# Initial temperature model#

**Subsection:** Initial temperature model#

**Parameter name:** List of model names#

**Default value:**

**Pattern:** [MultipleSelection S40RTS perturbation|SAVANI perturbation|adiabatic|adiabatic boundary|ascii data|ascii data layered|ascii profile|continental geotherm|function|harmonic perturbation|inclusion shape perturbation|lithosphere mask|mandelbox|patch on S40RTS|perturbed box|polar box|prescribed temperature|random Gaussian perturbation|spherical gaussian perturbation|spherical hexagonal perturbation|world builder ]

**Documentation:** A comma-separated list of initial temperature models that will be used to initialize the temperature. These plugins are loaded in the order given, and modify the existing temperature field via the operators listed in ’List of model operators’.

The following initial temperature models are available:

‘S40RTS perturbation’: An initial temperature field in which the temperature is perturbed following the S20RTS or S40RTS shear wave velocity model by Ritsema and others, which can be downloaded here \url{http://www.earth.lsa.umich.edu/~jritsema/research.html}. Information on the vs model can be found in Ritsema, J., Deuss, A., van Heijst, H.J. & Woodhouse, J.H., 2011. S40RTS: a degree-40 shear-velocity model for the mantle from new Rayleigh wave dispersion, teleseismic traveltime and normal-mode splitting function measurements, Geophys. J. Int. 184, 1223-1236. The scaling between the shear wave perturbation and the density perturbation can be constant and set by the user with the ’Vs to density scaling’ parameter or depth-dependent and read in from a file. To convert density the user can specify the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The scaling is as follows: \(\delta \ln \rho (r,\theta,\phi) = \xi \cdot \delta \ln v_s(r,\theta, \phi)\) and \(\delta T(r,\theta,\phi) = - \frac{1}{\alpha} \delta \ln \rho(r,\theta,\phi)\). \(\xi\) is the ‘vs to density scaling’ parameter and \(\alpha\) is the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The temperature perturbation is added to an otherwise constant temperature (incompressible model) or adiabatic reference profile (compressible model). If a depth is specified in ’Remove temperature heterogeneity down to specified depth’, there is no temperature perturbation prescribed down to that depth. Note the required file format if the vs to density scaling is read in from a file: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of points in the reference state as for example ’# POINTS: 3’. Following the comment lines there has to be a single line containing the names of all data columns, separated by arbitrarily many spaces. Column names are not allowed to contain spaces. The file can contain unnecessary columns, but for this plugin it needs to at least provide the columns named ‘depth’ and ‘vs_to_density’. Note that the data lines in the file need to be sorted in order of increasing depth from 0 to the maximal depth in the model domain. Points in the model that are outside of the provided depth range will be assigned the maximum or minimum depth values, respectively. Points do not need to be equidistant, but the computation of properties is optimized in speed if they are. If the plugin is used in 2d it will use an equatorial slice of the seismic tomography model.

‘SAVANI perturbation’: An initial temperature field in which the temperature is perturbed following the SAVANI shear wave velocity model by Auer and others, which can be downloaded here \url{http://n.ethz.ch/~auerl/savani.tar.bz2}. Information on the vs model can be found in Auer, L., Boschi, L., Becker, T.W., Nissen-Meyer, T. & Giardini, D., 2014. Savani: A variable resolution whole-mantle model of anisotropic shear velocity variations based on multiple data sets. Journal of Geophysical Research: Solid Earth 119.4 (2014): 3006-3034. The scaling between the shear wave perturbation and the density perturbation can be constant and set by the user with the ’Vs to density scaling’ parameter or depth-dependent and read in from a file. To convert density the user can specify the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The scaling is as follows: \(\delta \ln \rho (r,\theta,\phi) = \xi \cdot \delta \ln v_s(r,\theta, \phi)\) and \(\delta T(r,\theta,\phi) = - \frac{1}{\alpha} \delta \ln \rho(r,\theta,\phi)\). \(\xi\) is the ‘vs to density scaling’ parameter and \(\alpha\) is the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The temperature perturbation is added to an otherwise constant temperature (incompressible model) or adiabatic reference profile (compressible model).If a depth is specified in ’Remove temperature heterogeneity down to specified depth’, there is no temperature perturbation prescribed down to that depth. Note the required file format if the vs to density scaling is read in from a file: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of points in the reference state as for example ’# POINTS: 3’. Following the comment lines there has to be a single line containing the names of all data columns, separated by arbitrarily many spaces. Column names are not allowed to contain spaces. The file can contain unnecessary columns, but for this plugin it needs to at least provide the columns named ‘depth’ and ‘vs_to_density’. Note that the data lines in the file need to be sorted in order of increasing depth from 0 to the maximal depth in the model domain. Points in the model that are outside of the provided depth range will be assigned the maximum or minimum depth values, respectively. Points do not need to be equidistant, but the computation of properties is optimized in speed if they are.

‘adiabatic’: Temperature is prescribed as an adiabatic profile with upper and lower thermal boundary layers, whose ages are given as input parameters. Note that this plugin uses the ’Adiabatic conditions model’ to compute the adiabat. Thus, the results depend on variables defined outside of this specific subsection; e.g. the globally defined ’Adiabatic surface temperature’, and the variables defined in the ’Material model’ section including densities, heat capacities and thermal expansivities.

‘adiabatic boundary’: An initial temperature condition that allows for discretizing the model domain into two layers separated by a user-defined isothermal boundary. The user includes an input ascii data file that is formatted as 3 columns of ‘longitude(radians)’, ‘colatitude(radians)’, and ‘isotherm depth(meters)’, where ‘isotherm depth’ represents the depth of an initial temperature of 1673.15 K (by default). The first lines in the data file may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 69 121’. Note that the coordinates need to be sorted in a specific order: the ‘longitude’ coordinate needs to ascend first, followed by the ‘colatitude’ coordinate in order to assign the correct data (isotherm depth) to the prescribed coordinates. The temperature is defined from the surface (273.15 K) to the isotherm depth (1673.15 K) as a linear gradient. Below the isotherm depth the temperature increases approximately adiabatically (0.0005 K per meter). This plugin should work for all geometry models, but is currently only tested for spherical models.

‘ascii data’: Implementation of a model in which the initial temperature is derived from files containing data in ascii format. Note the required format of the input data: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 3 3’. The order of the data columns has to be ‘x’, ‘y’, ‘Temperature [K]’ in a 2d model and ‘x’, ‘y’, ‘z’, ‘Temperature [K]’ in a 3d model, which means that there has to be a single column containing the temperature. Note that the data in the input files need to be sorted in a specific order: the first coordinate needs to ascend first, followed by the second and the third at last in order to assign the correct data to the prescribed coordinates. If you use a spherical model, then the assumed grid changes. ‘x’ will be replaced by the radial distance of the point to the bottom of the model, ‘y’ by the azimuth angle and ‘z’ by the polar angle measured positive from the north pole. The grid will be assumed to be a latitude-longitude grid. Note that the order of spherical coordinates is ‘r’, ‘phi’, ‘theta’ and not ‘r’, ‘theta’, ‘phi’, since this allows for dimension independent expressions.

‘ascii data layered’: Implementation of a model in which the initial temperature is derived from files containing data in ascii format. Each file defines a surface on which temperature is defined. Between the surfaces, the temperatures can be chosen to be constant (with a value defined by the nearest shallower surface), or linearly interpolated between surfaces. Note the required format of the input ascii data file: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 3 3’. The order of the data columns has to be ‘x’, ‘y’, ‘Temperature [K]’ in a 2d model and ‘x’, ‘y’, ‘z’, ‘Temperature [K]’ in a 3d model; i.e. the last two columns always contain the position of the isotherm along the vertical direction, and the temperature at that point. The first column needs to ascend first, followed by the second in order to assign the correct data to the prescribed coordinates. If you use a spherical model, then the assumed grid changes. ‘x’ will be replaced by the azimuth angle and ‘y’ (if 3d) by the polar angle measured positive from the north pole. The last column will be the distance of the point from the origin (i.e. radial position). The grid in this case will be a latitude-longitude grid. Note that the order of spherical coordinates in 3d is ‘phi’, ‘theta’, ‘r’, ‘T’and not ‘theta’, ‘phi’, ‘r’, ‘T’ as this is more consistent with other ASPECT plugins. Outside of the region defined by the grid, the plugin will use the value at the edge of the region.

‘ascii profile’: Implementation of a model in which the initial temperature is read from a file that provides these values as a function of depth. Note the required format of the input data: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of points in the temperature profile, for example ‘# POINTS: 10’. Following the comment lines, there has to be a single line containing the names of all data columns, separated by arbitrarily many spaces. Column names are not allowed to contain spaces. The file can contain unnecessary columns, but for this plugin it needs to at least provide columns named ‘depth’ and‘temperature’.Note that the data lines in the file need to be sorted in order of increasing depth from 0 to the maximal depth in the model domain. Points in the model that are outside of the provided depth range will be assigned the maximum or minimum depth values, respectively. Points do not need to be equidistant, but the computation of properties is optimized in speed if they are.

‘continental geotherm’: This is a temperature initial condition that computes a continental geotherm based on the solution of the steady-state conductive equation \(k\frac{d^2 T}{dy^2}+\rho H = 0\) as described in e.g. Turcotte and Schubert, Ch. 4.6, or Chapman (1986). As boundary conditions, we take the surface temperature and the temperature of the Lithosphere-Asthenosphere Boundary (LAB). The geotherm is computed for a homogeneous lithosphere composed of an upper crust, lower crust and mantle layer. The crustal layers are assumed to have a constant radioactive heating, and all layers are assumed to have a constant thermal conductivity. Layer thicknesses, surface temperature and LAB temperature should be specified by the user. For consistency, the density, heat production and thermal conductivity of each layer are read from the visco plastic material model and the compositional heating model. For any depths below the depth of the LAB, a unrealistically high temperature is returned, such that this plugin can be combined with another temperature plugin through the ’minimum’ operator. Note that the current implementation only works for a 3-layer lithosphere, even though in principle the heat conduction equation can be solved for any number of layers. The naming of the compositional fields that represent the layers is also very specific, namely ‘upper_crust’, ‘lower_crust’, and ‘lithospheric_mantle’. Make sure the top and bottom temperatures of the lithosphere agree with temperatures set in for example the temperature boundary conditions.

‘function’: Specify the initial temperature in terms of an explicit formula. The format of these functions follows the syntax understood by the muparser library, see A note on the syntax of formulas in input files.

‘harmonic perturbation’: An initial temperature field in which the temperature is perturbed following a harmonic function (spherical harmonic or sine depending on geometry and dimension) in lateral and radial direction from an otherwise constant temperature (incompressible model) or adiabatic reference profile (compressible model).

‘inclusion shape perturbation’: An initial temperature field in which there is an inclusion in a constant-temperature box field. The size, shape, gradient, position, and temperature of the inclusion are defined by parameters.

‘lithosphere mask’: Implementation of a model in which the initial temperature is set to a specified lithosphere temperature above the lithosphere-asthenosphere boundary (specified by an ascii file or maximum lithosphere depth value). Below this the initial temperature is set as NaN. Note the required format of the input data file: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of grid points in each dimension as for example ’# POINTS: 3 3’. For a spherical model, the order of the data columns has to be ’phi’, ’theta’, ’depth (m)’, where phi is the azimuth angle and theta is the polar angle measured positive from the north pole. This plug-in can be combined with another using the ’replace if valid’ operator.

‘mandelbox’: Fractal-shaped temperature field.

‘patch on S40RTS’: Implementation of a model in which the initial temperature is derived from a file containing shear wave velocity perturbations in ascii format (e.g. a high resolution upper mantle tomography) combined with S40RTS. Note the required format of the input ascii input data: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of grid points in each dimension as for example ’# POINTS: 3 3 3’. The order of the data columns has to be ‘x’, ‘y’, ‘z’, ’Vs Perturbation’ in a 3d model, which means that there has to be a single column containing the temperature. Note that the data in the input files need to be sorted in a specific order: the first coordinate needs to ascend first, followed by the second and the third at last in order to assign the correct data to the prescribed coordinates. In the spherical model data will be handled as Cartesian, however, ‘x’ will be replaced by the radial distance of the point to the bottom of the model, ‘y’ by the azimuth angle and ‘z’ by the polar angle measured positive from the north pole. The grid will be assumed to be a latitude-longitude grid. Note that the order of spherical coordinates is ‘r’, ‘phi’, ‘theta’ and not ‘r’, ‘theta’, ‘phi’, since this allows for dimension independent expressions. See S40RTS documentation for details on input parameters in the S40RTS perturbation subsection. The boundary between the two tomography models is smoothed using a depth weighted combination of Vs values within the region of smoothing.

‘perturbed box’: An initial temperature field in which the temperature is perturbed slightly from an otherwise constant value equal to one. The perturbation is chosen in such a way that the initial temperature is constant to one along the entire boundary.

‘polar box’: An initial temperature field in which the temperature is perturbed slightly from an otherwise constant value equal to one. The perturbation is such that there are two poles on opposing corners of the box.

‘prescribed temperature’: This model fixes the initial temperature to the prescribed temperature outputs computed by the material model. This only works if the material model implements prescribed temperature outputs.

‘random Gaussian perturbation’: An initial temperature field in which the temperature is perturbed from a temperature of zero following a given number of Gaussian perturbations placed randomly throughout the model domain. The number, width, and maximum magnitude of the perturbations can be chosen as model parameters. This plugin is meant to be used in combination with another initial temperature model that determines the background temperature (such as the ’function’ or the ’adiabatic’ plugin) using the ’add’ operator to combine them.

‘spherical gaussian perturbation’: An initial temperature field in which the temperature is perturbed by a single Gaussian added to an otherwise spherically symmetric state. Additional parameters are read from the parameter file in subsection ’Spherical gaussian perturbation’.

‘spherical hexagonal perturbation’: An initial temperature field in which the temperature is perturbed following an \(N\)-fold pattern in a specified direction from an otherwise spherically symmetric state. The class’s name comes from previous versions when the only option was \(N=6\).

‘world builder’: Specify the initial temperature through the World Builder. More information on the World Builder can be found at \url{https://geodynamicworldbuilder.github.io}. Make sure to specify the location of the World Builder file in the parameter ’World builder file’.

**Parameter name:** List of model operators#

**Default value:** add

**Pattern:** [MultipleSelection add|subtract|minimum|maximum|replace if valid ]

**Documentation:** A comma-separated list of operators that will be used to append the listed temperature models onto the previous models. If only one operator is given, the same operator is applied to all models.

**Parameter name:** Model name#

**Default value:** unspecified

**Pattern:** [Selection S40RTS perturbation|SAVANI perturbation|adiabatic|adiabatic boundary|ascii data|ascii data layered|ascii profile|continental geotherm|function|harmonic perturbation|inclusion shape perturbation|lithosphere mask|mandelbox|patch on S40RTS|perturbed box|polar box|prescribed temperature|random Gaussian perturbation|spherical gaussian perturbation|spherical hexagonal perturbation|world builder|unspecified ]

**Documentation:** Select one of the following models:

‘S40RTS perturbation’: An initial temperature field in which the temperature is perturbed following the S20RTS or S40RTS shear wave velocity model by Ritsema and others, which can be downloaded here \url{http://www.earth.lsa.umich.edu/~jritsema/research.html}. Information on the vs model can be found in Ritsema, J., Deuss, A., van Heijst, H.J. & Woodhouse, J.H., 2011. S40RTS: a degree-40 shear-velocity model for the mantle from new Rayleigh wave dispersion, teleseismic traveltime and normal-mode splitting function measurements, Geophys. J. Int. 184, 1223-1236. The scaling between the shear wave perturbation and the density perturbation can be constant and set by the user with the ’Vs to density scaling’ parameter or depth-dependent and read in from a file. To convert density the user can specify the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The scaling is as follows: \(\delta \ln \rho (r,\theta,\phi) = \xi \cdot \delta \ln v_s(r,\theta, \phi)\) and \(\delta T(r,\theta,\phi) = - \frac{1}{\alpha} \delta \ln \rho(r,\theta,\phi)\). \(\xi\) is the ‘vs to density scaling’ parameter and \(\alpha\) is the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The temperature perturbation is added to an otherwise constant temperature (incompressible model) or adiabatic reference profile (compressible model). If a depth is specified in ’Remove temperature heterogeneity down to specified depth’, there is no temperature perturbation prescribed down to that depth. Note the required file format if the vs to density scaling is read in from a file: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of points in the reference state as for example ’# POINTS: 3’. Following the comment lines there has to be a single line containing the names of all data columns, separated by arbitrarily many spaces. Column names are not allowed to contain spaces. The file can contain unnecessary columns, but for this plugin it needs to at least provide the columns named ‘depth’ and ‘vs_to_density’. Note that the data lines in the file need to be sorted in order of increasing depth from 0 to the maximal depth in the model domain. Points in the model that are outside of the provided depth range will be assigned the maximum or minimum depth values, respectively. Points do not need to be equidistant, but the computation of properties is optimized in speed if they are. If the plugin is used in 2d it will use an equatorial slice of the seismic tomography model.

‘SAVANI perturbation’: An initial temperature field in which the temperature is perturbed following the SAVANI shear wave velocity model by Auer and others, which can be downloaded here \url{http://n.ethz.ch/~auerl/savani.tar.bz2}. Information on the vs model can be found in Auer, L., Boschi, L., Becker, T.W., Nissen-Meyer, T. & Giardini, D., 2014. Savani: A variable resolution whole-mantle model of anisotropic shear velocity variations based on multiple data sets. Journal of Geophysical Research: Solid Earth 119.4 (2014): 3006-3034. The scaling between the shear wave perturbation and the density perturbation can be constant and set by the user with the ’Vs to density scaling’ parameter or depth-dependent and read in from a file. To convert density the user can specify the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The scaling is as follows: \(\delta \ln \rho (r,\theta,\phi) = \xi \cdot \delta \ln v_s(r,\theta, \phi)\) and \(\delta T(r,\theta,\phi) = - \frac{1}{\alpha} \delta \ln \rho(r,\theta,\phi)\). \(\xi\) is the ‘vs to density scaling’ parameter and \(\alpha\) is the ’Thermal expansion coefficient in initial temperature scaling’ parameter. The temperature perturbation is added to an otherwise constant temperature (incompressible model) or adiabatic reference profile (compressible model).If a depth is specified in ’Remove temperature heterogeneity down to specified depth’, there is no temperature perturbation prescribed down to that depth. Note the required file format if the vs to density scaling is read in from a file: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of points in the reference state as for example ’# POINTS: 3’. Following the comment lines there has to be a single line containing the names of all data columns, separated by arbitrarily many spaces. Column names are not allowed to contain spaces. The file can contain unnecessary columns, but for this plugin it needs to at least provide the columns named ‘depth’ and ‘vs_to_density’. Note that the data lines in the file need to be sorted in order of increasing depth from 0 to the maximal depth in the model domain. Points in the model that are outside of the provided depth range will be assigned the maximum or minimum depth values, respectively. Points do not need to be equidistant, but the computation of properties is optimized in speed if they are.

‘adiabatic’: Temperature is prescribed as an adiabatic profile with upper and lower thermal boundary layers, whose ages are given as input parameters. Note that this plugin uses the ’Adiabatic conditions model’ to compute the adiabat. Thus, the results depend on variables defined outside of this specific subsection; e.g. the globally defined ’Adiabatic surface temperature’, and the variables defined in the ’Material model’ section including densities, heat capacities and thermal expansivities.

‘adiabatic boundary’: An initial temperature condition that allows for discretizing the model domain into two layers separated by a user-defined isothermal boundary. The user includes an input ascii data file that is formatted as 3 columns of ‘longitude(radians)’, ‘colatitude(radians)’, and ‘isotherm depth(meters)’, where ‘isotherm depth’ represents the depth of an initial temperature of 1673.15 K (by default). The first lines in the data file may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 69 121’. Note that the coordinates need to be sorted in a specific order: the ‘longitude’ coordinate needs to ascend first, followed by the ‘colatitude’ coordinate in order to assign the correct data (isotherm depth) to the prescribed coordinates. The temperature is defined from the surface (273.15 K) to the isotherm depth (1673.15 K) as a linear gradient. Below the isotherm depth the temperature increases approximately adiabatically (0.0005 K per meter). This plugin should work for all geometry models, but is currently only tested for spherical models.

‘ascii data’: Implementation of a model in which the initial temperature is derived from files containing data in ascii format. Note the required format of the input data: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 3 3’. The order of the data columns has to be ‘x’, ‘y’, ‘Temperature [K]’ in a 2d model and ‘x’, ‘y’, ‘z’, ‘Temperature [K]’ in a 3d model, which means that there has to be a single column containing the temperature. Note that the data in the input files need to be sorted in a specific order: the first coordinate needs to ascend first, followed by the second and the third at last in order to assign the correct data to the prescribed coordinates. If you use a spherical model, then the assumed grid changes. ‘x’ will be replaced by the radial distance of the point to the bottom of the model, ‘y’ by the azimuth angle and ‘z’ by the polar angle measured positive from the north pole. The grid will be assumed to be a latitude-longitude grid. Note that the order of spherical coordinates is ‘r’, ‘phi’, ‘theta’ and not ‘r’, ‘theta’, ‘phi’, since this allows for dimension independent expressions.

‘ascii data layered’: Implementation of a model in which the initial temperature is derived from files containing data in ascii format. Each file defines a surface on which temperature is defined. Between the surfaces, the temperatures can be chosen to be constant (with a value defined by the nearest shallower surface), or linearly interpolated between surfaces. Note the required format of the input ascii data file: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 3 3’. The order of the data columns has to be ‘x’, ‘y’, ‘Temperature [K]’ in a 2d model and ‘x’, ‘y’, ‘z’, ‘Temperature [K]’ in a 3d model; i.e. the last two columns always contain the position of the isotherm along the vertical direction, and the temperature at that point. The first column needs to ascend first, followed by the second in order to assign the correct data to the prescribed coordinates. If you use a spherical model, then the assumed grid changes. ‘x’ will be replaced by the azimuth angle and ‘y’ (if 3d) by the polar angle measured positive from the north pole. The last column will be the distance of the point from the origin (i.e. radial position). The grid in this case will be a latitude-longitude grid. Note that the order of spherical coordinates in 3d is ‘phi’, ‘theta’, ‘r’, ‘T’and not ‘theta’, ‘phi’, ‘r’, ‘T’ as this is more consistent with other ASPECT plugins. Outside of the region defined by the grid, the plugin will use the value at the edge of the region.

‘ascii profile’: Implementation of a model in which the initial temperature is read from a file that provides these values as a function of depth. Note the required format of the input data: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of points in the temperature profile, for example ‘# POINTS: 10’. Following the comment lines, there has to be a single line containing the names of all data columns, separated by arbitrarily many spaces. Column names are not allowed to contain spaces. The file can contain unnecessary columns, but for this plugin it needs to at least provide columns named ‘depth’ and‘temperature’.Note that the data lines in the file need to be sorted in order of increasing depth from 0 to the maximal depth in the model domain. Points in the model that are outside of the provided depth range will be assigned the maximum or minimum depth values, respectively. Points do not need to be equidistant, but the computation of properties is optimized in speed if they are.

‘continental geotherm’: This is a temperature initial condition that computes a continental geotherm based on the solution of the steady-state conductive equation \(k\frac{d^2 T}{dy^2}+\rho H = 0\) as described in e.g. Turcotte and Schubert, Ch. 4.6, or Chapman (1986). As boundary conditions, we take the surface temperature and the temperature of the Lithosphere-Asthenosphere Boundary (LAB). The geotherm is computed for a homogeneous lithosphere composed of an upper crust, lower crust and mantle layer. The crustal layers are assumed to have a constant radioactive heating, and all layers are assumed to have a constant thermal conductivity. Layer thicknesses, surface temperature and LAB temperature should be specified by the user. For consistency, the density, heat production and thermal conductivity of each layer are read from the visco plastic material model and the compositional heating model. For any depths below the depth of the LAB, a unrealistically high temperature is returned, such that this plugin can be combined with another temperature plugin through the ’minimum’ operator. Note that the current implementation only works for a 3-layer lithosphere, even though in principle the heat conduction equation can be solved for any number of layers. The naming of the compositional fields that represent the layers is also very specific, namely ‘upper_crust’, ‘lower_crust’, and ‘lithospheric_mantle’. Make sure the top and bottom temperatures of the lithosphere agree with temperatures set in for example the temperature boundary conditions.

‘function’: Specify the initial temperature in terms of an explicit formula. The format of these functions follows the syntax understood by the muparser library, see A note on the syntax of formulas in input files.

‘harmonic perturbation’: An initial temperature field in which the temperature is perturbed following a harmonic function (spherical harmonic or sine depending on geometry and dimension) in lateral and radial direction from an otherwise constant temperature (incompressible model) or adiabatic reference profile (compressible model).

‘inclusion shape perturbation’: An initial temperature field in which there is an inclusion in a constant-temperature box field. The size, shape, gradient, position, and temperature of the inclusion are defined by parameters.

‘lithosphere mask’: Implementation of a model in which the initial temperature is set to a specified lithosphere temperature above the lithosphere-asthenosphere boundary (specified by an ascii file or maximum lithosphere depth value). Below this the initial temperature is set as NaN. Note the required format of the input data file: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of grid points in each dimension as for example ’# POINTS: 3 3’. For a spherical model, the order of the data columns has to be ’phi’, ’theta’, ’depth (m)’, where phi is the azimuth angle and theta is the polar angle measured positive from the north pole. This plug-in can be combined with another using the ’replace if valid’ operator.

‘mandelbox’: Fractal-shaped temperature field.

‘patch on S40RTS’: Implementation of a model in which the initial temperature is derived from a file containing shear wave velocity perturbations in ascii format (e.g. a high resolution upper mantle tomography) combined with S40RTS. Note the required format of the input ascii input data: The first lines may contain any number of comments if they begin with ’#’, but one of these lines needs to contain the number of grid points in each dimension as for example ’# POINTS: 3 3 3’. The order of the data columns has to be ‘x’, ‘y’, ‘z’, ’Vs Perturbation’ in a 3d model, which means that there has to be a single column containing the temperature. Note that the data in the input files need to be sorted in a specific order: the first coordinate needs to ascend first, followed by the second and the third at last in order to assign the correct data to the prescribed coordinates. In the spherical model data will be handled as Cartesian, however, ‘x’ will be replaced by the radial distance of the point to the bottom of the model, ‘y’ by the azimuth angle and ‘z’ by the polar angle measured positive from the north pole. The grid will be assumed to be a latitude-longitude grid. Note that the order of spherical coordinates is ‘r’, ‘phi’, ‘theta’ and not ‘r’, ‘theta’, ‘phi’, since this allows for dimension independent expressions. See S40RTS documentation for details on input parameters in the S40RTS perturbation subsection. The boundary between the two tomography models is smoothed using a depth weighted combination of Vs values within the region of smoothing.

‘perturbed box’: An initial temperature field in which the temperature is perturbed slightly from an otherwise constant value equal to one. The perturbation is chosen in such a way that the initial temperature is constant to one along the entire boundary.

‘polar box’: An initial temperature field in which the temperature is perturbed slightly from an otherwise constant value equal to one. The perturbation is such that there are two poles on opposing corners of the box.

‘prescribed temperature’: This model fixes the initial temperature to the prescribed temperature outputs computed by the material model. This only works if the material model implements prescribed temperature outputs.

‘random Gaussian perturbation’: An initial temperature field in which the temperature is perturbed from a temperature of zero following a given number of Gaussian perturbations placed randomly throughout the model domain. The number, width, and maximum magnitude of the perturbations can be chosen as model parameters. This plugin is meant to be used in combination with another initial temperature model that determines the background temperature (such as the ’function’ or the ’adiabatic’ plugin) using the ’add’ operator to combine them.

‘spherical gaussian perturbation’: An initial temperature field in which the temperature is perturbed by a single Gaussian added to an otherwise spherically symmetric state. Additional parameters are read from the parameter file in subsection ’Spherical gaussian perturbation’.

‘spherical hexagonal perturbation’: An initial temperature field in which the temperature is perturbed following an \(N\)-fold pattern in a specified direction from an otherwise spherically symmetric state. The class’s name comes from previous versions when the only option was \(N=6\).

‘world builder’: Specify the initial temperature through the World Builder. More information on the World Builder can be found at \url{https://geodynamicworldbuilder.github.io}. Make sure to specify the location of the World Builder file in the parameter ’World builder file’.

**Warning**: This parameter provides an old and deprecated way of specifying initial temperature models and shouldn’t be used. Please use ’List of model names’ instead.

**Subsection:** Initial temperature model / Adiabatic#

**Parameter name:** Age bottom boundary layer#

**Default value:** 0.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The age of the lower thermal boundary layer, used for the calculation of the half-space cooling model temperature. Units: years if the ’Use years in output instead of seconds’ parameter is set; seconds otherwise.

**Parameter name:** Age top boundary layer#

**Default value:** 0.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The age of the upper thermal boundary layer, used for the calculation of the half-space cooling model temperature. Units: years if the ’Use years in output instead of seconds’ parameter is set; seconds otherwise.

**Parameter name:** Amplitude#

**Default value:** 0.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The amplitude (in K) of the initial spherical temperature perturbation at the bottom of the model domain. This perturbation will be added to the adiabatic temperature profile, but not to the bottom thermal boundary layer. Instead, the maximum of the perturbation and the bottom boundary layer temperature will be used.

**Parameter name:** Cooling model#

**Default value:** half-space cooling

**Pattern:** [Selection half-space cooling|plate cooling ]

**Documentation:** Whether to use the half space cooling model or the plate cooling model

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/adiabatic/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** adiabatic.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Lithosphere thickness#

**Default value:** 125e3

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** Thickness of the lithosphere for plate cooling model. \si{\m}

**Parameter name:** Position#

**Default value:** center

**Pattern:** [Selection center ]

**Documentation:** Where the initial temperature perturbation should be placed. If ‘center’ is given, then the perturbation will be centered along a ‘midpoint’ of some sort of the bottom boundary. For example, in the case of a box geometry, this is the center of the bottom face; in the case of a spherical shell geometry, it is along the inner surface halfway between the bounding radial lines.

**Parameter name:** Radius#

**Default value:** 0.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The Radius (in m) of the initial spherical temperature perturbation at the bottom of the model domain.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Parameter name:** Subadiabaticity#

**Default value:** 0.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** If this value is larger than 0, the initial temperature profile will not be adiabatic, but subadiabatic. This value gives the maximal deviation from adiabaticity. Set to 0 for an adiabatic temperature profile. Units: \si{\kelvin}.

The function object in the Function subsection represents the compositional fields that will be used as a reference profile for calculating the thermal diffusivity. This function is one-dimensional and depends only on depth. The format of this functions follows the syntax understood by the muparser library, see A note on the syntax of formulas in input files.

**Parameter name:** Top boundary layer age model#

**Default value:** constant

**Pattern:** [Selection constant|function|ascii data ]

**Documentation:** How to define the age of the top thermal boundary layer. Options are: ’constant’ for a constant age specified by the parameter ’Age top boundary layer’; ’function’ for an analytical function describing the age as specified in the subsection ’Age function’; and ’ascii data’ to use an ’ascii data’ file specified by the parameter ’Data file name’.

**Subsection:** Initial temperature model / Adiabatic / Age function#

**Parameter name:** Coordinate system#

**Default value:** cartesian

**Pattern:** [Selection cartesian|spherical ]

**Documentation:** A selection that determines the assumed coordinate system for the function variables. Allowed values are ‘cartesian’, ‘spherical’, and ‘depth’. ‘spherical’ coordinates are interpreted as r,phi or r,phi,theta in 2d/3d respectively with theta being the polar angle. ‘depth’ will create a function, in which only the first parameter is non-zero, which is interpreted to be the depth of the point.

**Parameter name:** Function constants#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Sometimes it is convenient to use symbolic constants in the expression that describes the function, rather than having to use its numeric value everywhere the constant appears. These values can be defined using this parameter, in the form ‘var1=value1, var2=value2, …’.

A typical example would be to set this runtime parameter to ‘pi=3.1415926536’ and then use ‘pi’ in the expression of the actual formula. (That said, for convenience this class actually defines both ‘pi’ and ‘Pi’ by default, but you get the idea.)

**Parameter name:** Function expression#

**Default value:** 0

**Pattern:** [Anything]

**Documentation:** The formula that denotes the function you want to evaluate for particular values of the independent variables. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, -1)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/.

If the function you are describing represents a vector-valued function with multiple components, then separate the expressions for individual components by a semicolon.

**Parameter name:** Variable names#

**Default value:** x,y,t

**Pattern:** [Anything]

**Documentation:** The names of the variables as they will be used in the function, separated by commas. By default, the names of variables at which the function will be evaluated are ‘x’ (in 1d), ‘x,y’ (in 2d) or ‘x,y,z’ (in 3d) for spatial coordinates and ‘t’ for time. You can then use these variable names in your function expression and they will be replaced by the values of these variables at which the function is currently evaluated. However, you can also choose a different set of names for the independent variables at which to evaluate your function expression. For example, if you work in spherical coordinates, you may wish to set this input parameter to ‘r,phi,theta,t’ and then use these variable names in your function expression.

**Subsection:** Initial temperature model / Adiabatic / Function#

**Parameter name:** Function constants#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Sometimes it is convenient to use symbolic constants in the expression that describes the function, rather than having to use its numeric value everywhere the constant appears. These values can be defined using this parameter, in the form ‘var1=value1, var2=value2, …’.

A typical example would be to set this runtime parameter to ‘pi=3.1415926536’ and then use ‘pi’ in the expression of the actual formula. (That said, for convenience this class actually defines both ‘pi’ and ‘Pi’ by default, but you get the idea.)

**Parameter name:** Function expression#

**Default value:** 0

**Pattern:** [Anything]

**Documentation:** The formula that denotes the function you want to evaluate for particular values of the independent variables. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, -1)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/.

If the function you are describing represents a vector-valued function with multiple components, then separate the expressions for individual components by a semicolon.

**Parameter name:** Variable names#

**Default value:** x,t

**Pattern:** [Anything]

**Documentation:** The names of the variables as they will be used in the function, separated by commas. By default, the names of variables at which the function will be evaluated are ‘x’ (in 1d), ‘x,y’ (in 2d) or ‘x,y,z’ (in 3d) for spatial coordinates and ‘t’ for time. You can then use these variable names in your function expression and they will be replaced by the values of these variables at which the function is currently evaluated. However, you can also choose a different set of names for the independent variables at which to evaluate your function expression. For example, if you work in spherical coordinates, you may wish to set this input parameter to ‘r,phi,theta,t’ and then use these variable names in your function expression.

**Subsection:** Initial temperature model / Adiabatic boundary#

**Parameter name:** Adiabatic temperature gradient#

**Default value:** 0.0005

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the adiabatic temperature gradient. Units: \si{\kelvin\per\meter}.

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/adiabatic-boundary/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** adiabatic_boundary.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Isotherm temperature#

**Default value:** 1673.15

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the isothermal boundary temperature. Units: \si{\kelvin}.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Parameter name:** Surface temperature#

**Default value:** 273.15

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the surface temperature. Units: \si{\kelvin}.

**Subsection:** Initial temperature model / Ascii data model#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/ascii-data/test/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** initial_isotherm_500K_box_3d.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Data file names#

**Default value:** initial_isotherm_500K_box_3d.txt

**Pattern:** [List of <[Anything]> of length 0…4294967295 (inclusive)]

**Documentation:** The file names of the model data (comma separated).

**Parameter name:** First point on slice#

**Default value:** 0.0,1.0,0.0

**Pattern:** [Anything]

**Documentation:** Point that determines the plane in which the 2d slice lies in. This variable is only used if ’Slice dataset in 2d plane’ is true. The slice will go through this point, the point defined by the parameter ’Second point on slice’, and the center of the model domain. After the rotation, this first point will lie along the (0,1,0) axis of the coordinate system. The coordinates of the point have to be given in Cartesian coordinates.

**Parameter name:** Interpolation scheme#

**Default value:** linear

**Pattern:** [Selection piecewise constant|linear ]

**Documentation:** Method to interpolate between layer boundaries. Select from piecewise constant or linear. Piecewise constant takes the value from the nearest layer boundary above the data point. The linear option interpolates linearly between layer boundaries. Above and below the domain given by the layer boundaries, the values aregiven by the top and bottom layer boundary.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Parameter name:** Second point on slice#

**Default value:** 1.0,0.0,0.0

**Pattern:** [Anything]

**Documentation:** Second point that determines the plane in which the 2d slice lies in. This variable is only used if ’Slice dataset in 2d plane’ is true. The slice will go through this point, the point defined by the parameter ’First point on slice’, and the center of the model domain. The coordinates of the point have to be given in Cartesian coordinates.

**Parameter name:** Slice dataset in 2D plane#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether to use a 2d data slice of a 3d data file or the entire data file. Slicing a 3d dataset is only supported for 2d models.

**Subsection:** Initial temperature model / Ascii profile#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/ascii-profile/tests/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** simple_test.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Subsection:** Initial temperature model / Continental geotherm#

**Parameter name:** Layer thicknesses#

**Default value:** 30000.

**Pattern:** [List of <[Double 0…MAX_DOUBLE (inclusive)]> of length 0…4294967295 (inclusive)]

**Documentation:** List of the 3 thicknesses of the lithospheric layers ’upper_crust’, ’lower_crust’ and ’mantle_lithosphere’. If only one thickness is given, then the same thickness is used for all layers. Units: \si{meter}.

**Parameter name:** Lithosphere-Asthenosphere boundary isotherm#

**Default value:** 1673.15

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the isotherm that is assumed at the Lithosphere-Asthenosphere boundary. Units: \si{\kelvin}.

**Parameter name:** Surface temperature#

**Default value:** 273.15

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the surface temperature. Units: \si{\kelvin}.

**Subsection:** Initial temperature model / Function#

**Parameter name:** Coordinate system#

**Default value:** cartesian

**Pattern:** [Selection cartesian|spherical|depth ]

**Documentation:** A selection that determines the assumed coordinate system for the function variables. Allowed values are ‘cartesian’, ‘spherical’, and ‘depth’. ‘spherical’ coordinates are interpreted as r,phi or r,phi,theta in 2d/3d respectively with theta being the polar angle. ‘depth’ will create a function, in which only the first parameter is non-zero, which is interpreted to be the depth of the point.

**Parameter name:** Function constants#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Sometimes it is convenient to use symbolic constants in the expression that describes the function, rather than having to use its numeric value everywhere the constant appears. These values can be defined using this parameter, in the form ‘var1=value1, var2=value2, …’.

A typical example would be to set this runtime parameter to ‘pi=3.1415926536’ and then use ‘pi’ in the expression of the actual formula. (That said, for convenience this class actually defines both ‘pi’ and ‘Pi’ by default, but you get the idea.)

**Parameter name:** Function expression#

**Default value:** 0

**Pattern:** [Anything]

**Documentation:** The formula that denotes the function you want to evaluate for particular values of the independent variables. This expression may contain any of the usual operations such as addition or multiplication, as well as all of the common functions such as ‘sin’ or ‘cos’. In addition, it may contain expressions like ‘if(x>0, 1, -1)’ where the expression evaluates to the second argument if the first argument is true, and to the third argument otherwise. For a full overview of possible expressions accepted see the documentation of the muparser library at http://muparser.beltoforion.de/.

If the function you are describing represents a vector-valued function with multiple components, then separate the expressions for individual components by a semicolon.

**Parameter name:** Variable names#

**Default value:** x,y,t

**Pattern:** [Anything]

**Documentation:** The names of the variables as they will be used in the function, separated by commas. By default, the names of variables at which the function will be evaluated are ‘x’ (in 1d), ‘x,y’ (in 2d) or ‘x,y,z’ (in 3d) for spatial coordinates and ‘t’ for time. You can then use these variable names in your function expression and they will be replaced by the values of these variables at which the function is currently evaluated. However, you can also choose a different set of names for the independent variables at which to evaluate your function expression. For example, if you work in spherical coordinates, you may wish to set this input parameter to ‘r,phi,theta,t’ and then use these variable names in your function expression.

**Subsection:** Initial temperature model / Harmonic perturbation#

**Parameter name:** Lateral wave number one#

**Default value:** 3

**Pattern:** [Integer range -2147483648…2147483647 (inclusive)]

**Documentation:** Doubled first lateral wave number of the harmonic perturbation. Equals the spherical harmonic degree in 3d spherical shells. In all other cases one equals half of a sine period over the model domain. This allows for single up-/downswings. Negative numbers reverse the sign of the perturbation but are not allowed for the spherical harmonic case.

**Parameter name:** Lateral wave number two#

**Default value:** 2

**Pattern:** [Integer range -2147483648…2147483647 (inclusive)]

**Documentation:** Doubled second lateral wave number of the harmonic perturbation. Equals the spherical harmonic order in 3d spherical shells. In all other cases one equals half of a sine period over the model domain. This allows for single up-/downswings. Negative numbers reverse the sign of the perturbation.

**Parameter name:** Magnitude#

**Default value:** 1.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The magnitude of the Harmonic perturbation.

**Parameter name:** Reference temperature#

**Default value:** 1600.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The reference temperature that is perturbed by the harmonic function. Only used in incompressible models.

**Parameter name:** Vertical wave number#

**Default value:** 1

**Pattern:** [Integer range -2147483648…2147483647 (inclusive)]

**Documentation:** Doubled radial wave number of the harmonic perturbation. One equals half of a sine period over the model domain. This allows for single up-/downswings. Negative numbers reverse the sign of the perturbation.

**Subsection:** Initial temperature model / Inclusion shape perturbation#

**Parameter name:** Ambient temperature#

**Default value:** 1.0

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** The background temperature for the temperature field.

**Parameter name:** Center X#

**Default value:** 0.5

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** The X coordinate for the center of the shape.

**Parameter name:** Center Y#

**Default value:** 0.5

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** The Y coordinate for the center of the shape.

**Parameter name:** Center Z#

**Default value:** 0.5

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** The Z coordinate for the center of the shape. This is only necessary for three-dimensional fields.

**Parameter name:** Inclusion gradient#

**Default value:** constant

**Pattern:** [Selection gaussian|linear|constant ]

**Documentation:** The gradient of the inclusion to be generated.

**Parameter name:** Inclusion shape#

**Default value:** circle

**Pattern:** [Selection square|circle ]

**Documentation:** The shape of the inclusion to be generated.

**Parameter name:** Inclusion temperature#

**Default value:** 0.0

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** The temperature of the inclusion shape. This is only the true temperature in the case of the constant gradient. In all other cases, it gives one endpoint of the temperature gradient for the shape.

**Parameter name:** Shape radius#

**Default value:** 1.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The radius of the inclusion to be generated. For shapes with no radius (e.g. square), this will be the width, and for shapes with no width, this gives a general guideline for the size of the shape.

**Subsection:** Initial temperature model / Lithosphere Mask#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/lithosphere-mask/

**Pattern:** [DirectoryName]

**Documentation:** The path to the LAB depth data file

**Parameter name:** Depth specification method#

**Default value:** Value

**Pattern:** [Selection File|Value ]

**Documentation:** Method that is used to specify the depth of the lithosphere-asthenosphere boundary.

**Parameter name:** LAB depth filename#

**Default value:** LAB_CAM2016.txt

**Pattern:** [FileName (Type: input)]

**Documentation:** File from which the lithosphere-asthenosphere boundary depth data is read.

**Parameter name:** Lithosphere temperature#

**Default value:** 1600.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The initial temperature within lithosphere, applied abovethe maximum lithosphere depth.

**Parameter name:** Maximum lithosphere depth#

**Default value:** 200000.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** Units: \si{\meter}.The maximum depth of the lithosphere. The model will be NaNs below this depth.

**Subsection:** Initial temperature model / Patch on S40RTS#

**Parameter name:** Maximum grid depth#

**Default value:** 700000.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The maximum depth of the Vs ascii grid. The model will read in Vs from S40RTS below this depth.

**Parameter name:** Remove temperature heterogeneity down to specified depth#

**Default value:** -1.7976931348623157e+308

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** This will set the heterogeneity prescribed by the Vs ascii grid and S40RTS to zero down to the specified depth (in meters). Note that your resolution has to be adequate to capture this cutoff. For example if you specify a depth of 660km, but your closest spherical depth layers are only at 500km and 750km (due to a coarse resolution) it will only zero out heterogeneities down to 500km. Similar caution has to be taken when using adaptive meshing.

**Parameter name:** Smoothing length scale#

**Default value:** 200000.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The depth range (above maximum grid depth) over which to smooth. The boundary is smoothed using a depth weighted combination of Vs values from the ascii grid and S40RTS at each point in the region of smoothing.

**Subsection:** Initial temperature model / Patch on S40RTS / Ascii data model#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/patch-on-S40RTS/test/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** upper_shell_3d.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Subsection:** Initial temperature model / Random Gaussian perturbation#

**Parameter name:** Maximum magnitude#

**Default value:** 25.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The maximum magnitude of the Gaussian perturbation. For each perturbation, a random magnitude between plus and minus the maximum magnitude will be chosen. Units: \si{\kelvin}.

**Parameter name:** Number of perturbations#

**Default value:** 100

**Pattern:** [Integer range -2147483648…2147483647 (inclusive)]

**Documentation:** Total number of perturbations to be introduced into the model. Perturbations will be placed at random locations within the model domain.

**Parameter name:** Width#

**Default value:** 1000.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The Gaussian RMS width of the perturbations. Units: \si{\meter}.

**Subsection:** Initial temperature model / S40RTS perturbation#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/S40RTS/

**Pattern:** [DirectoryName]

**Documentation:** The path to the model data.

**Parameter name:** Initial condition file name#

**Default value:** S40RTS.sph

**Pattern:** [Anything]

**Documentation:** The file name of the spherical harmonics coefficients from Ritsema et al.

**Parameter name:** Maximum order#

**Default value:** 20

**Pattern:** [Integer range 0…2147483647 (inclusive)]

**Documentation:** The maximum order the users specify when reading the data file of spherical harmonic coefficients, which must be smaller than the maximum order the data file stored. This parameter will be used only if ’Specify a lower maximum order’ is set to true.

**Parameter name:** Reference temperature#

**Default value:** 1600.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The reference temperature that is perturbed by the spherical harmonic functions. Only used in incompressible models.

**Parameter name:** Remove degree 0 from perturbation#

**Default value:** true

**Pattern:** [Bool]

**Documentation:** Option to remove the degree zero component from the perturbation, which will ensure that the laterally averaged temperature for a fixed depth is equal to the background temperature.

**Parameter name:** Remove temperature heterogeneity down to specified depth#

**Default value:** -1.7976931348623157e+308

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** This will set the heterogeneity prescribed by S20RTS or S40RTS to zero down to the specified depth (in meters). Note that your resolution has to be adequate to capture this cutoff. For example if you specify a depth of 660km, but your closest spherical depth layers are only at 500km and 750km (due to a coarse resolution) it will only zero out heterogeneities down to 500km. Similar caution has to be taken when using adaptive meshing.

**Parameter name:** Specify a lower maximum order#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Option to use a lower maximum order when reading the data file of spherical harmonic coefficients. This is probably used for the faster tests or when the users only want to see the spherical harmonic pattern up to a certain order.

**Parameter name:** Spline knots depth file name#

**Default value:** Spline_knots.txt

**Pattern:** [Anything]

**Documentation:** The file name of the spline knot locations from Ritsema et al.

**Parameter name:** Thermal expansion coefficient in initial temperature scaling#

**Default value:** 2e-5

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the thermal expansion coefficient \(\beta\). Units: \si{\per\kelvin}.

**Parameter name:** Use thermal expansion coefficient from material model#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Option to take the thermal expansion coefficient from the material model instead of from what is specified in this section.

**Parameter name:** Vs to density scaling#

**Default value:** 0.25

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** This parameter specifies how the perturbation in shear wave velocity as prescribed by S20RTS or S40RTS is scaled into a density perturbation. See the general description of this model for more detailed information.

**Parameter name:** Vs to density scaling method#

**Default value:** constant

**Pattern:** [Selection file|constant ]

**Documentation:** Method that is used to specify how the vs-to-density scaling varies with depth.

**Subsection:** Initial temperature model / S40RTS perturbation / Ascii data vs to density model#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/S40RTS/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** vs_to_density_Steinberger.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Subsection:** Initial temperature model / SAVANI perturbation#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/SAVANI/

**Pattern:** [DirectoryName]

**Documentation:** The path to the model data.

**Parameter name:** Initial condition file name#

**Default value:** savani.dlnvs.60.m.ab

**Pattern:** [Anything]

**Documentation:** The file name of the spherical harmonics coefficients from Auer et al.

**Parameter name:** Maximum order#

**Default value:** 20

**Pattern:** [Integer range 0…2147483647 (inclusive)]

**Documentation:** The maximum order the users specify when reading the data file of spherical harmonic coefficients, which must be smaller than the maximum order the data file stored. This parameter will be used only if ’Specify a lower maximum order’ is set to true.

**Parameter name:** Reference temperature#

**Default value:** 1600.0

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The reference temperature that is perturbed by the spherical harmonic functions. Only used in incompressible models.

**Parameter name:** Remove degree 0 from perturbation#

**Default value:** true

**Pattern:** [Bool]

**Documentation:** Option to remove the degree zero component from the perturbation, which will ensure that the laterally averaged temperature for a fixed depth is equal to the background temperature.

**Parameter name:** Remove temperature heterogeneity down to specified depth#

**Default value:** -1.7976931348623157e+308

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** This will set the heterogeneity prescribed by SAVANI to zero down to the specified depth (in meters). Note that your resolution has to be adequate to capture this cutoff. For example if you specify a depth of 660km, but your closest spherical depth layers are only at 500km and 750km (due to a coarse resolution) it will only zero out heterogeneities down to 500km. Similar caution has to be taken when using adaptive meshing.

**Parameter name:** Specify a lower maximum order#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Option to use a lower maximum order when reading the data file of spherical harmonic coefficients. This is probably used for the faster tests or when the users only want to see the spherical harmonic pattern up to a certain order.

**Parameter name:** Spline knots depth file name#

**Default value:** Spline_knots.txt

**Pattern:** [Anything]

**Documentation:** The file name of the spline knots taken from the 28 spherical layers of SAVANI tomography model.

**Parameter name:** Thermal expansion coefficient in initial temperature scaling#

**Default value:** 2e-5

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The value of the thermal expansion coefficient \(\beta\). Units: \si{\per\kelvin}.

**Parameter name:** Use thermal expansion coefficient from material model#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Option to take the thermal expansion coefficient from the material model instead of from what is specified in this section.

**Parameter name:** Vs to density scaling#

**Default value:** 0.25

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** This parameter specifies how the perturbation in shear wave velocity as prescribed by SAVANI is scaled into a density perturbation. See the general description of this model for more detailed information.

**Parameter name:** Vs to density scaling method#

**Default value:** constant

**Pattern:** [Selection file|constant ]

**Documentation:** Method that is used to specify how the vs-to-density scaling varies with depth.

**Subsection:** Initial temperature model / SAVANI perturbation / Ascii data vs to density model#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/initial-temperature/S40RTS/

**Pattern:** [DirectoryName]

**Documentation:** The name of a directory that contains the model data. This path may either be absolute (if starting with a ‘/’) or relative to the current directory. The path may also include the special text ‘$ASPECT_SOURCE_DIR’ which will be interpreted as the path in which the ASPECT source files were located when ASPECT was compiled. This interpretation allows, for example, to reference files located in the ‘data/’ subdirectory of ASPECT.

**Parameter name:** Data file name#

**Default value:** vs_to_density_Steinberger.txt

**Pattern:** [Anything]

**Documentation:** The file name of the model data.

**Parameter name:** Scale factor#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Scalar factor, which is applied to the model data. You might want to use this to scale the input to a reference model. Another way to use this factor is to convert units of the input files. For instance, if you provide velocities in cm/yr set this factor to 0.01.

**Subsection:** Initial temperature model / Spherical gaussian perturbation#

**Parameter name:** Amplitude#

**Default value:** 0.01

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The amplitude of the perturbation.

**Parameter name:** Angle#

**Default value:** 0.

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The angle where the center of the perturbation is placed.

**Parameter name:** Filename for initial geotherm table#

**Default value:** initial-geotherm-table

**Pattern:** [FileName (Type: input)]

**Documentation:** The file from which the initial geotherm table is to be read. The format of the file is defined by what is read in source/initial_temperature/spherical_shell.cc.

**Parameter name:** Non-dimensional depth#

**Default value:** 0.7

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The non-dimensional radial distance where the center of the perturbation is placed.

**Parameter name:** Sigma#

**Default value:** 0.2

**Pattern:** [Double 0…MAX_DOUBLE (inclusive)]

**Documentation:** The standard deviation of the Gaussian perturbation.

**Parameter name:** Sign#

**Default value:** 1.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** The sign of the perturbation.

**Subsection:** Initial temperature model / Spherical hexagonal perturbation#

**Parameter name:** Angular mode#

**Default value:** 6

**Pattern:** [Integer range -2147483648…2147483647 (inclusive)]

**Documentation:** The number of convection cells with which to perturb the system.

**Parameter name:** Rotation offset#

**Default value:** -45.

**Pattern:** [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]

**Documentation:** Amount of clockwise rotation in degrees to apply to the perturbations. Default is set to -45 in order to provide backwards compatibility.