Material model#

Subsection: Material model#

Parameter name: Material averaging#

Default value: none

Pattern: [Selection none|arithmetic average|harmonic average|geometric average|pick largest|project to Q1|log average|harmonic average only viscosity|geometric average only viscosity|project to Q1 only viscosity ]

Documentation: Whether or not (and in the first case, how) to do any averaging of material model output data when constructing the linear systems for velocity/pressure, temperature, and compositions in each time step, as well as their corresponding preconditioners.

Possible choices: none|arithmetic average|harmonic average|geometric average|pick largest|project to Q1|log average|harmonic average only viscosity|geometric average only viscosity|project to Q1 only viscosity

The process of averaging, and where it may be used, is discussed in more detail in Section~\ref{sec:sinker-with-averaging}.

More averaging schemes are available in the averaging material model. This material model is a “compositing material model” which can be used in combination with other material models.

Parameter name: Model name#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: The name of the material model to be used in this simulation. There are many material models you can choose from, as listed below. They generally fall into two category: (i) models that implement a particular case of material behavior, (ii) models that modify other models in some way. We sometimes call the latter “compositing models”. An example of a compositing model is the “depth dependent” model below in that it takes another, freely choosable model as its base and then modifies that model’s output in some way.

You can select one of the following models:

‘Steinberger’: This material model looks up the viscosity from the tables that correspond to the paper of Steinberger and Calderwood 2006 (“Models of large-scale viscous flow in the Earth’s mantle with constraints from mineral physics and surface observations”, Geophys. J. Int., 167, 1461-1481, \url{http://dx.doi.org/10.1111/j.1365-246X.2006.03131.x}) and material data from a database generated by the thermodynamics code Perplex, see \url{http://www.perplex.ethz.ch/}. The default example data builds upon the thermodynamic database by Stixrude 2011 and assumes a pyrolitic composition by Ringwood 1988 but is easily replaceable by other data files.

‘ascii reference profile’: A material model that reads in a reference state for density, thermal expansivity, compressibility and specific heat from a text file. 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 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 ‘density’, ‘thermal_expansivity’, ‘specific_heat’, and ‘compressibility’. 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.

The viscosity \(\eta\) is computed as \begin{equation}\eta(z,T) = \eta_r(z) \eta_0 \exp\left(-A \frac{T - T_{\text{adi}}}{T_{\text{adi}}}\right),\end{equation}where \(\eta_r(z)\) is the depth-dependence, which is a piecewise constant function computed according to the list of “Viscosity prefactors” and “Transition depths”, \(\eta_0\) is the reference viscosity specified by the parameter “Viscosity” and \(A\) describes the dependence on temperature and corresponds to the parameter “Thermal viscosity exponent”.

‘averaging’: The “averaging” Material model applies an averaging of the quadrature points within a cell. The values to average are supplied by any of the other available material models. In other words, it is a “compositing material model”. Parameters related to the average model are read from a subsection “Material model/Averaging”.

The user must specify a “Base model” from which material properties are derived. Furthermore an averaging operation must be selected, where the Choice should be from the list none|arithmetic average|harmonic average|geometric average|pick largest|log average|NWD arithmetic average|NWD harmonic average|NWD geometric average.

NWD stands for Normalized Weighed Distance. The models with this in front of their name work with a weighed average, which means each quadrature point requires an individual weight. The weight is determined by the distance, where the exact relation is determined by a bell shaped curve. A bell shaped curve is a continuous function which is one at its maximum and exactly zero at and beyond its limit. This bell shaped curve is spanned around each quadrature point to determine the weighting map for each quadrature point. The used bell shape comes from Lucy (1977). The distance is normalized so the largest distance becomes one. This means that if variable ”Bell shape limit” is exactly one, the farthest quadrature point is just on the limit and its weight will be exactly zero. In this plugin it is not implemented as larger and equal than the limit, but larger than, to ensure the quadrature point at distance zero is always included.

‘compositing’: The “compositing” Material model selects material model properties from a given set of other material models, and is intended to make mixing different material models easier. This is useful, for example, when wanting to use the melting parameterization of the “melt simple” model (which has a relatively simple viscosity model that only allows for a temperature- but not strain rate-dependent viscosity) with a more realistic viscosity model such as that provided by the “diffusion dislocation” model.

Specifically, this material model works by allowing to specify the name of another material model for each coefficient that material models are asked for (such as the viscosity, density, etc.). Whenever the material model is asked for the values of coefficients, it then evaluates all of the “base models” that were listed for the various coefficients, and copies the values returned by these base models into the output structure.

The implementation of this material model is somewhat expensive because it has to evaluate all material coefficients of all underlying material models. Consequently, if performance of assembly and postprocessing is important, then implementing a separate material model is a better choice than using this material model.

‘composition reaction’: A material model that behaves in the same way as the simple material model, but includes two compositional fields and a reaction between them. Above a depth given in the input file, the first fields gets converted to the second field.

‘depth dependent’: The “depth dependent” Material model applies a depth-dependent scaling to any of the other available material models. In other words, it is a “compositing material model”.

Parameters related to the depth dependent model are read from a subsection “Material model/Depth dependent model”. The user must specify a “Base model” from which material properties are derived. Currently the depth dependent model only allows depth dependence of viscosity - other material properties are taken from the “Base model”. Viscosity \(\eta\) at depth \(z\) is calculated according to:\begin{equation}\eta(z,p,T,X,…) = \eta(z) \eta_b(p,T,X,..)/\eta_{r}\end{equation}where \(\eta(z)\) is the depth-dependence specified by the depth dependent model, \(\eta_b(p,T,X,...)\) is the viscosity calculated from the base model, and \(\eta_{r}\) is the reference viscosity. In addition to the specification of the “Base model”, the user must specify the method to be used to calculate the depth-dependent viscosity \(\eta(z)\) as “Material model/Depth dependent model/Depth dependence method”, which can be chosen among “None|Function|File|List”. Each method and the associated parameters are as follows:

“Function”: read a user-specified parsed function from the input file in a subsection “Material model/Depth dependent model/Viscosity depth function”. By default, this function is uniformly equal to 1.0e21. Specifying a function that returns a value less than or equal to 0.0 anywhere in the model domain will produce an error.

“File”: read a user-specified file containing viscosity values at specified depths. The file containing depth-dependent viscosities is read from a directory specified by the user as “Material model/Depth dependent model/Data directory”, from a file with name specified as “Material model/Depth dependent model/Viscosity depth file”. The format of this file is ascii text and contains two columns with one header line:

example Viscosity depth file:\Depth (m) Viscosity (Pa-s)\0.0000000e+00 1.0000000e+21\6.7000000e+05 1.0000000e+22\

Viscosity is interpolated from this file using linear interpolation. “None”: no depth-dependence. Viscosity is taken directly from “Base model”

“List:”: read a comma-separated list of depth values corresponding to the maximum depths of layers having constant depth-dependence \(\eta(z)\). The layers must be specified in order of increasing depth, and the last layer in the list must have a depth greater than or equal to the maximal depth of the model. The list of layer depths is specified as “Material model/Depth dependent model/Depth list” and the corresponding list of layer viscosities is specified as “Material model/Depth dependent model/Viscosity list”

‘diffusion dislocation’: An implementation of a viscous rheology including diffusion and dislocation creep. Compositional fields can each be assigned individual activation energies, reference densities, thermal expansivities, and stress exponents. The effective viscosity is defined as

[\eta_{\text{eff}} = \left(\frac{1}{\eta_{\text{eff}}^\text{diff}}+ \frac{1}{\eta_{\text{eff}}^\text{dis}}\right)^{-1}] where [\eta_{\text{i}} = \frac{1}{2} A^{-\frac{1}{n_i}} d^\frac{m_i}{n_i} \dot{\varepsilon_i}^{\frac{1-n_i}{n_i}} \exp\left(\frac{E_i^\ast + PV_i^\ast}{n_iRT}\right)]

where \(d\) is grain size, \(i\) corresponds to diffusion or dislocation creep, \(\dot{\varepsilon}\) is the square root of the second invariant of the strain rate tensor, \(R\) is the gas constant, \(T\) is temperature, and \(P\) is pressure. \(A_i\) are prefactors, \(n_i\) and \(m_i\) are stress and grain size exponents \(E_i\) are the activation energies and \(V_i\) are the activation volumes.

This form of the viscosity equation is commonly used in geodynamic simulations See, for example, Billen and Hirth (2007), G3, 8, Q08012. Significantly, other studies may use slightly different forms of the viscosity equation leading to variations in how specific terms are defined or combined. For example, the grain size exponent should always be positive in the diffusion viscosity equation used here, while other studies place the grain size term in the denominator and invert the sign of the grain size exponent. When examining previous work, one should carefully check how the viscous prefactor and grain size terms are defined.

The ratio of diffusion to dislocation strain rate is found by Newton’s method, iterating to find the stress which satisfies the above equations. The value for the components of this formula and additional parameters are read from the parameter file in subsection ’Material model/DiffusionDislocation’.

‘drucker prager’: A material model that has constant values for all coefficients but the density and viscosity. The defaults for all coefficients are chosen to be similar to what is believed to be correct for Earth’s mantle. All of the values that define this model are read from a section “Material model/Drucker Prager” in the input file, see Section~\ref{parameters:Material_20model/Drucker_20Prager}. Note that the model does not take into account any dependencies of material properties on compositional fields.

The viscosity is computed according to the Drucker Prager frictional plasticity criterion (non-associative) based on a user-defined internal friction angle \(\phi\) and cohesion \(C\). In 3d: \(\sigma_y = \frac{6 C \cos(\phi)}{\sqrt{3} (3+\sin(\phi))} + \frac{6 P \sin(\phi)}{\sqrt{3} (3+\sin(\phi))}\), where \(P\) is the pressure. See for example Zienkiewicz, O. C., Humpheson, C. and Lewis, R. W. (1975), G’{e}otechnique 25, No. 4, 671-689. With this formulation we circumscribe instead of inscribe the Mohr Coulomb yield surface. In 2d the Drucker Prager yield surface is the same as the Mohr Coulomb surface: \(\sigma_y = P \sin(\phi) + C \cos(\phi)\). Note that in 2d for \(\phi=0\), these criteria revert to the von Mises criterion (no pressure dependence). See for example Thieulot, C. (2011), PEPI 188, 47-68.

Note that we enforce the pressure to be positive to prevent negative yield strengths and viscosities.

We then use the computed yield strength to scale back the viscosity on to the yield surface using the Viscosity Rescaling Method described in Kachanov, L. M. (2004), Fundamentals of the Theory of Plasticity, Dover Publications, Inc. (Not Radial Return.)A similar implementation can be found in GALE (https://geodynamics.org/cig/software/gale/gale-manual.pdf).

To avoid numerically unfavourably large (or even negative) viscosity ranges, we cut off the viscosity with a user-defined minimum and maximum viscosity: \(\eta_eff = \frac{1}{\frac{1}{\eta_min + \eta}+ \frac{1}{\eta_max}}\).

Note that this model uses the formulation that assumes an incompressible medium despite the fact that the density follows the law \(\rho(T)=\rho_0(1-\beta(T-T_{\text{ref}}))\).

‘grain size’: A material model that relies on compositional fields that correspond to the average grain sizes of a mineral phase and source terms that determine the grain size evolution in terms of the strain rate, temperature, phase transitions, and the creep regime. This material model only works if a compositional field named ’grain_size’ is present. In the diffusion creep regime, the viscosity depends on this grain size field. We use the grain size evolution laws described in Behn et al., 2009. Implications of grain size evolution on the seismic structure of the oceanic upper mantle, Earth Planet. Sci. Letters, 282, 178–189. Other material parameters are either prescribed similar to the ’simple’ material model, or read from data files that were generated by the Perplex or Hefesto software. This material model is described in more detail in Dannberg, J., Z. Eilon, U. Faul, R. Gassmoeller, P. Moulik, and R. Myhill (2017), The importance of grain size to mantle dynamics and seismological observations, Geochem. Geophys. Geosyst., 18, 3034–3061, doi:10.1002/2017GC006944.

‘latent heat’: A material model that includes phase transitions and the possibility that latent heat is released or absorbed when material crosses one of the phase transitions of up to two different materials (compositional fields). This model implements a standard approximation of the latent heat terms following Christensen & Yuen, 1985. The change of entropy is calculated as \(Delta S = \gamma \frac{\Delta\rho}{\rho^2}\) with the Clapeyron slope \(\gamma\) and the density change \(\Delta\rho\) of the phase transition being input parameters. The model employs an analytic phase function in the form \(X=\frac{1}{2} \left( 1 + \tanh \left( \frac{\Delta p}{\Delta p_0} \right) \right)\) with \(\Delta p = p - p_{\text{transition}} - \gamma \left( T - T_{\text{transition}} \right)\) and \(\Delta p_0\) being the pressure difference over the width of the phase transition (specified as input parameter).

‘latent heat melt’: A material model that includes the latent heat of melting for two materials: peridotite and pyroxenite. The melting model for peridotite is taken from Katz et al., 2003 (A new parameterization of hydrous mantle melting) and the one for pyroxenite from Sobolev et al., 2011 (Linking mantle plumes, large igneous provinces and environmental catastrophes). The model assumes a constant entropy change for melting 100% of the material, which can be specified in the input file. The partial derivatives of entropy with respect to temperature and pressure required for calculating the latent heat consumption are then calculated as product of this constant entropy change, and the respective derivative of the function the describes the melt fraction. This is linearly averaged with respect to the fractions of the two materials present. If no compositional fields are specified in the input file, the model assumes that the material is peridotite. If compositional fields are specified, the model assumes that the first compositional field is the fraction of pyroxenite and the rest of the material is peridotite.

Otherwise, this material model has a temperature- and pressure-dependent density and viscosity and the density and thermal expansivity depend on the melt fraction present. It is possible to extent this model to include a melt fraction dependence of all the material parameters by calling the function melt_fraction in the calculation of the respective parameter. However, melt and solid move with the same velocity and melt extraction is not taken into account (batch melting).

‘melt boukare’: A material model that implements a simplified version of the melting model of Boukare et al. (https://doi.org/10.1002/2015JB011929) for the lowermost mantle and uses it to compute the material parameters required for the modelling of melt transport, including melting and solidification and the corresponding changes in composition.The model parameterizes the composition (which includes the components MgO, FeO and SiO2) as a mixture between two endmembers (one iron-bearing and one magnesium-bearing). The equation of state considers three phases: bridgmanite, ferropericlase, and melt (each with their individual compositions). More details can be found in Dannberg, J., Myhill, R., Gassmöller, R., and Cottaar, S. (2021). The morphology, evolution and seismic visibility of partial melt at the core–mantle boundary: implications for ULVZs. Geophysical Journal International, 227(2), 1028-1059.

‘melt global’: A material model that implements a simple formulation of the material parameters required for the modelling of melt transport, including a source term for the porosity according to a simplified linear melting model similar to \cite{schmeling2006}: \(\phi_{\text{equilibrium}} = \frac{T-T_{\text{sol}}}{T_{\text{liq}}-T_{\text{sol}}}\) with \(T_{\text{sol}} = T_{\text{sol,0}} + \Delta T_p \, p + \Delta T_c \, C\) \(T_{\text{liq}} = T_{\text{sol}} + \Delta T_{\text{sol-liq}}\).

‘melt simple’: A material model that implements a simple formulation of the material parameters required for the modelling of melt transport, including a source term for the porosity according to the melting model for dry peridotite of \cite{KSL2003}. This also includes a computation of the latent heat of melting (if the ‘latent heat’ heating model is active).

Most of the material properties are constant, except for the shear, viscosity \(\eta\), the compaction viscosity \(\xi\), and the permeability \(k\), which depend on the porosity; and the solid and melt densities, which depend on temperature and pressure: \(\eta(\phi,T) = \eta_0 e^{\alpha(\phi-\phi_0)} e^{-\beta(T-T_0)/T_0}\), \(\xi(\phi,T) = \xi_0 \frac{\phi_0}{\phi} e^{-\beta(T-T_0)/T_0}\), \(k=k_0 \phi^n (1-\phi)^m\), \(\rho=\rho_0 (1 - \alpha (T - T_{\text{adi}})) e^{\kappa p}\).

The model is compressible only if this is specified in the input file, and contains compressibility for both solid and melt.

‘modified tait’: A material model that implements the thermal modified Tait equation of state as written in \cite{HP2011}. Constant values are used for the thermal conductivity and viscosity. The defaults for all coefficients are chosen to be similar to what is believed to be correct for Earth’s mantle. All of the values that define this model are read from a section “Material model/Modified Tait model” in the input file, see Section~\ref{parameters:Material_20model/Modified_20Tait_20model}.

‘multicomponent’: This incompressible model is for use with an arbitrary number of compositional fields, where each field represents a rock type which can have completely different properties from the others. However, each rock type itself has constant material properties. The value of the compositional field is interpreted as a volume fraction. If the sum of the fields is greater than one, they are renormalized. If it is less than one, material properties for “background mantle” make up the rest. When more than one field is present, the material properties are averaged arithmetically. An exception is the viscosity, where the averaging should make more of a difference. For this, the user selects between arithmetic, harmonic, geometric, or maximum composition averaging.

‘multicomponent compressible’: This model is for use with an arbitrary number of compositional fields, where each field represents a rock type which can have completely different properties from the others. Each rock type is described by a self-consistent equation of state. The value of the compositional field is interpreted as a mass fraction. If the sum of the fields is greater than one, they are renormalized. If it is less than one, material properties for “background mantle” make up the rest. When more than one field is present, the material properties are averaged arithmetically by mass fraction (for specific heat), or volume fraction (for density, thermal expansivity and compressibility). The thermal conductivity is also arithmetically averaged by volume fraction. Finally, the viscosity is averaged by volume fraction, but the user can choose between arithmetic, harmonic, geometric or maximum composition averaging.

‘nondimensional’: A material model for nondimensionalized computations for compressible or incompressible computations defined through Rayleigh number ext{Ra} and Dissipation number Di. This model is made to be used with the Boussinesq, ALA, or TALA formulation.

The viscosity is defined as [\eta = \text{Di} / \text{Ra} \cdot \exp(-b T’ + c z)] where \(T’\) is the temperature variation from the adiabatic temperature, \(z\) is the depth, \(b\) is given by “Viscosity temperature prefactor”, and \(c\) by “Viscosity depth prefactor”. If \(\text{Di}\) is zero, it will be replaced by 1.0 in \(\eta\).

The density is defined as [\rho = \exp(\text{Di}/\gamma \cdot z) (1.0 - \alpha T’ + \text{Di} \gamma p’),] where \(\alpha=\text{Di}\) is the thermal expansion coefficient, \(\gamma\) is the Grueneisen parameter, and \(p’\) is the pressure variation from the adiabatic pressure. The pressure dependent term is not present if “TALA” is enabled.

‘perplex lookup’: A material model that has constant values for viscosity and thermal conductivity, and calculates other properties on-the-fly using PerpleX meemum. Compositional fields correspond to the individual components in the order given in the PerpleX file.

‘replace lithosphere viscosity’: The “replace lithosphere viscosity” Material model sets viscosity to a prescribed constant above the lithosphere-asthenosphere boundary (specified by an ascii file or maximum lithosphere depth). Below the lithosphere-asthenosphereboundary the viscosity is taken from any of the other available material model. In other words, it is a “compositing material model”. Parameters related to the replace lithosphere viscosity model are read from a subsection “Material model/Replace lithosphere viscosity”. The user must specify a “Base model” from which other material properties are derived. 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.

‘simple’: A material model that has constant values for all coefficients but the density and viscosity. The defaults for all coefficients are chosen to be similar to what is believed to be correct for Earth’s mantle. All of the values that define this model are read from a section “Material model/Simple model” in the input file, see Section~\ref{parameters:Material_20model/Simple_20model}.

This model uses the following set of equations for the two coefficients that are non-constant: \begin{align} \eta(p,T,\mathfrak c) &= \tau(T) \zeta(\mathfrak c) \eta_0, \ \rho(p,T,\mathfrak c) &= \left(1-\alpha (T-T_0)\right)\rho_0 + \Delta\rho ; c_0,\end{align}where \(c_0\) is the first component of the compositional vector \(\mathfrak c\) if the model uses compositional fields, or zero otherwise.

The temperature pre-factor for the viscosity formula above is defined as \begin{align} \tau(T) &= H\left(e^{-\beta (T-T_0)/T_0}\right),\intertext{with} \qquad\qquad H(x) &= \begin{cases} \tau_{\text{min}} & \text{if}; x<\tau_{\text{min}}, \ x & \text{if}; 10^{-2}\le x \le 10^2, \ \tau_{\text{max}} & \text{if}; x>\tau_{\text{max}}, \ \end{cases}\end{align} where \(x=e^{-\beta (T-T_0)/T_0}\), \(\beta\) corresponds to the input parameter “Thermal viscosity exponent”, and \(T_0\) to the parameter “Reference temperature”. If you set \(T_0=0\) in the input file, the thermal pre-factor \(\tau(T)=1\). The parameters \(\tau_{\text{min}}\) and \(\tau_{\text{max}}\) set the minimum and maximum values of the temperature pre-factor and are set using “Maximum thermal prefactor” and “Minimum thermal prefactor”. Specifying a value of 0.0 for the minimum or maximum values will disable pre-factor limiting.

The compositional pre-factor for the viscosity is defined as \begin{align} \zeta(\mathfrak c) &= \xi^{c_0}\end{align} if the model has compositional fields and equals one otherwise. \(\xi\) corresponds to the parameter “Composition viscosity prefactor” in the input file.

Finally, in the formula for the density, \(\alpha\) corresponds to the “Thermal expansion coefficient” and \(\Delta\rho\) corresponds to the parameter “Density differential for compositional field 1”.

Note that this model uses the formulation that assumes an incompressible medium despite the fact that the density follows the law \(\rho(T)=\rho_0(1-\alpha(T-T_{\text{ref}}))\).

\note{Despite its name, this material model is not exactly “simple”, as indicated by the formulas above. While it was originally intended to be simple, it has over time acquired all sorts of temperature and compositional dependencies that weren’t initially intended. Consequently, there is now a “simpler” material model that now fills the role the current model was originally intended to fill.}

‘simple compressible’: A material model that has constant values for all coefficients but the density. The defaults for all coefficients are chosen to be similar to what is believed to be correct for Earth’s mantle. All of the values that define this model are read from a section “Material model/Simple compressible model” in the input file, see Section~\ref{parameters:Material_20model/Simple_20compressible_20model}.

This model uses the following equations for the density: \begin{align} \rho(p,T) = \rho_0 \left(1-\alpha (T-T_a)\right) \exp{\beta (P-P_0))}\end{align}This formulation for the density assumes that the compressibility provided by the user is the adiabatic compressibility (\(\beta_S\)). The thermal expansivity and isentropic compressibility implied by the pressure and temperature dependence are equal to the user-defined constant values only along the reference isentrope, and there is also an implicit pressure dependence to the heat capacity \(C_p\) via Maxwell’s relations.

‘simpler’: A material model that has constant values except for density, which depends linearly on temperature: \begin{align} \rho(p,T) &= \left(1-\alpha (T-T_0)\right)\rho_0.\end{align}

\note{This material model fills the role the “simple” material model was originally intended to fill, before the latter acquired all sorts of complicated temperature and compositional dependencies.}

‘visco plastic’: An implementation of an incompressible visco(elastic)-plastic rheology with options for selecting dislocation creep, diffusion creep or composite viscous flow laws. Prior to yielding, one may select to modify the viscosity to account for viscoelastic effects. Plasticity limits viscous stresses through a Drucker Prager yield criterion. The implementation of this material model is based heavily on the ‘DiffusionDislocation’ (Bob Myhill), ‘DruckerPrager’ (Anne Glerum), and ‘Viscoelastic’ (John Naliboff) material models.

The viscosity for dislocation or diffusion creep is defined as [v = \frac 12 A^{-\frac{1}{n}} d^{\frac{m}{n}} \dot{\varepsilon}_{ii}^{\frac{1-n}{n}} \exp\left(\frac{E + PV}{nRT}\right)] where \(A\) is the prefactor, \(n\) is the stress exponent, \(\dot{\varepsilon}_{ii}\) is the square root of the deviatoric strain rate tensor second invariant, \(d\) is grain size, \(m\) is the grain size exponent, \(E\) is activation energy, \(V\) is activation volume, \(P\) is pressure, \(R\) is the gas exponent and \(T\) is temperature. This form of the viscosity equation is commonly used in geodynamic simulations. See, for example, Billen and Hirth (2007), G3, 8, Q08012. Significantly, other studies may use slightly different forms of the viscosity equation leading to variations in how specific terms are defined or combined. For example, the grain size exponent should always be positive in the diffusion viscosity equation used here, while other studies place the grain size term in the denominator and invert the sign of the grain size exponent. When examining previous work, one should carefully check how the viscous prefactor and grain size terms are defined.

One may select to use the diffusion (\(v_{\text{diff}}\); \(n=1\), \(m eq 0\)), dislocation (\(v_{\text{disl}}\), \(n>1\), \(m=0\)) or composite \(\frac{v_{\text{diff}} v_{\text{disl}}}{v_{\text{diff}}+v_{\text{disl}}}\) equation form.

The diffusion and dislocation prefactors can be weakened with a factor between 0 and 1 according to the total or the viscous strain only.

Viscosity is limited through one of two different ‘yielding’ mechanisms.

The first plasticity mechanism limits viscous stress through a Drucker Prager yield criterion, where the yield stress in 3d is \(\sigma_y = \frac{6C\cos(\phi) + 2P\sin(\phi)} {\sqrt{3}(3+\sin(\phi))}\) and \(\sigma_y = C\cos(\phi) + P\sin(\phi)\) in 2d. Above, \(C\) is cohesion and \(\phi\) is the angle of internal friction. Note that the 2d form is equivalent to the Mohr Coulomb yield surface. If \(\phi\) is 0, the yield stress is fixed and equal to the cohesion (Von Mises yield criterion). When the viscous stress (\(2v{\varepsilon}_{ii}\)) exceeds the yield stress, the viscosity is rescaled back to the yield surface: \(v_{y}=\sigma_{y}/(2{\varepsilon}_{ii})\). This form of plasticity is commonly used in geodynamic models. See, for example, Thieulot, C. (2011), PEPI 188, pp. 47-68.

The user has the option to linearly reduce the cohesion and internal friction angle as a function of the finite strain magnitude. The finite strain invariant or full strain tensor is calculated through compositional fields within the material model. This implementation is identical to the compositional field finite strain plugin and cookbook described in the manual (author: Gassmoeller, Dannberg). If the user selects to track the finite strain invariant (\(e_{ii}\)), a single compositional field tracks the value derived from \(e_{ii}^t = (e_{ii})^{(t-1)} + \dot{e}_{ii}\; dt\), where \(t\) and \(t-1\) are the current and prior time steps, \(\dot{e}_{ii}\) is the second invariant of the strain rate tensor and \(dt\) is the time step size. In the case of the full strain tensor \(F\), the finite strain magnitude is derived from the second invariant of the symmetric stretching tensor \(L\), where \(L = F [F]^T\). The user must specify a single compositional field for the finite strain invariant or multiple fields (4 in 2d, 9 in 3d) for the finite strain tensor. These field(s) must be the first listed compositional fields in the parameter file. Note that one or more of the finite strain tensor components must be assigned a non-zero value initially. This value can be be quite small (e.g., 1.e-8), but still non-zero. While the option to track and use the full finite strain tensor exists, tracking the associated compositional fields is computationally expensive in 3d. Similarly, the finite strain magnitudes may in fact decrease if the orientation of the deformation field switches through time. Consequently, the ideal solution is track the finite strain invariant (single compositional) field within the material and track the full finite strain tensor through particles.When only the second invariant of the strain is tracked, one has the option to track the full strain or only the plastic strain. In the latter case, strain is only tracked in case the material is plastically yielding, i.e. the viscous stress > yield stress.

Viscous stress may also be limited by a non-linear stress limiter that has a form similar to the Peierls creep mechanism. This stress limiter assigns an effective viscosity \(\sigma_{\text{eff}} = \frac{\tau_y}{2\varepsilon_y} {\frac{\varepsilon_{ii}}{\varepsilon_y}}^{\frac{1}{n_y}-1}\) Above \(\tau_y\) is a yield stress, \(\varepsilon_y\) is the reference strain rate, \(\varepsilon_{ii}\) is the strain rate and \(n_y\) is the stress limiter exponent. The yield stress, \(\tau_y\), is defined through the Drucker Prager yield criterion formulation. This method of limiting viscous stress has been used in various forms within the geodynamic literature \cite{chri92,vavv02,cibi13,cibi15}.When \(n_y\) is 1, it essentially becomes a linear viscosity model, and in the limit \(n_y\rightarrow \infty\) it converges to the standard viscosity rescaling method (concretely, values \(n_y>20\) are large enough).

The visco-plastic rheology described above may also be modified to include viscoelastic deformation, thus producing a viscoelastic plastic constitutive relationship.

The viscoelastic rheology behavior takes into account the elastic shear strength (e.g., shear modulus), while the tensile and volumetric strength (e.g., Young’s and bulk modulus) are not considered. The model is incompressible and allows specifying an arbitrary number of compositional fields, where each field represents a different rock type or component of the viscoelastic stress tensor. The stress tensor in 2d and 3d, respectively, contains 3 or 6 components. The compositional fields representing these components must be named and listed in a very specific format, which is designed to minimize mislabeling stress tensor components as distinct ’compositional rock types’ (or vice versa). For 2d models, the first three compositional fields must be labeled ’stress_xx’, ’stress_yy’ and ’stress_xy’. In 3d, the first six compositional fields must be labeled ’stress_xx’, ’stress_yy’, ’stress_zz’, ’stress_xy’, ’stress_xz’, ’stress_yz’.

Combining this viscoelasticity implementation with non-linear viscous flow and plasticity produces a constitutive relationship commonly referred to as partial elastoviscoplastic (e.g., pEVP) in the geodynamics community. While extensively discussed and applied within the geodynamics literature, notable references include: Moresi et al. (2003), J. Comp. Phys., v. 184, p. 476-497. Gerya and Yuen (2007), Phys. Earth. Planet. Inter., v. 163, p. 83-105. Gerya (2010), Introduction to Numerical Geodynamic Modeling. Kaus (2010), Tectonophysics, v. 484, p. 36-47. Choi et al. (2013), J. Geophys. Res., v. 118, p. 2429-2444. Keller et al. (2013), Geophys. J. Int., v. 195, p. 1406-1442.

The overview below directly follows Moresi et al. (2003) eqns. 23-38. However, an important distinction between this material model and the studies above is the use of compositional fields, rather than particles, to track individual components of the viscoelastic stress tensor. The material model will be updated when an option to track and calculate viscoelastic stresses with particles is implemented.

Moresi et al. (2003) begins (eqn. 23) by writing the deviatoric rate of deformation (\(\hat{D}\)) as the sum of elastic (\(\hat{D_{e}}\)) and viscous (\(\hat{D_{v}}\)) components: \(\hat{D} = \hat{D_{e}} + \hat{D_{v}}\). These terms further decompose into \(\hat{D_{v}} = \frac{\tau}{2\eta}\) and \(\hat{D_{e}} = \frac{\overset{\nabla}{\tau}}{2\mu}\), where \(\tau\) is the viscous deviatoric stress, \(\eta\) is the shear viscosity, \(\mu\) is the shear modulus and \(\overset{\nabla}{\tau}\) is the Jaumann corotational stress rate. This later term (eqn. 24) contains the time derivative of the deviatoric stress (\(\dot{\tau}\)) and terms that account for material spin (e.g., rotation) due to advection: \(\overset{\nabla}{\tau} = \dot{\tau} + {\tau}W -W\tau\). Above, \(W\) is the material spin tensor (eqn. 25): \(W_{ij} = \frac{1}{2} \left (\frac{\partial V_{i}}{\partial x_{j}} - \frac{\partial V_{j}}{\partial x_{i}} \right )\).

If plasticity is included, the deviatoric rate of deformation may be written as: \(\hat{D} = \hat{D_{e}} + \hat{D_{v}} + \hat{D_{p}}\), where \(\hat{D_{p}}\) is the plastic component. \(\hat{D_{p}}\) decomposes to \(\frac{\tau_{y}}{2\eta_{y}}\), where \(\tau_{y}\) is the yield stress and \(\eta_{y}\) is the viscosity rescaled to the yield surface. The Jaumann stress-rate can also be approximated using terms from the previous time step (\(t\)) and current time step (\(t + \Delta t^{e}\)): \(\smash[t]{\overset{\nabla}{\tau}}^{t + \Delta t^{e}} \approx \frac{\tau^{t + \Delta t^{e} - \tau^{t}}}{\Delta t^{e}} - W^{t}\tau^{t} + \tau^{t}W^{t}\). In this material model, the size of the time step above (\(\Delta t^{e}\)) can be specified as the numerical time step size or an independent fixed time step. If the latter case is selected, the user has an option to apply a stress averaging scheme to account for the differences between the numerical and fixed elastic time step (eqn. 32). If one selects to use a fixed elastic time step throughout the model run, this can still be achieved by using CFL and maximum time step values that restrict the numerical time step to a specific time.

The formulation above allows rewriting the total rate of deformation (eqn. 29) as \(\tau^{t + \Delta t^{e}} = \eta_{eff} \left ( 2\hat{D}^{t + \triangle t^{e}} + \frac{\tau^{t}}{\mu \Delta t^{e}} + \frac{W^{t}\tau^{t} - \tau^{t}W^{t}}{\mu} \right )\).

The effective viscosity (eqn. 28) is a function of the viscosity (\(\eta\)), elastic time step size (\(\Delta t^{e}\)) and shear relaxation time (\( \alpha = \frac{\eta}{\mu} \)): \(\eta_{eff} = \eta \frac{\Delta t^{e}}{\Delta t^{e} + \alpha}\) The magnitude of the shear modulus thus controls how much the effective viscosity is reduced relative to the initial viscosity.

Elastic effects are introduced into the governing Stokes equations through an elastic force term (eqn. 30) using stresses from the previous time step: \(F^{e,t} = -\frac{\eta_{eff}}{\mu \Delta t^{e}} \tau^{t}\). This force term is added onto the right-hand side force vector in the system of equations.

When plastic yielding occurs, the effective viscosity in equation 29 and 30 is the plastic viscosity (equation 36). If the current stress is below the plastic yield stress, the effective viscosity is still as defined in equation 28. During non-linear iterations, we define the current stress prior to yielding (e.g., value compared to yield stress) as \(\tau^{t + \Delta t^{e}} = \eta_{eff} \left ( 2\hat{D}^{t + \triangle t^{e}} + \frac{\tau^{t}}{\mu \Delta t^{e}} \right ) \)

Compositional fields can each be assigned individual values of thermal diffusivity, heat capacity, density, thermal expansivity and rheological parameters.

If more than one compositional field is present at a given point, viscosities are averaged with an arithmetic, geometric harmonic (default) or maximum composition scheme.

The value for the components of this formula and additional parameters are read from the parameter file in subsection ’Material model/Visco Plastic’.

‘viscoelastic’: An implementation of a simple linear viscoelastic rheology that only includes the deviatoric components of elasticity. Specifically, the viscoelastic rheology only takes into account the elastic shear strength (e.g., shear modulus), while the tensile and volumetric strength (e.g., Young’s and bulk modulus) are not considered. The model is incompressible and allows specifying an arbitrary number of compositional fields, where each field represents a different rock type or component of the viscoelastic stress tensor. The stress tensor in 2d and 3d, respectively, contains 3 or 6 components. The compositional fields representing these components must be named and listed in a very specific format, which is designed to minimize mislabeling stress tensor components as distinct ’compositional rock types’ (or vice versa). For 2d models, the first three compositional fields must be labeled ’stress_xx’, ’stress_yy’ and ’stress_xy’. In 3d, the first six compositional fields must be labeled ’stress_xx’, ’stress_yy’, ’stress_zz’, ’stress_xy’, ’stress_xz’, ’stress_yz’.

Expanding the model to include non-linear viscous flow (e.g., diffusion/dislocation creep) and plasticity would produce a constitutive relationship commonly referred to as partial elastoviscoplastic (e.g., pEVP) in the geodynamics community. While extensively discussed and applied within the geodynamics literature, notable references include: Moresi et al. (2003), J. Comp. Phys., v. 184, p. 476-497. Gerya and Yuen (2007), Phys. Earth. Planet. Inter., v. 163, p. 83-105. Gerya (2010), Introduction to Numerical Geodynamic Modeling. Kaus (2010), Tectonophysics, v. 484, p. 36-47. Choi et al. (2013), J. Geophys. Res., v. 118, p. 2429-2444. Keller et al. (2013), Geophys. J. Int., v. 195, p. 1406-1442.

The overview below directly follows Moresi et al. (2003) eqns. 23-32. However, an important distinction between this material model and the studies above is the use of compositional fields, rather than particles, to track individual components of the viscoelastic stress tensor. The material model will be updated when an option to track and calculate viscoelastic stresses with particles is implemented.

Moresi et al. (2003) begins (eqn. 23) by writing the deviatoric rate of deformation (\(\hat{D}\)) as the sum of elastic (\(\hat{D_{e}}\)) and viscous (\(\hat{D_{v}}\)) components: \(\hat{D} = \hat{D_{e}} + \hat{D_{v}}\). These terms further decompose into \(\hat{D_{v}} = \frac{\tau}{2\eta}\) and \(\hat{D_{e}} = \frac{\overset{\nabla}{\tau}}{2\mu}\), where \(\tau\) is the viscous deviatoric stress, \(\eta\) is the shear viscosity, \(\mu\) is the shear modulus and \(\overset{\nabla}{\tau}\) is the Jaumann corotational stress rate. This later term (eqn. 24) contains the time derivative of the deviatoric stress (\(\dot{\tau}\)) and terms that account for material spin (e.g., rotation) due to advection: \(\overset{\nabla}{\tau} = \dot{\tau} + {\tau}W -W\tau\). Above, \(W\) is the material spin tensor (eqn. 25): \(W_{ij} = \frac{1}{2} \left (\frac{\partial V_{i}}{\partial x_{j}} - \frac{\partial V_{j}}{\partial x_{i}} \right )\).

The Jaumann stress-rate can also be approximated using terms from the previous time step (\(t\)) and current time step (\(t + \Delta t^{e}\)): \(\smash[t]{\overset{\nabla}{\tau}}^{t + \Delta t^{e}} \approx \frac{\tau^{t + \Delta t^{e} - \tau^{t}}}{\Delta t^{e}} - W^{t}\tau^{t} + \tau^{t}W^{t}\). In this material model, the size of the time step above (\(\Delta t^{e}\)) can be specified as the numerical time step size or an independent fixed time step. If the latter case is selected, the user has an option to apply a stress averaging scheme to account for the differences between the numerical and fixed elastic time step (eqn. 32). If one selects to use a fixed elastic time step throughout the model run, this can still be achieved by using CFL and maximum time step values that restrict the numerical time step to a specific time.

The formulation above allows rewriting the total deviatoric stress (eqn. 29) as \(\tau^{t + \Delta t^{e}} = \eta_\text{eff} \left ( 2\hat{D}^{t + \triangle t^{e}} + \frac{\tau^{t}}{\mu \Delta t^{e}} + \frac{W^{t}\tau^{t} - \tau^{t}W^{t}}{\mu} \right )\).

The effective viscosity (eqn. 28) is a function of the viscosity (\(\eta\)), elastic time step size (\(\Delta t^{e}\)) and shear relaxation time (\( \alpha = \frac{\eta}{\mu} \)): \(\eta_\text{eff} = \eta \frac{\Delta t^{e}}{\Delta t^{e} + \alpha}\) The magnitude of the shear modulus thus controls how much the effective viscosity is reduced relative to the initial viscosity.

Elastic effects are introduced into the governing Stokes equations through an elastic force term (eqn. 30) using stresses from the previous time step: \(F^{e,t} = -\frac{\eta_\text{eff}}{\mu \Delta t^{e}} \tau^{t}\). This force term is added onto the right-hand side force vector in the system of equations.

The value of each compositional field representing distinct rock types at a point is interpreted to be a volume fraction of that rock type. If the sum of the compositional field volume fractions is less than one, then the remainder of the volume is assumed to be ’background material’.

Several model parameters (densities, elastic shear moduli, thermal expansivities, thermal conductivies, specific heats) can be defined per-compositional field. For each material parameter the user supplies a comma delimited list of length N+1, where N is the number of compositional fields. The additional field corresponds to the value for background material. They should be ordered ”background, composition1, composition2…”. However, the first 3 (2d) or 6 (3d) composition fields correspond to components of the elastic stress tensor and their material values will not contribute to the volume fractions. If a single value is given, then all the compositional fields are given that value. Other lengths of lists are not allowed. For a given compositional field the material parameters are treated as constant, except density, which varies linearly with temperature according to the thermal expansivity.

When more than one compositional field is present at a point, they are averaged arithmetically. An exception is viscosity, which may be averaged arithmetically, harmonically, geometrically, or by selecting the viscosity of the composition field with the greatest volume fraction.

Subsection: Material model / Ascii reference profile#

Parameter name: Thermal conductivity#

Default value: 4.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference conductivity

Parameter name: Thermal viscosity exponent#

Default value: 0.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of viscosity. Dimensionless exponent.

Parameter name: Transition depths#

Default value: 1.5e5, 4.1e5, 6.6e5

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

Documentation: A list of depths where the viscosity changes. Values must monotonically increase. Units: \si{\meter}.

Parameter name: Use TALA#

Default value: false

Pattern: [Bool]

Documentation: Whether to use the TALA instead of the ALA approximation.

Parameter name: Viscosity#

Default value: 1e21

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Viscosity

Parameter name: Viscosity prefactors#

Default value: 10., 0.1, 1., 10.

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

Documentation: A list of prefactors for the viscosity that determine the viscosity profile. Each prefactor is applied in a depth range specified by the list of ‘Transition depths’, i.e. the first prefactor is applied above the first transition depth, the second one between the first and second transition depth, and so on. To compute the viscosity profile, this prefactor is multiplied by the reference viscosity specified through the parameter ‘Viscosity’. List must have one more entry than Transition depths. Units: non-dimensional.

Subsection: Material model / Ascii reference profile / Ascii data model#

Parameter name: Data directory#

Default value: $ASPECT_SOURCE_DIR/data/adiabatic-conditions/ascii-data/

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:

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: Material model / Averaging#

Parameter name: Averaging operation#

Default value: none

Pattern: [Selection none|arithmetic average|harmonic average|geometric average|pick largest|log average|nwd arithmetic average|nwd harmonic average|nwd geometric average ]

Documentation: Choose the averaging operation to use.

Parameter name: Base model#

Default value: simple

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic ]

Documentation: The name of a material model that will be modified by an averaging operation. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Bell shape limit#

Default value: 1.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The limit normalized distance between 0 and 1 where the bell shape becomes zero. See the manual for a more information.

Subsection: Material model / Compositing#

Parameter name: Compressibility#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Compressibility. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Density#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Density. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Entropy derivative pressure#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Entropy derivative pressure. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Entropy derivative temperature#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Entropy derivative temperature. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Reaction terms#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Reaction terms. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Specific heat#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Specific heat. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Thermal conductivity#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Thermal conductivity. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Thermal expansion coefficient#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Thermal expansion coefficient. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Viscosity#

Default value: unspecified

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic|unspecified ]

Documentation: Material model to use for Viscosity. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Subsection: Material model / Composition reaction model#

Parameter name: Composition viscosity prefactor 1#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: A linear dependency of viscosity on the first compositional field. Dimensionless prefactor. With a value of 1.0 (the default) the viscosity does not depend on the composition.

Parameter name: Composition viscosity prefactor 2#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: A linear dependency of viscosity on the second compositional field. Dimensionless prefactor. With a value of 1.0 (the default) the viscosity does not depend on the composition.

Parameter name: Density differential for compositional field 1#

Default value: 0.

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

Documentation: If compositional fields are used, then one would frequently want to make the density depend on these fields. In this simple material model, we make the following assumptions: if no compositional fields are used in the current simulation, then the density is simply the usual one with its linear dependence on the temperature. If there are compositional fields, then the material model determines how many of them influence the density. The composition-dependence adds a term of the kind \(+\Delta \rho \; c_1(\mathbf x)\). This parameter describes the value of \(\Delta \rho\). Units: \si{\kilogram\per\meter\cubed}/unit change in composition.

Parameter name: Density differential for compositional field 2#

Default value: 0.

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

Documentation: If compositional fields are used, then one would frequently want to make the density depend on these fields. In this simple material model, we make the following assumptions: if no compositional fields are used in the current simulation, then the density is simply the usual one with its linear dependence on the temperature. If there are compositional fields, then the material model determines how many of them influence the density. The composition-dependence adds a term of the kind \(+\Delta \rho \; c_2(\mathbf x)\). This parameter describes the value of \(\Delta \rho\). Units: \si{\kilogram\per\meter\cubed}/unit change in composition.

Parameter name: Reaction depth#

Default value: 0.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Above this depth the compositional fields react: The first field gets converted to the second field. Units: \si{\meter}.

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of viscosity. Dimensionless exponent.

Parameter name: Viscosity#

Default value: 5e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity. Units: \si{\kilogram\per\meter\per\second}.

Subsection: Material model / Depth dependent model#

Parameter name: Base model#

Default value: simple

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic ]

Documentation: The name of a material model that will be modified by a depth dependent viscosity. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for that for more information.

Parameter name: Data directory#

Default value: $ASPECT_SOURCE_DIR/data/material-model/rheology/

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: ascii_depth_profile.txt

Pattern: [Anything]

Documentation: The file name of the model data.

Parameter name: Depth dependence method#

Default value: None

Pattern: [Selection Function|File|List|None ]

Documentation: Method that is used to specify how the viscosity should vary with depth.

Parameter name: Depth list#

Default value:

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

Documentation: A comma-separated list of depth values for use with the “List” “Depth dependence method”. The list must be provided in order of increasing depth, and the last value must be greater than or equal to the maximal depth of the model. The depth list is interpreted as a layered viscosity structure and the depth values specify the maximum depths of each layer.

Parameter name: Reference viscosity#

Default value: 1.7976931348623157e+308

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant reference viscosity \(\eta_r\) that is used to scale the non-dimensional depth-dependent viscosity prefactor. Units: \si{\pascal\second}.

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: Viscosity depth file#

Alias: Data file name

Deprecation Status: false

Parameter name: Viscosity list#

Default value:

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

Documentation: A comma-separated list of viscosity values, corresponding to the depth values provided in “Depth list”. The number of viscosity values specified here must be the same as the number of depths provided in “Depth list”.

Subsection: Material model / Depth dependent model / Viscosity depth 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: 1.0e21

Pattern: [Anything]

Documentation:

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: Material model / Diffusion dislocation#

Parameter name: Activation energies for diffusion creep#

Default value: 375e3

Pattern: [Anything]

Documentation: List of activation energies, \(E_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\joule\per\mole}.

Parameter name: Activation energies for dislocation creep#

Default value: 530e3

Pattern: [Anything]

Documentation: List of activation energies, \(E_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\joule\per\mole}.

Parameter name: Activation volumes for diffusion creep#

Default value: 6e-6

Pattern: [Anything]

Documentation: List of activation volumes, \(V_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\meter\cubed\per\mole}.

Parameter name: Activation volumes for dislocation creep#

Default value: 1.4e-5

Pattern: [Anything]

Documentation: List of activation volumes, \(V_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\meter\cubed\per\mole}.

Parameter name: Densities#

Default value: 3300.

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

Documentation: List of densities, \(\rho\), for background mantle and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Effective viscosity coefficient#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Scaling coefficient for effective viscosity.

Parameter name: Grain size#

Default value: 1e-3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Units: \si{\meter}.

Parameter name: Grain size exponents for diffusion creep#

Default value: 3.

Pattern: [Anything]

Documentation: List of grain size exponents, \(m_{\text{diffusion}}\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Heat capacity#

Default value: 1.25e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Maximum strain rate ratio iterations#

Default value: 40

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

Documentation: Maximum number of iterations to find the correct diffusion/dislocation strain rate ratio.

Parameter name: Maximum viscosity#

Default value: 1e28

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Upper cutoff for effective viscosity. Units: \si{\pascal\second}.

Parameter name: Minimum strain rate#

Default value: 1.4e-20

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Stabilizes strain dependent viscosity. Units: \si{\per\second}.

Parameter name: Minimum viscosity#

Default value: 1e17

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Lower cutoff for effective viscosity. Units: \si{\pascal\second}.

Parameter name: Prefactors for diffusion creep#

Default value: 1.5e-15

Pattern: [Anything]

Documentation: List of viscosity prefactors, \(A\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\per\pascal\meter}\(^{m_{\text{diffusion}}}\)\si{\per\second}.

Parameter name: Prefactors for dislocation creep#

Default value: 1.1e-16

Pattern: [Anything]

Documentation: List of viscosity prefactors, \(A\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\pascal}\(^{-n_{\text{dislocation}}}\) \si{\per\second}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: For calculating density by thermal expansivity. Units: \si{\kelvin}.

Parameter name: Strain rate residual tolerance#

Default value: 1e-22

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Tolerance for correct diffusion/dislocation strain rate ratio.

Parameter name: Stress exponents for diffusion creep#

Default value: 1.

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

Documentation: List of stress exponents, \(n_{\text{diffusion}}\), for background mantle and compositional fields, for a total of N+1 values, where N is the number of compositional fields. The stress exponent for diffusion creep is almost always equal to one. If only one value is given, then all use the same value. Units: None.

Parameter name: Stress exponents for dislocation creep#

Default value: 3.5

Pattern: [Anything]

Documentation: List of stress exponents, \(n_{\text{dislocation}}\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Thermal diffusivity#

Default value: 0.8e-6

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Units: \si{\meter\squared\per\second}.

Parameter name: Thermal expansivities#

Default value: 3.5e-5

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

Documentation: List of thermal expansivities for background mantle and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\per\kelvin}.

Parameter name: Viscosity averaging scheme#

Default value: harmonic

Pattern: [Selection arithmetic|harmonic|geometric|maximum composition ]

Documentation: When more than one compositional field is present at a point with different viscosities, we need to come up with an average viscosity at that point. Select a weighted harmonic, arithmetic, geometric, or maximum composition.

Subsection: Material model / Drucker Prager#

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). The reference temperature is used in the density calculation. Units: \si{\kelvin}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Subsection: Material model / Drucker Prager / Viscosity#

Parameter name: Angle of internal friction#

Default value: 0.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the angle of internal friction \(\phi\). For a value of zero, in 2d the von Mises criterion is retrieved. Angles higher than 30 degrees are harder to solve numerically. Units: degrees.

Parameter name: Cohesion#

Default value: 2e7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the cohesion \(C\). Units: \si{\pascal}.

Parameter name: Maximum viscosity#

Default value: 1e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the maximum viscosity cutoff \(\eta_max\). Units: \si{\pascal\second}.

Parameter name: Minimum viscosity#

Default value: 1e19

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the minimum viscosity cutoff \(\eta_min\). Units: \si{\pascal\second}.

Parameter name: Reference strain rate#

Default value: 1e-15

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the initial strain rate prescribed during the first nonlinear iteration \(\dot{\epsilon}_ref\). Units: \si{\per\second}.

Subsection: Material model / Grain size model#

Parameter name: Advect logarithm of grain size#

Default value: false

Pattern: [Bool]

Documentation: This parameter determines whether to advect the logarithm of the grain size or the grain size itself. The equation and the physics are the same, but for problems with high grain size gradients it might be preferable to advect the logarithm.

Parameter name: Average specific grain boundary energy#

Default value: 1.0

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

Documentation: The average specific grain boundary energy \(\gamma\). List must have one more entry than the Phase transition depths. Units: \si{\joule\per\meter\squared}.

Parameter name: Bilinear interpolation#

Default value: true

Pattern: [Bool]

Documentation: This parameter determines whether to use bilinear interpolation to compute material properties (slower but more accurate).

Parameter name: Data directory#

Default value: $ASPECT_SOURCE_DIR/data/material-model/steinberger/

Pattern: [DirectoryName]

Documentation: The path to the model data. 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: Derivatives file names#

Default value:

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

Documentation: The file names of the enthalpy derivatives data. List with as many components as active compositional fields (material data is assumed to be in order with the ordering of the fields).

Parameter name: Diffusion activation energy#

Default value: 3.35e5

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

Documentation: The activation energy for diffusion creep \(E_{diff}\). List must have one more entry than the Phase transition depths. Units: \si{\joule\per\mole}.

Parameter name: Diffusion activation volume#

Default value: 4e-6

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

Documentation: The activation volume for diffusion creep \(V_{diff}\). List must have one more entry than the Phase transition depths. Units: \si{\meter\cubed\per\mole}.

Parameter name: Diffusion creep exponent#

Default value: 1.

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

Documentation: The power-law exponent \(n_{diff}\) for diffusion creep. List must have one more entry than the Phase transition depths. Units: none.

Parameter name: Diffusion creep grain size exponent#

Default value: 3.

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

Documentation: The diffusion creep grain size exponent \(p_{diff}\) that determines the dependence of viscosity on grain size. List must have one more entry than the Phase transition depths. Units: none.

Parameter name: Diffusion creep prefactor#

Default value: 7.4e-15

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

Documentation: The prefactor for the diffusion creep law \(A_{diff}\). List must have one more entry than the Phase transition depths. Units: \si{\meter}\(^{p_{diff}}\)\si{\pascal}\(^{-n_{diff}}\)\si{\per\second}.

Parameter name: Dislocation activation energy#

Default value: 4.8e5

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

Documentation: The activation energy for dislocation creep \(E_{dis}\). List must have one more entry than the Phase transition depths. Units: \si{\joule\per\mole}.

Parameter name: Dislocation activation volume#

Default value: 1.1e-5

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

Documentation: The activation volume for dislocation creep \(V_{dis}\). List must have one more entry than the Phase transition depths. Units: \si{\meter\cubed\per\mole}.

Parameter name: Dislocation creep exponent#

Default value: 3.5

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

Documentation: The power-law exponent \(n_{dis}\) for dislocation creep. List must have one more entry than the Phase transition depths. Units: none.

Parameter name: Dislocation creep prefactor#

Default value: 4.5e-15

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

Documentation: The prefactor for the dislocation creep law \(A_{dis}\). List must have one more entry than the Phase transition depths. Units: \si{\pascal}\(^{-n_{dis}}\)\si{\per\second}.

Parameter name: Dislocation viscosity iteration number#

Default value: 100

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

Documentation: We need to perform an iteration inside the computation of the dislocation viscosity, because it depends on the dislocation strain rate, which depends on the dislocation viscosity itself. This number determines the maximum number of iterations that are performed.

Parameter name: Dislocation viscosity iteration threshold#

Default value: 1e-3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: We need to perform an iteration inside the computation of the dislocation viscosity, because it depends on the dislocation strain rate, which depends on the dislocation viscosity itself. This number determines the termination accuracy, i.e. if the dislocation viscosity changes by less than this factor we terminate the iteration.

Parameter name: Geometric constant#

Default value: 3.

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

Documentation: The geometric constant \(c\) used in the paleowattmeter grain size reduction law. List must have one more entry than the Phase transition depths. Units: none.

Parameter name: Grain growth activation energy#

Default value: 3.5e5

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

Documentation: The activation energy for grain growth \(E_g\). List must have one more entry than the Phase transition depths. Units: \si{\joule\per\mole}.

Parameter name: Grain growth activation volume#

Default value: 8e-6

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

Documentation: The activation volume for grain growth \(V_g\). List must have one more entry than the Phase transition depths. Units: \si{\meter\cubed\per\mole}.

Parameter name: Grain growth exponent#

Default value: 3.

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

Documentation: The exponent of the grain growth law \(p_g\). This is an experimentally determined grain growth constant. List must have one more entry than the Phase transition depths. Units: none.

Parameter name: Grain growth rate constant#

Default value: 1.5e-5

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

Documentation: The prefactor for the Ostwald ripening grain growth law \(G_0\). This is dependent on water content, which is assumed to be 50 H/\(10^6\) Si for the default value. List must have one more entry than the Phase transition depths. Units: \si{\meter}\(^{p_g}\)\si{\per\second}.

Parameter name: Lower mantle grain size scaling#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: A scaling factor for the grain size in the lower mantle. In models where the high grain size contrast between the upper and lower mantle causes numerical problems, the grain size in the lower mantle can be scaled to a larger value, simultaneously scaling the viscosity prefactors and grain growth parameters to keep the same physical behavior. Differences to the original formulation only occur when material with a smaller grain size than the recrystallization grain size cross the upper-lower mantle boundary. The real grain size can be obtained by dividing the model grain size by this value. Units: none.

Parameter name: Material file format#

Default value: perplex

Pattern: [Selection perplex|hefesto ]

Documentation: The material file format to be read in the property tables.

Parameter name: Material file names#

Default value: pyr-ringwood88.txt

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

Documentation: The file names of the material data. List with as many components as active compositional fields (material data is assumed to be in order with the ordering of the fields).

Parameter name: Maximum latent heat substeps#

Default value: 1

Pattern: [Integer range 1…2147483647 (inclusive)]

Documentation: The maximum number of substeps over the temperature pressure range to calculate the averaged enthalpy gradient over a cell.

Parameter name: Maximum specific heat#

Default value: 6000.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The maximum specific heat that is allowed in the whole model domain. Units: J/kg/K.

Parameter name: Maximum temperature dependence of viscosity#

Default value: 100.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The factor by which viscosity at adiabatic temperature and ambient temperature are allowed to differ (a value of x means that the viscosity can be x times higher or x times lower compared to the value at adiabatic temperature. This parameter is introduced to limit local viscosity contrasts, but still allow for a widely varying viscosity over the whole mantle range. Units: none.

Parameter name: Maximum thermal expansivity#

Default value: 1e-3

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

Documentation: The maximum thermal expansivity that is allowed in the whole model domain. Units: 1/K.

Parameter name: Maximum viscosity#

Default value: 1e26

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The maximum viscosity that is allowed in the whole model domain. Units: Pa , s.

Parameter name: Minimum grain size#

Default value: 1e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The minimum grain size that is used for the material model. This parameter is introduced to limit local viscosity contrasts, but still allows for a widely varying viscosity over the whole mantle range. Units: \si{\meter}.

Parameter name: Minimum specific heat#

Default value: 500.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The minimum specific heat that is allowed in the whole model domain. Units: J/kg/K.

Parameter name: Minimum thermal expansivity#

Default value: 1e-5

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

Documentation: The minimum thermal expansivity that is allowed in the whole model domain. Units: 1/K.

Parameter name: Minimum viscosity#

Default value: 1e18

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The minimum viscosity that is allowed in the whole model domain. Units: Pa , s.

Parameter name: Phase transition Clapeyron slopes#

Default value:

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

Documentation: A list of Clapeyron slopes for each phase transition. A positive Clapeyron slope indicates that the phase transition will occur in a greater depth, if the temperature is higher than the one given in Phase transition temperatures and in a smaller depth, if the temperature is smaller than the one given in Phase transition temperatures. For negative slopes the other way round. List must have the same number of entries as Phase transition depths. Units: \si{\pascal\per\kelvin}.

Parameter name: Phase transition depths#

Default value:

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

Documentation: A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.

Parameter name: Phase transition temperatures#

Default value:

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

Documentation: A list of temperatures where phase transitions occur. Higher or lower temperatures lead to phase transition occurring in smaller or greater depths than given in Phase transition depths, depending on the Clapeyron slope given in Phase transition Clapeyron slopes. List must have the same number of entries as Phase transition depths. Units: \si{\kelvin}.

Parameter name: Phase transition widths#

Default value:

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

Documentation: A list of widths for each phase transition. This is only use to specify the region where the recrystallized grain size is assigned after material has crossed a phase transition and should accordingly be chosen similar to the maximum cell width expected at the phase transition.List must have the same number of entries as Phase transition depths. Units: \si{\meter}.

Parameter name: Reciprocal required strain#

Default value: 10.

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

Documentation: This parameter (\(\lambda\)) gives an estimate of the strain necessary to achieve a new grain size. List must have one more entry than the Phase transition depths.

Parameter name: Recrystallized grain size#

Default value:

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

Documentation: The grain size \(d_{ph}\) to that a phase will be reduced to when crossing a phase transition. When set to zero, grain size will not be reduced. List must have the same number of entries as Phase transition depths. Units: \si{\meter}.

Parameter name: Reference compressibility#

Default value: 4e-12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the reference compressibility. Units: \si{\per\pascal}.

Parameter name: Reference density#

Default value: 3300

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(cp\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Use enthalpy for material properties#

Default value: true

Pattern: [Bool]

Documentation: This parameter determines whether to use the enthalpy to calculate the thermal expansivity and specific heat (if true) or use the thermal expansivity and specific heat values from the material properties table directly (if false).

Parameter name: Use paleowattmeter#

Default value: true

Pattern: [Bool]

Documentation: A flag indicating whether the computation should be use the paleowattmeter approach of Austin and Evans (2007) for grain size reduction in the dislocation creep regime (if true) or the paleopiezometer approach from Hall and Parmetier (2003) (if false).

Parameter name: Use table properties#

Default value: false

Pattern: [Bool]

Documentation: This parameter determines whether to use the table properties also for density, thermal expansivity and specific heat. If false the properties are generated as in the simple compressible plugin.

Parameter name: Viscosity#

Default value: 5e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity. Units: \si{\pascal\second}.

Parameter name: Work fraction for boundary area change#

Default value: 0.1

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

Documentation: The fraction \(\chi\) of work done by dislocation creep to change the grain boundary area. List must have one more entry than the Phase transition depths. Units: \si{\joule\per\meter\squared}.

Subsection: Material model / Latent heat#

Parameter name: Composition viscosity prefactor#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: A linear dependency of viscosity on composition. Dimensionless prefactor.

Parameter name: Compressibility#

Default value: 5.124e-12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the compressibility \(\kappa\). Units: \si{\per\pascal}.

Parameter name: Corresponding phase for density jump#

Default value:

Pattern: [List of <[Integer range 0…2147483647 (inclusive)]> of length 0…4294967295 (inclusive)]

Documentation: A list of phases, which correspond to the Phase transition density jumps. The density jumps occur only in the phase that is given by this phase value. 0 stands for the 1st compositional fields, 1 for the second compositional field and -1 for none of them. List must have the same number of entries as Phase transition depths. Units: \si{\pascal\per\kelvin}.

Parameter name: Define transition by depth instead of pressure#

Default value: true

Pattern: [Bool]

Documentation: Whether to list phase transitions by depth or pressure. If this parameter is true, then the input file will use Phase transitions depths and Phase transition widths to define the phase transition. If it is false, the parameter file will read in phase transition data from Phase transition pressures and Phase transition pressure widths.

Parameter name: Density differential for compositional field 1#

Default value: 0.

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

Documentation: If compositional fields are used, then one would frequently want to make the density depend on these fields. In this simple material model, we make the following assumptions: if no compositional fields are used in the current simulation, then the density is simply the usual one with its linear dependence on the temperature. If there are compositional fields, then the density only depends on the first one in such a way that the density has an additional term of the kind \(+\Delta \rho \; c_1(\mathbf x)\). This parameter describes the value of \(\Delta \rho\). Units: \si{\kilogram\per\meter\cubed}/unit change in composition.

Parameter name: Maximum viscosity#

Default value: 1e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Limit for the maximum viscosity in the model. Units: Pa , s.

Parameter name: Minimum viscosity#

Default value: 1e19

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Limit for the minimum viscosity in the model. Units: Pa , s.

Parameter name: Phase transition Clapeyron slopes#

Default value:

Pattern: [Anything]

Documentation: A list of Clapeyron slopes for each phase transition. A positive Clapeyron slope indicates that the phase transition will occur in a greater depth, if the temperature is higher than the one given in Phase transition temperatures and in a smaller depth, if the temperature is smaller than the one given in Phase transition temperatures. For negative slopes the other way round. List must have the same number of entries as Phase transition depths. Units: \si{\pascal\per\kelvin}.

Parameter name: Phase transition density jumps#

Default value:

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

Documentation: A list of density jumps at each phase transition. A positive value means that the density increases with depth. The corresponding entry in Corresponding phase for density jump determines if the density jump occurs in peridotite, eclogite or none of them.List must have the same number of entries as Phase transition depths. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Phase transition depths#

Default value:

Pattern: [Anything]

Documentation: A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.

Parameter name: Phase transition pressure widths#

Default value:

Pattern: [Anything]

Documentation: A list of widths for each phase transition, in terms of pressure. The phase functions are scaled with these values, leading to a jump between phases for a value of zero and a gradual transition for larger values. List must have the same number of entries as Phase transition pressures. Define transition by depth instead of pressure must be set to false to use this parameter. Units: \si{\pascal}.

Parameter name: Phase transition pressures#

Default value:

Pattern: [Anything]

Documentation: A list of pressures where phase transitions occur. Values must monotonically increase. Define transition by depth instead of pressure must be set to false to use this parameter. Units: \si{\pascal}.

Parameter name: Phase transition temperature lower limits#

Default value: -1.7976931348623157e+308

Pattern: [Anything]

Documentation: A list of lower temperature limits for each phase transition. Below this temperature the respective phase transition is deactivated. The default value means there is no lower limit for any phase transition. List must have the same number of entries as Phase transition depths. When the optional temperature limits are applied, the user has to be careful about the consistency between adjacent phases. Phase transitions should be continuous in pressure-temperature space. We recommend producing a phase diagram with simple model setups to check the implementation as a starting point.Units: \si{\kelvin}.

Parameter name: Phase transition temperature upper limits#

Default value: 1.7976931348623157e+308

Pattern: [Anything]

Documentation: A list of upper temperature limits for each phase transition. Above this temperature the respective phase transition is deactivated. The default value means there is no upper limit for any phase transitions. List must have the same number of entries as Phase transition depths. When the optional temperature limits are applied, the user has to be careful about the consistency between adjacent phases. Phase transitions should be continuous in pressure-temperature space. We recommend producing a phase diagram with simple model setups to check the implementation as a starting point.Units: \si{\kelvin}.

Parameter name: Phase transition temperatures#

Default value:

Pattern: [Anything]

Documentation: A list of temperatures where phase transitions occur. Higher or lower temperatures lead to phase transition occurring in smaller or greater depths than given in Phase transition depths, depending on the Clapeyron slope given in Phase transition Clapeyron slopes. List must have the same number of entries as Phase transition depths. Units: \si{\kelvin}.

Parameter name: Phase transition widths#

Default value:

Pattern: [Anything]

Documentation: A list of widths for each phase transition, in terms of depth. The phase functions are scaled with these values, leading to a jump between phases for a value of zero and a gradual transition for larger values. List must have the same number of entries as Phase transition depths. Units: \si{\meter}.

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Thermal conductivity#

Default value: 2.38

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 4e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of viscosity. Dimensionless exponent.

Parameter name: Viscosity#

Default value: 5e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity. Units: \si{\pascal\second}.

Parameter name: Viscosity prefactors#

Default value:

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

Documentation: A list of prefactors for the viscosity for each phase. The reference viscosity will be multiplied by this factor to get the corresponding viscosity for each phase. List must have one more entry than Phase transition depths. Units: non-dimensional.

Subsection: Material model / Latent heat melt#

Parameter name: A1#

Default value: 1085.7

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

Documentation: Constant parameter in the quadratic function that approximates the solidus of peridotite. Units: \si{\degreeCelsius}.

Parameter name: A2#

Default value: 1.329e-7

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the solidus of peridotite. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: A3#

Default value: -5.1e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the solidus of peridotite. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: B1#

Default value: 1475.0

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

Documentation: Constant parameter in the quadratic function that approximates the lherzolite liquidus used for calculating the fraction of peridotite-derived melt. Units: \si{\degreeCelsius}.

Parameter name: B2#

Default value: 8.0e-8

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the lherzolite liquidus used for calculating the fraction of peridotite-derived melt. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: B3#

Default value: -3.2e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the lherzolite liquidus used for calculating the fraction of peridotite-derived melt. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: C1#

Default value: 1780.0

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

Documentation: Constant parameter in the quadratic function that approximates the liquidus of peridotite. Units: \si{\degreeCelsius}.

Parameter name: C2#

Default value: 4.50e-8

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the liquidus of peridotite. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: C3#

Default value: -2.0e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the liquidus of peridotite. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: Composition viscosity prefactor#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: A linear dependency of viscosity on composition. Dimensionless prefactor.

Parameter name: Compressibility#

Default value: 5.124e-12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the compressibility \(\kappa\). Units: \si{\per\pascal}.

Parameter name: D1#

Default value: 976.0

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

Documentation: Constant parameter in the quadratic function that approximates the solidus of pyroxenite. Units: \si{\degreeCelsius}.

Parameter name: D2#

Default value: 1.329e-7

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the solidus of pyroxenite. Note that this factor is different from the value given in Sobolev, 2011, because they use the potential temperature whereas we use the absolute temperature. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: D3#

Default value: -5.1e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the solidus of pyroxenite. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: Density differential for compositional field 1#

Default value: 0.

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

Documentation: If compositional fields are used, then one would frequently want to make the density depend on these fields. In this simple material model, we make the following assumptions: if no compositional fields are used in the current simulation, then the density is simply the usual one with its linear dependence on the temperature. If there are compositional fields, then the density only depends on the first one in such a way that the density has an additional term of the kind \(+\Delta \rho \; c_1(\mathbf x)\). This parameter describes the value of \(\Delta \rho\). Units: \si{\kilogram\per\meter\cubed}/unit change in composition.

Parameter name: E1#

Default value: 663.8

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

Documentation: Prefactor of the linear depletion term in the quadratic function that approximates the melt fraction of pyroxenite. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: E2#

Default value: -611.4

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

Documentation: Prefactor of the quadratic depletion term in the quadratic function that approximates the melt fraction of pyroxenite. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: Mass fraction cpx#

Default value: 0.15

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

Documentation: Mass fraction of clinopyroxene in the peridotite to be molten. Units: non-dimensional.

Parameter name: Maximum pyroxenite melt fraction#

Default value: 0.5429

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

Documentation: Maximum melt fraction of pyroxenite in this parameterization. At higher temperatures peridotite begins to melt.

Parameter name: Peridotite melting entropy change#

Default value: -300.

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

Documentation: The entropy change for the phase transition from solid to melt of peridotite. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Pyroxenite melting entropy change#

Default value: -400.

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

Documentation: The entropy change for the phase transition from solid to melt of pyroxenite. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Relative density of melt#

Default value: 0.9

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

Documentation: The relative density of melt compared to the solid material. This means, the density change upon melting is this parameter times the density of solid material.Units: non-dimensional.

Parameter name: Thermal conductivity#

Default value: 2.38

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 4e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Thermal expansion coefficient of melt#

Default value: 6.8e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of viscosity. Dimensionless exponent.

Parameter name: Viscosity#

Default value: 5e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity. Units: \si{\pascal\second}.

Parameter name: beta#

Default value: 1.5

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

Documentation: Exponent of the melting temperature in the melt fraction calculation. Units: non-dimensional.

Parameter name: r1#

Default value: 0.5

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

Documentation: Constant in the linear function that approximates the clinopyroxene reaction coefficient. Units: non-dimensional.

Parameter name: r2#

Default value: 8e-11

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

Documentation: Prefactor of the linear pressure term in the linear function that approximates the clinopyroxene reaction coefficient. Units: \si{\per\pascal}.

Subsection: Material model / Melt boukare#

Parameter name: Einstein temperatures#

Default value: 418.1, 561.0, 297.6, 540.2, 505.75, 558.1, 558.1

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

Documentation: List of Einstein temperatures for each different endmember.Units: K.

Parameter name: Endmember names#

Default value: FeSiO3_bridgmanite, MgSiO3_bridgmanite, FeO_periclase, MgO_periclase, FeO_melt, MgO_melt, SiO2_melt

Pattern: [List of <[MultipleSelection MgSiO3_bridgmanite|FeSiO3_bridgmanite|MgO_periclase|FeO_periclase|MgO_melt|FeO_melt|SiO2_melt ]> of length 0…4294967295 (inclusive)]

Documentation: Names of the endmember components used in the equation of state and the melting model, and whose parameters are determined by the other input parameters of this material model. The order the parameters are given in has to be the same as the order the endmember names are given in. Units: none.

Parameter name: Endmember states#

Default value: solid, solid, solid, solid, melt, melt, melt

Pattern: [List of <[MultipleSelection solid|melt ]> of length 0…4294967295 (inclusive)]

Documentation: States of the endmember components used in the equation of state and the melting model. For each endmember, this list has to define if they belong to the melt or to the solid. The order the states are given in has to be the same as the order the ’Endmember names’ are given in. Units: none.

Parameter name: Exponential melt weakening factor#

Default value: 27

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

Documentation: The porosity dependence of the viscosity. Units: dimensionless.

Parameter name: Fe mantle melting temperature#

Default value: 3424.5

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

Documentation: The melting temperature of one of the components in the melting model, the Fe mantle endmember.Units: K.

Parameter name: Fe number of moles#

Default value: 0.48

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

Documentation: The number of moles of Fe atoms mixing on a pseudosite in the mantle lattice, This is needed because we use an empirical model fitting the full Boukare model, and can be changed to reflect partition coefficients from other sources.Units: none.

Parameter name: First derivatives of the bulk modulus#

Default value: 4.14, 4.14, 4.9, 3.95, 5.0802472229003905, 4.25, 4.25

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

Documentation: The pressure derivative of the bulk modulus at the reference temperature and reference pressure for each different endmember component.Units: none.

Parameter name: Include melting and freezing#

Default value: true

Pattern: [Bool]

Documentation: Whether to include melting and freezing (according to a simplified linear melting approximation in the model (if true), or not (if false).

Parameter name: Linear coefficients for specific heat polynomial#

Default value: 6.36191292e-03, -3.31714290e-03, 3.36163516e-03, -6.35318887e-03, -2.41909947e-03, -2.41909947e-03, -2.41909947e-03

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

Documentation: The first of three coefficients that are used to compute the specific heat capacities for each different endmember at the reference temperature and reference pressure. This coefficient describes the linear part of the temperature dependence. Units: J/kg/K/K.

Parameter name: Melting time scale for operator splitting#

Default value: 1e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: In case the operator splitting scheme is used, the porosity field can not be set to a new equilibrium melt fraction instantly, but the model has to provide a melting time scale instead. This time scale defines how fast melting happens, or more specifically, the parameter defines the time after which the deviation of the porosity from the equilibrium melt fraction will be reduced to a fraction of \(1/e\). So if the melting time scale is small compared to the time step size, the reaction will be so fast that the porosity is very close to the equilibrium melt fraction after reactions are computed. Conversely, if the melting time scale is large compared to the time step size, almost no melting and freezing will occur.

Also note that the melting time scale has to be larger than or equal to the reaction time step used in the operator splitting scheme, otherwise reactions can not be computed. If the model does not use operator splitting, this parameter is not used. Units: yr or s, depending on the “Use years in output instead of seconds” parameter.

Parameter name: Mg mantle melting temperature#

Default value: 4821.2

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

Documentation: The melting temperature of one of the components in the melting model, the Mg mantle endmember.Units: K.

Parameter name: Mg number of moles#

Default value: 0.62

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

Documentation: The number of moles of Mg atoms mixing on a pseudosite in the mantle lattice, This is needed because we use an empirical model fitting the full Boukare model, and can be changed to reflect partition coefficients from other sources.Units: none.

Parameter name: Molar masses#

Default value: 0.1319287, 0.1003887, 0.0718444, 0.0403044, 0.0707624708, 0.048592178, 0.048592178

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

Documentation: Molar masses of the different endmembersUnits: kg/mol.

Parameter name: Number of atoms#

Default value: 5.0, 5.0, 2.0, 2.0, 2.092, 2.419, 2.419

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

Documentation: Number of atoms per in the formula of each endmember.Units: none.

Parameter name: Reference bulk moduli#

Default value: 2.81e11, 2.51e+11, 1.52e11, 1.616e11, 166652774642.11273, 2.317e11, 2.317e11

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

Documentation: List of bulk moduli for each different endmember at the reference temperature and reference pressure.Units: Pa.

Parameter name: Reference bulk viscosity#

Default value: 1e22

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant bulk viscosity \(\xi_0\) of the solid matrix. This viscosity may be modified by both temperature and porosity dependencies. Units: \(Pa \, s\).

Parameter name: Reference enthalpies#

Default value: -1082910.0, -1442310.0, -262240.0, -601570.0, -195245.49100022088, -538009.8, -538009.8

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

Documentation: List of enthalpies at the reference temperature and reference pressure for each different endmember component.Units: J/mol.

Parameter name: Reference entropies#

Default value: 95.0, 62.6, 58.6, 26.5, 95.0299295525918, 64.9, 64.9

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

Documentation: List of entropies at the reference temperature and reference pressure for each different endmember component.Units: J/K/mol.

Parameter name: Reference melt viscosity#

Default value: 10

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant melt viscosity \(\eta_f\). Units: \(Pa \, s\).

Parameter name: Reference permeability#

Default value: 1e-8

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

Documentation: Reference permeability of the solid host rock.Units: \(m^2\).

Parameter name: Reference pressure#

Default value: 1e11

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

Documentation: Reference pressure used to compute the material propertiesof the different endmember components.Units: Pa.

Parameter name: Reference shear viscosity#

Default value: 5e20

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity \(\eta_0\) of the solid matrix. This viscosity may be modified by both temperature and porosity dependencies. Units: \(Pa \, s\).

Parameter name: Reference specific heat capacities#

Default value: 139.546209, 161.546581, 52.0016403, 73.1147154, 79.5326013, 79.5326013, 79.5326013

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

Documentation: List of specific heat capacities for each different endmember at the reference temperature and reference pressure.Units: J/kg/K.

Parameter name: Reference temperature#

Default value: 298.15

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

Documentation: Reference temperature used to compute the material propertiesof the different endmember components.Units: K.

Parameter name: Reference thermal expansivities#

Default value: 1.87e-05, 1.87e-05, 3.22e-05, 3.11e-05, 2.9614332469401705e-05, 2.06e-05, 2.06e-05

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

Documentation: List of thermal expansivities for each different endmember at the reference temperature and reference pressure.Units: 1/K.

Parameter name: Reference volumes#

Default value: 2.534e-05, 2.445e-05, 1.206e-05, 1.125e-05, 1.2325484447664221e-05, 1.218e-05, 1.218e-05

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

Documentation: Reference volumes of the different endmembers.Units: \(m^3\).

Parameter name: Second coefficients for specific heat polynomial#

Default value: -4.13886524e+06, -3.57533814e+06, -1.19540964e+06, -7.33679285e+05, -1.61692272e+06, -1.61692272e+06, -1.61692272e+06

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

Documentation: The second of three coefficients that are used to compute the specific heat capacities for each different endmember at the reference temperature and reference pressure. This coefficient describes the part of the temperature dependence that scales as the inverse of the square of the temperature. Units: J K/kg.

Parameter name: Second derivatives of the bulk modulus#

Default value: -1.6e-11, -1.6e-11, -3.2e-11, -2.4e-11, -3.9742163085937504e-11, -2.14e-11, -2.14e-11

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

Documentation: The second pressure derivative of the bulk modulus at the reference temperature and reference pressure for each different endmember component.Units: 1/Pa.

Parameter name: Thermal bulk viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of the bulk viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \(W/m/K\).

Parameter name: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of the shear viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Parameter name: Third coefficients for specific heat polynomial#

Default value: -464.775577, -1112.54791, 25.5067110, -592.994207, -562.222634, -562.222634, -562.222634

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

Documentation: The third of three coefficients that are used to compute the specific heat capacities for each different endmember at the reference temperature and reference pressure. This coefficient describes the part of the temperature dependence that scales as the inverse of the square root of the temperatureUnits: J/kg/sqrt(K).

Subsection: Material model / Melt global#

Parameter name: Depletion density change#

Default value: 0.0

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

Documentation: The density contrast between material with a depletion of 1 and a depletion of zero. Negative values indicate lower densities of depleted material. Depletion is indicated by the compositional field with the name peridotite. Not used if this field does not exist in the model. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Depletion solidus change#

Default value: 200.0

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

Documentation: The solidus temperature change for a depletion of 100%. For positive values, the solidus gets increased for a positive peridotite field (depletion) and lowered for a negative peridotite field (enrichment). Scaling with depletion is linear. Only active when fractional melting is used. Units: \si{\kelvin}.

Parameter name: Exponential depletion strengthening factor#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: \(\alpha_F\): exponential dependency of viscosity on the depletion field \(F\) (called peridotite). Dimensionless factor. With a value of 0.0 (the default) the viscosity does not depend on the depletion. The effective viscosity increasedue to depletion is defined as \(exp( \alpha_F * F)\). Rationale: melting dehydrates the source rock by removing most of the volatiles,and makes it stronger. Hirth and Kohlstedt (1996) report typical values around a factor 100 to 1000 viscosity contrast between wet and dry rocks, although some experimental studies report a smaller (factor 10) contrast (e.g. Fei et al., 2013).

Parameter name: Exponential melt weakening factor#

Default value: 27.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The porosity dependence of the viscosity. Units: dimensionless.

Parameter name: Include melting and freezing#

Default value: true

Pattern: [Bool]

Documentation: Whether to include melting and freezing (according to a simplified linear melting approximation in the model (if true), or not (if false).

Parameter name: Maximum Depletion viscosity change#

Default value: 1.0e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: \(\Delta \eta_{F,max}\): maximum depletion strengthening of viscosity. Rationale: melting dehydrates the source rock by removing most of the volatiles,and makes it stronger. Hirth and Kohlstedt (1996) report typical values around a factor 100 to 1000 viscosity contrast between wet and dry rocks, although some experimental studies report a smaller (factor 10) contrast (e.g. Fei et al., 2013).

Parameter name: Melt bulk modulus derivative#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the pressure derivative of the melt bulk modulus. Units: None.

Parameter name: Melt compressibility#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the compressibility of the melt. Units: \si{\per\pascal}.

Parameter name: Melting time scale for operator splitting#

Default value: 1e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: In case the operator splitting scheme is used, the porosity field can not be set to a new equilibrium melt fraction instantly, but the model has to provide a melting time scale instead. This time scale defines how fast melting happens, or more specifically, the parameter defines the time after which the deviation of the porosity from the equilibrium melt fraction will be reduced to a fraction of \(1/e\). So if the melting time scale is small compared to the time step size, the reaction will be so fast that the porosity is very close to the equilibrium melt fraction after reactions are computed. Conversely, if the melting time scale is large compared to the time step size, almost no melting and freezing will occur.

Also note that the melting time scale has to be larger than or equal to the reaction time step used in the operator splitting scheme, otherwise reactions can not be computed. If the model does not use operator splitting, this parameter is not used. Units: yr or s, depending on the “Use years in output instead of seconds” parameter.

Parameter name: Pressure solidus change#

Default value: 6e-8

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

Documentation: The linear solidus temperature change with pressure. For positive values, the solidus gets increased for positive pressures. Units: \si{\per\pascal}.

Parameter name: Reference bulk viscosity#

Default value: 1e22

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant bulk viscosity \(\xi_0\) of the solid matrix. This viscosity may be modified by both temperature and porosity dependencies. Units: \si{\pascal\second}.

Parameter name: Reference melt density#

Default value: 2500.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density of the melt/fluid\(\rho_{f,0}\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference melt viscosity#

Default value: 10.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant melt viscosity \(\eta_f\). Units: \si{\pascal\second}.

Parameter name: Reference permeability#

Default value: 1e-8

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

Documentation: Reference permeability of the solid host rock.Units: \si{\meter\squared}.

Parameter name: Reference shear viscosity#

Default value: 5e20

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity \(\eta_0\) of the solid matrix. This viscosity may be modified by both temperature and porosity dependencies. Units: \si{\pascal\second}.

Parameter name: Reference solid density#

Default value: 3000.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density of the solid \(\rho_{s,0}\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). The reference temperature is used in both the density and viscosity formulas. Units: \si{\kelvin}.

Parameter name: Solid compressibility#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the compressibility of the solid matrix. Units: \si{\per\pascal}.

Parameter name: Surface solidus#

Default value: 1300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Solidus for a pressure of zero. Units: \si{\kelvin}.

Parameter name: Thermal bulk viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of the bulk viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

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: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of the shear viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Subsection: Material model / Melt simple#

Parameter name: A1#

Default value: 1085.7

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

Documentation: Constant parameter in the quadratic function that approximates the solidus of peridotite. Units: \si{\degreeCelsius}.

Parameter name: A2#

Default value: 1.329e-7

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the solidus of peridotite. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: A3#

Default value: -5.1e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the solidus of peridotite. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: B1#

Default value: 1475.0

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

Documentation: Constant parameter in the quadratic function that approximates the lherzolite liquidus used for calculating the fraction of peridotite-derived melt. Units: \si{\degreeCelsius}.

Parameter name: B2#

Default value: 8.0e-8

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the lherzolite liquidus used for calculating the fraction of peridotite-derived melt. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: B3#

Default value: -3.2e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the lherzolite liquidus used for calculating the fraction of peridotite-derived melt. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: C1#

Default value: 1780.0

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

Documentation: Constant parameter in the quadratic function that approximates the liquidus of peridotite. Units: \si{\degreeCelsius}.

Parameter name: C2#

Default value: 4.50e-8

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

Documentation: Prefactor of the linear pressure term in the quadratic function that approximates the liquidus of peridotite. Units: \si{\degreeCelsius\per\pascal}.

Parameter name: C3#

Default value: -2.0e-18

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

Documentation: Prefactor of the quadratic pressure term in the quadratic function that approximates the liquidus of peridotite. Units: \si{\degreeCelsius\per\pascal\squared}.

Parameter name: Depletion density change#

Default value: 0.0

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

Documentation: The density contrast between material with a depletion of 1 and a depletion of zero. Negative values indicate lower densities of depleted material. Depletion is indicated by the compositional field with the name peridotite. Not used if this field does not exist in the model. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Depletion solidus change#

Default value: 200.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The solidus temperature change for a depletion of 100%. For positive values, the solidus gets increased for a positive peridotite field (depletion) and lowered for a negative peridotite field (enrichment). Scaling with depletion is linear. Only active when fractional melting is used. Units: \si{\kelvin}.

Parameter name: Exponential melt weakening factor#

Default value: 27.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The porosity dependence of the viscosity. Units: dimensionless.

Parameter name: Freezing rate#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Freezing rate of melt when in subsolidus regions. If this parameter is set to a number larger than 0.0, it specifies the fraction of melt that will freeze per year (or per second, depending on the “Use years in output instead of seconds” parameter), as soon as the porosity exceeds the equilibrium melt fraction, and the equilibrium melt fraction falls below the depletion. In this case, melt will freeze according to the given rate until one of those conditions is not fulfilled anymore. The reasoning behind this is that there should not be more melt present than the equilibrium melt fraction, as melt production decreases with increasing depletion, but the freezing process of melt also reduces the depletion by the same amount, and as soon as the depletion falls below the equilibrium melt fraction, we expect that material should melt again (no matter how much melt is present). This is quite a simplification and not a realistic freezing parameterization, but without tracking the melt composition, there is no way to compute freezing rates accurately. If this parameter is set to zero, no freezing will occur. Note that freezing can never be faster than determined by the “Melting time scale for operator splitting”. The product of the “Freezing rate” and the “Melting time scale for operator splitting” defines how fast freezing occurs with respect to melting (if the product is 0.5, melting will occur twice as fast as freezing). Units: 1/yr or 1/s, depending on the “Use years in output instead of seconds” parameter.

Parameter name: Mass fraction cpx#

Default value: 0.15

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

Documentation: Mass fraction of clinopyroxene in the peridotite to be molten. Units: non-dimensional.

Parameter name: Melt bulk modulus derivative#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the pressure derivative of the melt bulk modulus. Units: None.

Parameter name: Melt compressibility#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the compressibility of the melt. Units: \si{\per\pascal}.

Parameter name: Melt extraction depth#

Default value: 1000.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Depth above that melt will be extracted from the model, which is done by a negative reaction term proportional to the porosity field. Units: \si{\meter}.

Parameter name: Melting time scale for operator splitting#

Default value: 1e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Because the operator splitting scheme is used, the porosity field can not be set to a new equilibrium melt fraction instantly, but the model has to provide a melting time scale instead. This time scale defines how fast melting happens, or more specifically, the parameter defines the time after which the deviation of the porosity from the equilibrium melt fraction will be reduced to a fraction of \(1/e\). So if the melting time scale is small compared to the time step size, the reaction will be so fast that the porosity is very close to the equilibrium melt fraction after reactions are computed. Conversely, if the melting time scale is large compared to the time step size, almost no melting and freezing will occur.

Also note that the melting time scale has to be larger than or equal to the reaction time step used in the operator splitting scheme, otherwise reactions can not be computed. Units: yr or s, depending on the “Use years in output instead of seconds” parameter.

Parameter name: Peridotite melting entropy change#

Default value: -300.

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

Documentation: The entropy change for the phase transition from solid to melt of peridotite. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference bulk viscosity#

Default value: 1e22

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant bulk viscosity \(\xi_0\) of the solid matrix. This viscosity may be modified by both temperature and porosity dependencies. Units: \si{\pascal\second}.

Parameter name: Reference melt density#

Default value: 2500.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density of the melt/fluid\(\rho_{f,0}\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference melt viscosity#

Default value: 10.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant melt viscosity \(\eta_f\). Units: \si{\pascal\second}.

Parameter name: Reference permeability#

Default value: 1e-8

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

Documentation: Reference permeability of the solid host rock.Units: \si{\meter\squared}.

Parameter name: Reference shear viscosity#

Default value: 5e20

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity \(\eta_0\) of the solid matrix. This viscosity may be modified by both temperature and porosity dependencies. Units: \si{\pascal\second}.

Parameter name: Reference solid density#

Default value: 3000.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density of the solid \(\rho_{s,0}\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). The reference temperature is used in both the density and viscosity formulas. Units: \si{\kelvin}.

Parameter name: Solid compressibility#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the compressibility of the solid matrix. Units: \si{\per\pascal}.

Parameter name: Thermal bulk viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of the bulk viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

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: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of the shear viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Parameter name: Use fractional melting#

Default value: false

Pattern: [Bool]

Documentation: If fractional melting should be used (if true), including a solidus change based on depletion (in this case, the amount of melt that has migrated away from its origin), and freezing of melt when it has moved to a region with temperatures lower than the solidus; or if batch melting should be used (if false), assuming that the melt fraction only depends on temperature and pressure, and how much melt has already been generated at a given point, but not considering movement of melt in the melting parameterization.

Note that melt does not freeze unless the ’Freezing rate’ parameter is set to a value larger than 0.

Parameter name: Use full compressibility#

Default value: false

Pattern: [Bool]

Documentation: If the compressibility should be used everywhere in the code (if true), changing the volume of material when the density changes, or only in the momentum conservation and advection equations (if false).

Parameter name: beta#

Default value: 1.5

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

Documentation: Exponent of the melting temperature in the melt fraction calculation. Units: non-dimensional.

Parameter name: r1#

Default value: 0.5

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

Documentation: Constant in the linear function that approximates the clinopyroxene reaction coefficient. Units: non-dimensional.

Parameter name: r2#

Default value: 8e-11

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

Documentation: Prefactor of the linear pressure term in the linear function that approximates the clinopyroxene reaction coefficient. Units: \si{\per\pascal}.

Subsection: Material model / Modified Tait model#

Parameter name: Einstein temperature#

Default value: 600.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The Einstein temperature at the reference pressure and temperature. Units: \si{\kelvin}.

Parameter name: Reference bulk modulus derivative#

Default value: 4.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the first pressure derivative of the isothermal bulk modulus at the reference pressure and temperature. Units: None.

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The density at the reference pressure and temperature. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference isothermal bulk modulus#

Default value: 125e9

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The isothermal bulk modulus at the reference pressure and temperature. Units: \si{\pascal}.

Parameter name: Reference pressure#

Default value: 1e5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference pressure \(P_0\). Units: \si{\pascal}.

Parameter name: Reference temperature#

Default value: 298.15

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Reference thermal expansivity#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The thermal expansion coefficient at the reference pressure and temperature. Units: \si{\per\kelvin}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Viscosity#

Default value: 1e21

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity \(\eta_0\). Units: \si{\pascal\second}.

Subsection: Material model / Modified Tait model / Reference heat capacity 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: 1.25e3

Pattern: [Anything]

Documentation:

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: Material model / Multicomponent#

Parameter name: Densities#

Default value: 3300.

Pattern: [Anything]

Documentation: List of densities for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Heat capacities#

Default value: 1250.

Pattern: [Anything]

Documentation: List of specific heats \(C_p\) for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Specific heats#

Alias: Heat capacities

Deprecation Status: false

Parameter name: Thermal conductivities#

Default value: 4.7

Pattern: [Anything]

Documentation: List of thermal conductivities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansivities#

Default value: 0.000040

Pattern: [Anything]

Documentation: List of thermal expansivities for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\per\kelvin}.

Parameter name: Viscosities#

Default value: 1.e21

Pattern: [Anything]

Documentation: List of viscosities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\pascal\second}.

Parameter name: Viscosity averaging scheme#

Default value: harmonic

Pattern: [Selection arithmetic|harmonic|geometric|maximum composition ]

Documentation: When more than one compositional field is present at a point with different viscosities, we need to come up with an average viscosity at that point. Select a weighted harmonic, arithmetic, geometric, or maximum composition.

Subsection: Material model / Multicomponent compressible#

Parameter name: Isochoric specific heats#

Default value: 1250.

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

Documentation: List of isochoric specific heats \(C_v\) for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Isothermal bulk modulus pressure derivatives#

Default value: 4.

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

Documentation: List of isothermal pressure derivatives of the bulk moduli for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: [].

Parameter name: Reference densities#

Default value: 3300.

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

Documentation: List of densities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference isothermal compressibilities#

Default value: 4e-12

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

Documentation: List of isothermal compressibilities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\per\pascal}.

Parameter name: Reference temperatures#

Default value: 298.15

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

Documentation: List of reference temperatures \(T_0\) for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\kelvin}.

Parameter name: Reference thermal expansivities#

Default value: 4.e-5

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

Documentation: List of thermal expansivities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\per\kelvin}.

Parameter name: Thermal conductivities#

Default value: 4.7

Pattern: [Anything]

Documentation: List of thermal conductivities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Viscosities#

Default value: 1.e21

Pattern: [Anything]

Documentation: List of viscosities for background mantle and compositional fields,for a total of N+1 values, where N is the number of compositional fields.If only one value is given, then all use the same value. Units: \si{\pascal\second}.

Parameter name: Viscosity averaging scheme#

Default value: harmonic

Pattern: [Selection arithmetic|harmonic|geometric|maximum composition ]

Documentation: When more than one compositional field is present at a point with different viscosities, we need to come up with an average viscosity at that point. Select a weighted harmonic, arithmetic, geometric, or maximum composition.

Subsection: Material model / Nondimensional model#

Parameter name: Di#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Dissipation number. Pick 0.0 for incompressible computations.

Parameter name: Ra#

Default value: 1e4

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Rayleigh number Ra

Parameter name: Reference density#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Use TALA#

Default value: false

Pattern: [Bool]

Documentation: Whether to use the TALA instead of the ALA approximation.

Parameter name: Viscosity depth prefactor#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Exponential depth prefactor for viscosity.

Parameter name: Viscosity temperature prefactor#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Exponential temperature prefactor for viscosity.

Parameter name: gamma#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Grueneisen parameter

Subsection: Material model / PerpleX lookup model#

Parameter name: Maximum material pressure#

Default value: 1.e12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the maximum pressure used to query PerpleX. Units: \si{\pascal}.

Parameter name: Maximum material temperature#

Default value: 6000.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the maximum temperature used to query PerpleX. Units: \si{\kelvin}.

Parameter name: Minimum material pressure#

Default value: 1.e5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the minimum pressure used to query PerpleX. Units: \si{\pascal}.

Parameter name: Minimum material temperature#

Default value: 0.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the minimum temperature used to query PerpleX. Units: \si{\kelvin}.

Parameter name: PerpleX input file name#

Default value: rock.dat

Pattern: [Anything]

Documentation: The name of the PerpleX input file (should end with .dat).

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Viscosity#

Default value: 5e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the viscosity \(\eta\). Units: \si{\pascal\second}.

Subsection: Material model / Replace lithosphere viscosity#

Parameter name: Base model#

Default value: simple

Pattern: [Selection Steinberger|ascii reference profile|averaging|compositing|composition reaction|depth dependent|diffusion dislocation|drucker prager|grain size|latent heat|latent heat melt|melt boukare|melt global|melt simple|modified tait|multicomponent|multicomponent compressible|nondimensional|perplex lookup|replace lithosphere viscosity|simple|simple compressible|simpler|visco plastic|viscoelastic ]

Documentation: The name of a material model that will be modified by a replacingthe viscosity in the lithosphere by a constant value. Valid values for this parameter are the names of models that are also valid for the “Material models/Model name” parameter. See the documentation for more information.

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 viscosity#

Default value: 1e23

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The viscosity 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: Material model / Simple compressible model#

Parameter name: Reference compressibility#

Default value: 4e-12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the reference compressibility. Units: \si{\per\pascal}.

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Viscosity#

Default value: 1000000000000000000000.000000

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the viscosity \(\eta\). Units: \si{\pascal\second}.

Subsection: Material model / Simple model#

Parameter name: Composition viscosity prefactor#

Default value: 1.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: A linear dependency of viscosity on the first compositional field. Dimensionless prefactor. With a value of 1.0 (the default) the viscosity does not depend on the composition. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\xi\) there.

Parameter name: Density differential for compositional field 1#

Default value: 0.

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

Documentation: If compositional fields are used, then one would frequently want to make the density depend on these fields. In this simple material model, we make the following assumptions: if no compositional fields are used in the current simulation, then the density is simply the usual one with its linear dependence on the temperature. If there are compositional fields, then the material model determines how many of them influence the density. The composition-dependence adds a term of the kind \(+\Delta \rho \; c_1(\mathbf x)\). This parameter describes the value of \(\Delta \rho\). Units: \si{\kilogram\per\meter\cubed}/unit change in composition.

Parameter name: Maximum thermal prefactor#

Default value: 1.0e2

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The maximum value of the viscosity prefactor associated with temperature dependence.

Parameter name: Minimum thermal prefactor#

Default value: 1.0e-2

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The minimum value of the viscosity prefactor associated with temperature dependence.

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). The reference temperature is used in both the density and viscosity formulas. Units: \si{\kelvin}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Thermal viscosity exponent#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The temperature dependence of viscosity. Dimensionless exponent. See the general documentation of this model for a formula that states the dependence of the viscosity on this factor, which is called \(\beta\) there.

Parameter name: Viscosity#

Default value: 5e24

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the constant viscosity \(\eta_0\). This viscosity may be modified by both temperature and compositional dependencies. Units: \si{\pascal\second}.

Subsection: Material model / Simpler model#

Parameter name: Reference density#

Default value: 3300.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference density \(\rho_0\). Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Reference specific heat#

Default value: 1250.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the specific heat \(C_p\). Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). The reference temperature is used in both the density and viscosity formulas. Units: \si{\kelvin}.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansion coefficient#

Default value: 2e-5

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

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

Parameter name: Viscosity#

Default value: 5000000000000000452984832.000000

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the viscosity \(\eta\). Units: \si{\pascal\second}.

Subsection: Material model / Steinberger model#

Parameter name: Bilinear interpolation#

Default value: true

Pattern: [Bool]

Documentation: Whether to use bilinear interpolation to compute material properties (slower but more accurate).

Parameter name: Data directory#

Default value: $ASPECT_SOURCE_DIR/data/material-model/steinberger/

Pattern: [DirectoryName]

Documentation: The path to the model data. 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: Derivatives file names#

Default value:

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

Documentation: The file names of the enthalpy derivatives data. List with as many components as active compositional fields (material data is assumed to be in order with the ordering of the fields).

Parameter name: Latent heat#

Default value: false

Pattern: [Bool]

Documentation: Whether to include latent heat effects in the calculation of thermal expansivity and specific heat. If true, ASPECT follows the approach of Nakagawa et al. 2009, using pressure and temperature derivatives of the enthalpy to calculate the thermal expansivity and specific heat. If false, ASPECT uses the thermal expansivity and specific heat values from the material properties table.

Parameter name: Lateral viscosity file name#

Default value: temp-viscosity-prefactor.txt

Pattern: [Anything]

Documentation: The file name of the lateral viscosity data.

Parameter name: Material file format#

Default value: perplex

Pattern: [Selection perplex|hefesto ]

Documentation: The material file format to be read in the property tables.

Parameter name: Material file names#

Default value: pyr-ringwood88.txt

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

Documentation: The file names of the material data (material data is assumed to be in order with the ordering of the compositional fields). Note that there are three options on how many files need to be listed here: 1. If only one file is provided, it is used for the whole model domain, and compositional fields are ignored. 2. If there is one more file name than the number of compositional fields, then the first file is assumed to define a ‘background composition’ that is modified by the compositional fields. If there are exactly as many files as compositional fields, the fields are assumed to represent the fractions of different materials and the average property is computed as a sum of the value of the compositional field times the material property of that field.

Parameter name: Maximum latent heat substeps#

Default value: 1

Pattern: [Integer range 1…2147483647 (inclusive)]

Documentation: The maximum number of substeps over the temperature pressure range to calculate the averaged enthalpy gradient over a cell.

Parameter name: Maximum lateral viscosity variation#

Default value: 1e2

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The relative cutoff value for lateral viscosity variations caused by temperature deviations. The viscosity may vary laterally by this factor squared.

Parameter name: Maximum thermal conductivity#

Default value: 1000

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The maximum thermal conductivity that is allowed in the model. Larger values will be cut off.

Parameter name: Maximum viscosity#

Default value: 1e23

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The maximum viscosity that is allowed in the viscosity calculation. Larger values will be cut off.

Parameter name: Minimum viscosity#

Default value: 1e19

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The minimum viscosity that is allowed in the viscosity calculation. Smaller values will be cut off.

Parameter name: Number lateral average bands#

Default value: 10

Pattern: [Integer range 1…2147483647 (inclusive)]

Documentation: Number of bands to compute laterally averaged temperature within.

Parameter name: Pressure dependencies of thermal conductivity#

Default value: 3.3e-10, 3.4e-10, 3.6e-10, 1.05e-10

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

Documentation: A list of values that determine the linear scaling of the thermal conductivity with the pressure in the ’p-T-dependent’ Thermal conductivity formulation. Units: \si{\watt\per\meter\per\kelvin\per\pascal}.

Parameter name: Radial viscosity file name#

Default value: radial-visc.txt

Pattern: [Anything]

Documentation: The file name of the radial viscosity data.

Parameter name: Reference temperatures for thermal conductivity#

Default value: 300, 300, 300, 1200

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

Documentation: A list of values of reference temperatures used to determine the temperature-dependence of the thermal conductivity in the ’p-T-dependent’ Thermal conductivity formulation. Units: \si{\kelvin}.

Parameter name: Reference thermal conductivities#

Default value: 2.47, 3.81, 3.52, 4.9

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

Documentation: A list of base values of the thermal conductivity for each of the horizontal layers in the ’p-T-dependent’ Thermal conductivity formulation. Pressure- and temperature-dependence will be appliedon top of this base value, according to the parameters ’Pressure dependencies of thermal conductivity’ and ’Reference temperatures for thermal conductivity’. Units: \si{\watt\per\meter\per\kelvin}

Parameter name: Saturation prefactors#

Default value: 0, 0, 0, 1

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

Documentation: A list of values that indicate how a given layer in the conductivity formulation should take into account the effects of saturation on the temperature-dependence of the thermal conducitivity. This factor is multiplied with a saturation function based on the theory of Roufosse and Klemens, 1974. A value of 1 reproduces the formulation of Stackhouse et al. (2015), a value of 0 reproduces the formulation of Tosi et al., (2013). Units: none.

Parameter name: Thermal conductivity#

Default value: 4.7

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The value of the thermal conductivity \(k\). Only used in case the ’constant’ Thermal conductivity formulation is selected. Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal conductivity exponents#

Default value: 0.48, 0.56, 0.61, 1.0

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

Documentation: A list of exponents in the temperature-dependent term of the ’p-T-dependent’ Thermal conductivity formulation. Note that this exponent is not used (and should have a value of 1) in the formulation of Stackhouse et al. (2015). Units: none.

Parameter name: Thermal conductivity formulation#

Default value: constant

Pattern: [Selection constant|p-T-dependent ]

Documentation: Which law should be used to compute the thermal conductivity. The ’constant’ law uses a constant value for the thermal conductivity. The ’p-T-dependent’ formulation uses equations from Stackhouse et al. (2015): First-principles calculations of the lattice thermal conductivity of the lower mantle (https://doi.org/10.1016/j.epsl.2015.06.050), and Tosi et al. (2013): Mantle dynamics with pressure- and temperature-dependent thermal expansivity and conductivity (https://doi.org/10.1016/j.pepi.2013.02.004) to compute the thermal conductivity in dependence of temperature and pressure. The thermal conductivity parameter sets can be chosen in such a way that either the Stackhouse or the Tosi relations are used. The conductivity description can consist of several layers with different sets of parameters. Note that the Stackhouse parametrization is only valid for the lower mantle (bridgmanite).

Parameter name: Thermal conductivity transition depths#

Default value: 410000, 520000, 660000

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

Documentation: A list of depth values that indicate where the transitions between the different conductivity parameter sets should occur in the ’p-T-dependent’ Thermal conductivity formulation (in most cases, this will be the depths of major mantle phase transitions). Units: \si{\meter}.

Parameter name: Use lateral average temperature for viscosity#

Default value: true

Pattern: [Bool]

Documentation: Whether to use to use the laterally averaged temperature instead of the adiabatic temperature as reference for the viscosity calculation. This ensures that the laterally averaged viscosities remain more or less constant over the model runtime. This behaviour might or might not be desired.

Subsection: Material model / Visco Plastic#

Parameter name: Activation energies for Peierls creep#

Default value: 320e3

Pattern: [Anything]

Documentation: List of activation energies, \(E\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\joule\per\mole}.

Parameter name: Activation energies for diffusion creep#

Default value: 375e3

Pattern: [Anything]

Documentation: List of activation energies, \(E_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\joule\per\mole}.

Parameter name: Activation energies for dislocation creep#

Default value: 530e3

Pattern: [Anything]

Documentation: List of activation energies, \(E_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\joule\per\mole}.

Parameter name: Activation volumes for Peierls creep#

Default value: 1.4e-5

Pattern: [Anything]

Documentation: List of activation volumes, \(V\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\meter\cubed\per\mole}.

Parameter name: Activation volumes for diffusion creep#

Default value: 6e-6

Pattern: [Anything]

Documentation: List of activation volumes, \(V_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\meter\cubed\per\mole}.

Parameter name: Activation volumes for dislocation creep#

Default value: 1.4e-5

Pattern: [Anything]

Documentation: List of activation volumes, \(V_a\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\meter\cubed\per\mole}.

Parameter name: Adiabat temperature gradient for viscosity#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Add an adiabatic temperature gradient to the temperature used in the flow law so that the activation volume is consistent with what one would use in a earth-like (compressible) model. Default is set so this is off. Note that this is a linear approximation of the real adiabatic gradient, which is okay for the upper mantle, but is not really accurate for the lower mantle. Using a pressure gradient of 32436 Pa/m, then a value of 0.3 K/km = 0.0003 K/m = 9.24e-09 K/Pa gives an earth-like adiabat.Units: \si{\kelvin\per\pascal}.

Parameter name: Allow negative pressures in plasticity#

Default value: false

Pattern: [Bool]

Documentation: Whether to allow negative pressures to be used in the computation of plastic yield stresses and viscosities. Setting this parameter to true may be advantageous in models without gravity where the dynamic stresses are much higher than the lithostatic pressure. If false, the minimum pressure in the plasticity formulation will be set to zero.

Parameter name: Angles of internal friction#

Default value: 0.

Pattern: [Anything]

Documentation: List of angles of internal friction, \(\phi\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. For a value of zero, in 2d the von Mises criterion is retrieved. Angles higher than 30 degrees are harder to solve numerically. Units: degrees.

Parameter name: Cohesion strain weakening factors#

Default value: 1.

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

Documentation: List of cohesion strain weakening factors for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Cohesions#

Default value: 1e20

Pattern: [Anything]

Documentation: List of cohesions, \(C\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. The extremely large default cohesion value (1e20 Pa) prevents the viscous stress from exceeding the yield stress. Units: \si{\pascal}.

Parameter name: Constant viscosity prefactors#

Default value: 1.0

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

Documentation: List of constant viscosity prefactors (i.e., multiplicative factors) for background material and compositional fields, for a total of N+1 where N is the number of compositional fields. Units: none.

Parameter name: Cutoff stresses for Peierls creep#

Default value: 0.0

Pattern: [Anything]

Documentation: List of the Stress thresholds below which the strain rate is solved for as a quadratic function of stress to aid with convergence when stress exponent n=0. Units: \si{\pascal}

Parameter name: Define thermal conductivities#

Default value: false

Pattern: [Bool]

Documentation: Whether to directly define thermal conductivities for each compositional field instead of calculating the values through the specified thermal diffusivities, densities, and heat capacities.

Parameter name: Define transition by depth instead of pressure#

Default value: true

Pattern: [Bool]

Documentation: Whether to list phase transitions by depth or pressure. If this parameter is true, then the input file will use Phase transitions depths and Phase transition widths to define the phase transition. If it is false, the parameter file will read in phase transition data from Phase transition pressures and Phase transition pressure widths.

Parameter name: Densities#

Default value: 3300.

Pattern: [Anything]

Documentation: List of densities for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Dynamic angles of internal friction#

Default value: 2

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

Documentation: List of dynamic angles of internal friction, \(\phi\), for background material and compositional fields, for a total of N\(+\)1 values, where N is the number of compositional fields. Dynamic angles of friction are used as the current friction angle when the effective strain rate is well above the ’dynamic characteristic strain rate’. Units: \si{\degree}.

Parameter name: Dynamic characteristic strain rate#

Default value: 1e-12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The characteristic strain rate value at which the angle of friction is equal to \(\mu = (\mu_s+\mu_d)/2\). When the effective strain rate is very high, the dynamic angle of friction is taken, when it is very low, the static angle of internal friction is used. Around the dynamic characteristic strain rate, there is a smooth gradient from the static to the dynamic angle of internal friction. Units: \si{\per\second}.

Parameter name: Dynamic friction smoothness exponent#

Default value: 1

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: An exponential factor in the equation for the calculation of the friction angle when a static and a dynamic angle of internal friction are specified. A factor of 1 returns the equation to Equation (13) in \cite{van_dinther_seismic_2013}. A factor between 0 and 1 makes the curve of the friction angle vs. the strain rate smoother, while a factor \(>\) 1 makes the change between static and dynamic friction angle more steplike. Units: none.

Parameter name: Elastic damper viscosity#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Viscosity of a viscous damper that acts in parallel with the elastic element to stabilize behavior. Units: \si{\pascal\second}

Parameter name: Elastic shear moduli#

Default value: 75.0e9

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

Documentation: List of elastic shear moduli, \(G\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. The default value of 75 GPa is representative of mantle rocks. Units: Pa.

Parameter name: End plasticity strain weakening intervals#

Default value: 1.

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

Documentation: List of strain weakening interval final strains for the cohesion and friction angle parameters of the background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: End prefactor strain weakening intervals#

Default value: 1.

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

Documentation: List of strain weakening interval final strains for the diffusion and dislocation prefactor parameters of the background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Fixed elastic time step#

Default value: 1.e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The fixed elastic time step \(dte\). Units: years if the ’Use years in output instead of seconds’ parameter is set; seconds otherwise.

Parameter name: Friction mechanism#

Default value: none

Pattern: [Selection none|dynamic friction|function ]

Documentation: Whether to make the friction angle dependent on strain rate or not. This rheology is intended to be used together with the visco-plastic rheology model.

\item “none”: No dependence of the friction angle is applied.

\item “dynamic friction”: The friction angle is rate dependent.When ’dynamic angles of internal friction’ are specified, the friction angle will be weakened for high strain rates with: \(\mu = \mu_d + \frac{\mu_s-\mu_d}{1+\frac{\dot{\epsilon}_{ii}}{\dot{\epsilon}_C}}^x\) where \(\mu_s\) and \(\mu_d\) are the friction angles at low and high strain rates, respectively. \(\dot{\epsilon}_{ii}\) is the second invariant of the strain rate and \(\dot{\epsilon}_C\) is the ’dynamic characteristic strain rate’ where \(\mu = (\mu_s+\mu_d)/2\). The ’dynamic friction smoothness exponent’ x controls how smooth or step-like the change from \(\mu_s\) to \(\mu_d\) is. The equation is modified after Equation (13) in \cite{van_dinther_seismic_2013}. \(\mu_s\) and \(\mu_d\) can be specified by setting ’Angles of internal friction’ and ’Dynamic angles of internal friction’, respectively. This relationship is similar to rate-and-state friction constitutive relationships, which are applicable to the strength of rocks during earthquakes.

\item “function”: Specify the friction angle as a function of space and time for each compositional field.

Parameter name: Friction strain weakening factors#

Default value: 1.

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

Documentation: List of friction strain weakening factors for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Grain size#

Default value: 1e-3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Units: \si{\meter}.

Parameter name: Grain size exponents for diffusion creep#

Default value: 3.

Pattern: [Anything]

Documentation: List of grain size exponents, \(m_{\text{diffusion}}\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Heat capacities#

Default value: 1250.

Pattern: [Anything]

Documentation: List of specific heats \(C_p\) for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Include Peierls creep#

Default value: false

Pattern: [Bool]

Documentation: Whether to include Peierls creep in the rheological formulation.

Parameter name: Include viscoelasticity#

Default value: false

Pattern: [Bool]

Documentation: Whether to include elastic effects in the rheological formulation.

Parameter name: Maximum Peierls strain rate iterations#

Default value: 40

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

Documentation: Maximum number of iterations to find the correct Peierls strain rate.

Parameter name: Maximum viscosity#

Default value: 1e28

Pattern: [Anything]

Documentation: Upper cutoff for effective viscosity. Units: \si{\pascal\second}. List with as many components as active compositional fields (material data is assumed to be in order with the ordering of the fields).

Parameter name: Maximum yield stress#

Default value: 1e12

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Limits the maximum value of the yield stress determined by the Drucker-Prager plasticity parameters. Default value is chosen so this is not automatically used. Values of 100e6–1000e6 \(Pa\) have been used in previous models. Units: \si{\pascal}.

Parameter name: Minimum strain rate#

Default value: 1.0e-20

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Stabilizes strain dependent viscosity. Units: \si{\per\second}.

Parameter name: Minimum viscosity#

Default value: 1e17

Pattern: [Anything]

Documentation: Lower cutoff for effective viscosity. Units: \si{\pascal\second}. List with as many components as active compositional fields (material data is assumed to be in order with the ordering of the fields).

Parameter name: Peierls creep flow law#

Default value: viscosity approximation

Pattern: [Selection viscosity approximation|exact ]

Documentation: Select what type of Peierls creep flow law to use. Currently, the available options are ’exact’, which uses a Newton-Raphson iterative method to find the stress and then compute viscosity, and ’viscosity approximation’, in which viscosity is an explicit function of the strain rate invariant, rather than stress.

Parameter name: Peierls fitting parameters#

Default value: 0.17

Pattern: [Anything]

Documentation: List of fitting parameters \(\gamma\) between stress \(\sigma\) and the Peierls stress \(\sigma_{\text{peierls}}\) for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: none

Parameter name: Peierls glide parameters p#

Default value: 0.5

Pattern: [Anything]

Documentation: List of the first Peierls creep glide parameters, \(p\), for background and compositional fields for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: none

Parameter name: Peierls glide parameters q#

Default value: 1.0

Pattern: [Anything]

Documentation: List of the second Peierls creep glide parameters, \(q\), for background and compositional fields for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: none

Parameter name: Peierls strain rate residual tolerance#

Default value: 1e-22

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Tolerance for the iterative solve to find the correct Peierls creep strain rate.

Parameter name: Peierls stresses#

Default value: 5.e9

Pattern: [Anything]

Documentation: List of stress limits for Peierls creep \(\sigma_{\text{peierls}}\) for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\pascal}

Parameter name: Phase transition Clapeyron slopes#

Default value:

Pattern: [Anything]

Documentation: A list of Clapeyron slopes for each phase transition. A positive Clapeyron slope indicates that the phase transition will occur in a greater depth, if the temperature is higher than the one given in Phase transition temperatures and in a smaller depth, if the temperature is smaller than the one given in Phase transition temperatures. For negative slopes the other way round. List must have the same number of entries as Phase transition depths. Units: \si{\pascal\per\kelvin}.

Parameter name: Phase transition depths#

Default value:

Pattern: [Anything]

Documentation: A list of depths where phase transitions occur. Values must monotonically increase. Units: \si{\meter}.

Parameter name: Phase transition pressure widths#

Default value:

Pattern: [Anything]

Documentation: A list of widths for each phase transition, in terms of pressure. The phase functions are scaled with these values, leading to a jump between phases for a value of zero and a gradual transition for larger values. List must have the same number of entries as Phase transition pressures. Define transition by depth instead of pressure must be set to false to use this parameter. Units: \si{\pascal}.

Parameter name: Phase transition pressures#

Default value:

Pattern: [Anything]

Documentation: A list of pressures where phase transitions occur. Values must monotonically increase. Define transition by depth instead of pressure must be set to false to use this parameter. Units: \si{\pascal}.

Parameter name: Phase transition temperature lower limits#

Default value: -1.7976931348623157e+308

Pattern: [Anything]

Documentation: A list of lower temperature limits for each phase transition. Below this temperature the respective phase transition is deactivated. The default value means there is no lower limit for any phase transition. List must have the same number of entries as Phase transition depths. When the optional temperature limits are applied, the user has to be careful about the consistency between adjacent phases. Phase transitions should be continuous in pressure-temperature space. We recommend producing a phase diagram with simple model setups to check the implementation as a starting point.Units: \si{\kelvin}.

Parameter name: Phase transition temperature upper limits#

Default value: 1.7976931348623157e+308

Pattern: [Anything]

Documentation: A list of upper temperature limits for each phase transition. Above this temperature the respective phase transition is deactivated. The default value means there is no upper limit for any phase transitions. List must have the same number of entries as Phase transition depths. When the optional temperature limits are applied, the user has to be careful about the consistency between adjacent phases. Phase transitions should be continuous in pressure-temperature space. We recommend producing a phase diagram with simple model setups to check the implementation as a starting point.Units: \si{\kelvin}.

Parameter name: Phase transition temperatures#

Default value:

Pattern: [Anything]

Documentation: A list of temperatures where phase transitions occur. Higher or lower temperatures lead to phase transition occurring in smaller or greater depths than given in Phase transition depths, depending on the Clapeyron slope given in Phase transition Clapeyron slopes. List must have the same number of entries as Phase transition depths. Units: \si{\kelvin}.

Parameter name: Phase transition widths#

Default value:

Pattern: [Anything]

Documentation: A list of widths for each phase transition, in terms of depth. The phase functions are scaled with these values, leading to a jump between phases for a value of zero and a gradual transition for larger values. List must have the same number of entries as Phase transition depths. Units: \si{\meter}.

Parameter name: Plastic damper viscosity#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Viscosity of the damper that acts in parallel with the plastic viscosity to produce mesh-independent behavior at sufficient resolutions. Units: \si{\pascal\second}

Parameter name: Prefactor strain weakening factors#

Default value: 1.

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

Documentation: List of viscous strain weakening factors for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Prefactors for Frank Kamenetskii#

Default value: 1.e21

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

Documentation: A viscosity prefactor for the viscosity approximation, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None

Parameter name: Prefactors for Peierls creep#

Default value: 1.4e-19

Pattern: [Anything]

Documentation: List of viscosity prefactors, \(A\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\pascal}\(^{-n_{\text{peierls}}}\) \si{\per\second}

Parameter name: Prefactors for diffusion creep#

Default value: 1.5e-15

Pattern: [Anything]

Documentation: List of viscosity prefactors, \(A\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\per\pascal\meter}\(^{m_{\text{diffusion}}}\)\si{\per\second}.

Parameter name: Prefactors for dislocation creep#

Default value: 1.1e-16

Pattern: [Anything]

Documentation: List of viscosity prefactors, \(A\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\pascal}\(^{-n_{\text{dislocation}}}\) \si{\per\second}.

Parameter name: Reference strain rate#

Default value: 1.0e-15

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Reference strain rate for first time step. Units: \si{\per\second}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Specific heats#

Alias: Heat capacities

Deprecation Status: false

Parameter name: Stabilization time scale factor#

Default value: 1.

Pattern: [Double 1…MAX_DOUBLE (inclusive)]

Documentation: A stabilization factor for the elastic stresses that influences how fast elastic stresses adjust to deformation. 1.0 is equivalent to no stabilization and may lead to oscillatory motion. Setting the factor to 2 avoids oscillations, but still enables an immediate elastic response. However, in complex models this can lead to problems of convergence, in which case the factor needs to be increased slightly. Setting the factor to infinity is equivalent to not applying elastic stresses at all. The factor is multiplied with the computational time step to create a time scale.

Parameter name: Start plasticity strain weakening intervals#

Default value: 0.

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

Documentation: List of strain weakening interval initial strains for the cohesion and friction angle parameters of the background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Start prefactor strain weakening intervals#

Default value: 0.

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

Documentation: List of strain weakening interval initial strains for the diffusion and dislocation prefactor parameters of the background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Strain healing mechanism#

Default value: no healing

Pattern: [Selection no healing|temperature dependent ]

Documentation: Whether to apply strain healing to plastic yielding and viscosity terms, and if yes, which method to use. The following methods are available:

\item “no healing”: No strain healing is applied.

\item “temperature dependent”: Purely temperature dependent strain healing applied to plastic yielding and viscosity terms, similar to the temperature-dependent Frank Kamenetskii formulation, computes strain healing as removing strain as a function of temperature, time, and a user-defined healing rate and prefactor as done in Fuchs and Becker, 2019, for mantle convection

Parameter name: Strain healing temperature dependent prefactor#

Default value: 15.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Prefactor for temperature dependent strain healing. Units: None

Parameter name: Strain healing temperature dependent recovery rate#

Default value: 1.e-15

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Recovery rate prefactor for temperature dependent strain healing. Units: \(1/s\)

Parameter name: Strain weakening mechanism#

Default value: default

Pattern: [Selection none|finite strain tensor|total strain|plastic weakening with plastic strain only|plastic weakening with total strain only|plastic weakening with plastic strain and viscous weakening with viscous strain|viscous weakening with viscous strain only|default ]

Documentation: Whether to apply strain weakening to viscosity, cohesion and internal angleof friction based on accumulated finite strain, and if yes, which method to use. The following methods are available:

\item “none”: No strain weakening is applied.

\item “finite strain tensor”: The full finite strain tensor is tracked, and its second invariant is used to weaken both the plastic yield stress (specifically, the cohesion and friction angle) and the pre-yield viscosity that arises from diffusion and/or dislocation creep.

\item “total strain”: The finite strain is approximated as the product of the second invariant of the strain rate in each time step and the time step size, and this quantity is integrated and tracked over time. It is used to weaken both the plastic yield stress (specifically, the cohesion and friction angle) and the pre-yield viscosity.

\item “plastic weakening with plastic strain only”: The finite strain is approximated as the product of the second invariant of the strain ratein each time step and the time step size in regions where material is plastically yielding. This quantity is integrated and tracked over time, and used to weaken the cohesion and friction angle. The pre-yield viscosity is not weakened.

\item “plastic weakening with total strain only”: The finite strain is approximated as the product of the second invariant of the strain rate in each time step and the time step size, and this quantity is integrated and tracked over time. It is used to weaken the plastic yield stress (specifically, the cohesion and internal friction angle). The pre-yield viscosity is not weakened.

\item “plastic weakening with plastic strain and viscous weakening with viscous strain”: Both the finite strain accumulated by plastic deformation and by viscous deformation are computed separately (each approximated as the product of the second invariant of the corresponding strain rate in each time step and the time step size). The plastic strain is used to weaken the plastic yield stress (specifically, the cohesion and yield angle), and the viscous strain is used to weaken the pre-yield viscosity.

\item “viscous weakening with viscous strain only”: The finite strain is approximated as the product of the second invariant of the strain rate in each time step and the time step size in regions where material is not plastically yielding. This quantity is integrated and tracked over time, and used to weaken the pre-yield viscosity. The cohesion and friction angle are not weakened.

\item “default”: The default option has the same behavior as “none”, but is there to make sure that the original parameters for specifying the strain weakening mechanism (“Use plastic/viscous strain weakening”) are still allowed, but to guarantee that one uses either the old parameter names or the new ones, never both.

If a compositional field named ’noninitial_plastic_strain’ is included in the parameter file, this field will automatically be excluded from from volume fraction calculation and track the cumulative plastic strain with the initial plastic strain values removed.

Parameter name: Stress exponents for Peierls creep#

Default value: 2.0

Pattern: [Anything]

Documentation: List of stress exponents, \(n_{\text{peierls}}\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Stress exponents for diffusion creep#

Default value: 1.

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

Documentation: List of stress exponents, \(n_{\text{diffusion}}\), for background mantle and compositional fields, for a total of N+1 values, where N is the number of compositional fields. The stress exponent for diffusion creep is almost always equal to one. If only one value is given, then all use the same value. Units: None.

Parameter name: Stress exponents for dislocation creep#

Default value: 3.5

Pattern: [Anything]

Documentation: List of stress exponents, \(n_{\text{dislocation}}\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None.

Parameter name: Stress limiter exponents#

Default value: 1.0

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

Documentation: List of stress limiter exponents, \(n_{\text{lim}}\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. Units: none.

Parameter name: Thermal conductivities#

Default value: 3.0

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

Documentation: List of thermal conductivities, for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal diffusivities#

Default value: 0.8e-6

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

Documentation: List of thermal diffusivities, for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\meter\squared\per\second}.

Parameter name: Thermal expansivities#

Default value: 0.000035

Pattern: [Anything]

Documentation: List of thermal expansivities for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\per\kelvin}.

Parameter name: Use adiabatic pressure in creep viscosity#

Default value: false

Pattern: [Bool]

Documentation: Whether to use the adiabatic pressure instead of the full pressure (default) when calculating creep (diffusion, dislocation, and peierls) viscosity. This may be helpful in models where the full pressure has an unusually large negative value arising from large negative dynamic pressure, resulting in solver convergence issue and in some cases a viscosity of zero.

Parameter name: Use fixed elastic time step#

Default value: unspecified

Pattern: [Selection true|false|unspecified ]

Documentation: Select whether the material time scale in the viscoelastic constitutive relationship uses the regular numerical time step or a separate fixed elastic time step throughout the model run. The fixed elastic time step is always used during the initial time step. If a fixed elastic time step is used throughout the model run, a stress averaging scheme is applied to account for differences with the numerical time step. An alternative approach is to limit the maximum time step size so that it is equal to the elastic time step. The default value of this parameter is ’unspecified’, which throws an exception during runtime. In order for the model to run the user must select ’true’ or ’false’.

Parameter name: Use plastic damper#

Default value: false

Pattern: [Bool]

Documentation: Whether to use a plastic damper when computing the Drucker-Prager plastic viscosity. The damper acts to stabilize the plastic shear band width and remove associated mesh-dependent behavior at sufficient resolutions.

Parameter name: Viscosity averaging scheme#

Default value: harmonic

Pattern: [Selection arithmetic|harmonic|geometric|maximum composition ]

Documentation: When more than one compositional field is present at a point with different viscosities, we need to come up with an average viscosity at that point. Select a weighted harmonic, arithmetic, geometric, or maximum composition.

Parameter name: Viscosity ratios for Frank Kamenetskii#

Default value: 15.

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

Documentation: An adjusted viscosity ratio, \(E\), for the viscosity approximation, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: None

Parameter name: Viscous flow law#

Default value: composite

Pattern: [Selection diffusion|dislocation|frank kamenetskii|composite ]

Documentation: Select what type of viscosity law to use between diffusion, dislocation, frank kamenetskii, and composite options. Soon there will be an option to select a specific flow law for each assigned composition

Parameter name: Yield mechanism#

Default value: drucker

Pattern: [Selection drucker|limiter ]

Documentation: Select what type of yield mechanism to use between Drucker Prager and stress limiter options.

Subsection: Material model / Visco Plastic / Friction 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: Material model / Viscoelastic#

Parameter name: Densities#

Default value: 3300.

Pattern: [Anything]

Documentation: List of densities for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\kilogram\per\meter\cubed}.

Parameter name: Elastic damper viscosity#

Default value: 0.0

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: Viscosity of a viscous damper that acts in parallel with the elastic element to stabilize behavior. Units: \si{\pascal\second}

Parameter name: Elastic shear moduli#

Default value: 75.0e9

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

Documentation: List of elastic shear moduli, \(G\), for background material and compositional fields, for a total of N+1 values, where N is the number of compositional fields. The default value of 75 GPa is representative of mantle rocks. Units: Pa.

Parameter name: Fixed elastic time step#

Default value: 1.e3

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The fixed elastic time step \(dte\). Units: years if the ’Use years in output instead of seconds’ parameter is set; seconds otherwise.

Parameter name: Heat capacities#

Default value: 1250.

Pattern: [Anything]

Documentation: List of specific heats \(C_p\) for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\joule\per\kelvin\per\kilogram}.

Parameter name: Reference temperature#

Default value: 293.

Pattern: [Double 0…MAX_DOUBLE (inclusive)]

Documentation: The reference temperature \(T_0\). Units: \si{\kelvin}.

Parameter name: Specific heats#

Alias: Heat capacities

Deprecation Status: false

Parameter name: Stabilization time scale factor#

Default value: 1.

Pattern: [Double 1…MAX_DOUBLE (inclusive)]

Documentation: A stabilization factor for the elastic stresses that influences how fast elastic stresses adjust to deformation. 1.0 is equivalent to no stabilization and may lead to oscillatory motion. Setting the factor to 2 avoids oscillations, but still enables an immediate elastic response. However, in complex models this can lead to problems of convergence, in which case the factor needs to be increased slightly. Setting the factor to infinity is equivalent to not applying elastic stresses at all. The factor is multiplied with the computational time step to create a time scale.

Parameter name: Thermal conductivities#

Default value: 4.7

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

Documentation: List of thermal conductivities for background mantle and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\watt\per\meter\per\kelvin}.

Parameter name: Thermal expansivities#

Default value: 0.000035

Pattern: [Anything]

Documentation: List of thermal expansivities for background mantle and compositional fields,for a total of N+M+1 values, where N is the number of compositional fields and M is the number of phases. If only one value is given, then all use the same value. Units: \si{\per\kelvin}.

Parameter name: Use fixed elastic time step#

Default value: unspecified

Pattern: [Selection true|false|unspecified ]

Documentation: Select whether the material time scale in the viscoelastic constitutive relationship uses the regular numerical time step or a separate fixed elastic time step throughout the model run. The fixed elastic time step is always used during the initial time step. If a fixed elastic time step is used throughout the model run, a stress averaging scheme is applied to account for differences with the numerical time step. An alternative approach is to limit the maximum time step size so that it is equal to the elastic time step. The default value of this parameter is ’unspecified’, which throws an exception during runtime. In order for the model to run the user must select ’true’ or ’false’.

Parameter name: Viscosities#

Default value: 1.e21

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

Documentation: List of viscosities for background mantle and compositional fields, for a total of N+1 values, where N is the number of compositional fields. If only one value is given, then all use the same value. Units: \si{\pascal\second}.

Parameter name: Viscosity averaging scheme#

Default value: harmonic

Pattern: [Selection arithmetic|harmonic|geometric|maximum composition ]

Documentation: When more than one compositional field is present at a point with different viscosities, we need to come up with an average viscosity at that point. Select a weighted harmonic, arithmetic, geometric, or maximum composition.