Global parameters
Contents
Global parameters#
Subsection: No subsection#
Parameter name: Adiabatic surface temperature#
Default value: 0.
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: In order to make the problem in the first time step easier to solve, we need a reasonable guess for the temperature and pressure. To obtain it, we use an adiabatic pressure and temperature field. This parameter describes what the ‘adiabatic’ temperature would be at the surface of the domain (i.e. at depth zero). Note that this value need not coincide with the boundary condition posed at this point. Rather, the boundary condition may differ significantly from the adiabatic value, and then typically induce a thermal boundary layer.
For more information, see the section in the manual that discusses the general mathematical model.
Parameter name: CFL number#
Default value: 1.0
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: In computations, the time step \(k\) is chosen according to \(k = c \min_K \frac {h_K} {\|u\|_{\infty,K} p_T}\) where \(h_K\) is the diameter of cell \(K\), and the denominator is the maximal magnitude of the velocity on cell \(K\) times the polynomial degree \(p_T\) of the temperature discretization. The dimensionless constant \(c\) is called the CFL number in this program. For time discretizations that have explicit components, \(c\) must be less than a constant that depends on the details of the time discretization and that is no larger than one. On the other hand, for implicit discretizations such as the one chosen here, one can choose the time step as large as one wants (in particular, one can choose \(c>1\)) though a CFL number significantly larger than one will yield rather diffusive solutions. Units: None.
Parameter name: Dimension#
Default value: 2
Pattern: [Integer range 2…3 (inclusive)]
Documentation: The number of space dimensions you want to run this program in. ASPECT can run in 2 and 3 space dimensions.
Parameter name: End time#
Default value: 5.69e+300
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: The end time of the simulation. The default value is a number so that when converted from years to seconds it is approximately equal to the largest number representable in floating point arithmetic. For all practical purposes, this equals infinity. Units: Years if the ’Use years in output instead of seconds’ parameter is set; seconds otherwise.
Parameter name: Max nonlinear iterations#
Default value: 10
Pattern: [Integer range 1…2147483647 (inclusive)]
Documentation: The maximal number of nonlinear iterations to be performed.
Parameter name: Max nonlinear iterations in pre-refinement#
Default value: 2147483647
Pattern: [Integer range 0…2147483647 (inclusive)]
Documentation: The maximal number of nonlinear iterations to be performed in the pre-refinement steps. This does not include the last refinement step before moving to timestep 1. When this parameter has a larger value than max nonlinear iterations, the latter is used.
Parameter name: Maximum first time step#
Default value: 5.69e+300
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Set a maximum time step size for only the first timestep. Generally the time step based on the CFL number should be sufficient, but for complicated models or benchmarking it may be useful to limit the first time step to some value, especially when using the free surface, which needs to settle to prevent instabilities. This should in that case be combined with a value set for “Maximum relative increase in time step”. The default value is a value so that when converted from years into seconds it equals the largest number representable by a floating point number, implying an unlimited time step. Units: Years or seconds, depending on the “Use years in output instead of seconds” parameter.
Parameter name: Maximum relative increase in time step#
Default value: 2147483647
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Set a percentage with which the time step is limited to increase. Generally the time step based on the CFL number should be sufficient, but for complicated models which may suddenly drastically change behavior, it may be useful to limit the increase in the time step, without limiting the time step size of the whole simulation to a particular number. For example, if this parameter is set to \(50\), then that means that the time step can at most increase by 50% from one time step to the next, or by a factor of 1.5. Units: %.
Parameter name: Maximum time step#
Default value: 5.69e+300
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Set a maximum time step size for the solver to use. Generally the time step based on the CFL number should be sufficient, but for complicated models or benchmarking it may be useful to limit the time step to some value. The default value is a value so that when converted from years into seconds it equals the largest number representable by a floating point number, implying an unlimited time step.Units: Years or seconds, depending on the “Use years in output instead of seconds” parameter.
Parameter name: Nonlinear solver scheme#
Default value: single Advection, single Stokes
Pattern: [Selection single Advection, single Stokes|iterated Advection and Stokes|single Advection, iterated Stokes|no Advection, iterated Stokes|no Advection, single Stokes|no Advection, iterated defect correction Stokes|single Advection, iterated defect correction Stokes|iterated Advection and defect correction Stokes|iterated Advection and Newton Stokes|single Advection, iterated Newton Stokes|single Advection, no Stokes|IMPES|iterated IMPES|iterated Stokes|Newton Stokes|Stokes only|Advection only|first timestep only, single Stokes|no Advection, no Stokes ]
Documentation: The kind of scheme used to resolve the nonlinearity in the system. ‘single Advection, single Stokes’ means that no nonlinear iterations are done, and the temperature, compositional fields and Stokes equations are solved exactly once per time step, one after the other. The ‘iterated Advection and Stokes’ scheme iterates this decoupled approach by alternating the solution of the temperature, composition and Stokes systems. The ‘single Advection, iterated Stokes’ scheme solves the temperature and composition equation once at the beginning of each time step and then iterates out the solution of the Stokes equation. The ‘no Advection, iterated Stokes’ scheme only solves the Stokes system, iterating out the solution, and ignores compositions and the temperature equation (careful, the material model must not depend on the temperature or composition; this is mostly useful for Stokes benchmarks). The ‘no Advection, single Stokes’ scheme only solves the Stokes system once per timestep. This is also mostly useful for Stokes benchmarks. The ‘single Advection, no Stokes’ scheme only solves the temperature and other advection systems once, and instead of solving for the Stokes system, a prescribed velocity and pressure is used. The ‘iterated Advection and Newton Stokes’ scheme iterates by alternating the solution of the temperature, composition and Stokes equations, using Picard iterations for the temperature and composition, and Newton iterations for the Stokes system. The ‘single Advection, iterated Newton Stokes’ scheme solves the temperature and composition equations once at the beginning of each time step and then iterates out the solution of the Stokes equation, using Newton iterations for the Stokes system. The ‘iterated Advection and defect correction Stokes’ scheme iterates by alternating the solution of the temperature, composition and Stokes equations, using Picard iterations for the temperature and composition, and defect correction Picard iterations for the Stokes system. The ‘single Advection, iterated defect correction Stokes’ scheme solves the temperature and composition equations once at the beginning of each time step and then iterates out the solution of the Stokes equation, using defect correction Picard iterations for the Stokes system. The ‘no Advection, iterated defect correction Stokes’ scheme solves the temperature and composition equations once at the beginning of each time step and then iterates out the solution of the Stokes equation, using defect correction Picard iterations for the Stokes system. The ‘first timestep only, single Stokes’ scheme solves the Stokes equations exactly once, at the first time step. No nonlinear iterations are done, and the temperature and composition systems are not solved.
The ‘IMPES’ scheme is deprecated and only allowed for reasons of backwards compatibility. It is the same as ‘single Advection, single Stokes’ .The ‘iterated IMPES’ scheme is deprecated and only allowed for reasons of backwards compatibility. It is the same as ‘iterated Advection and Stokes’. The ‘iterated Stokes’ scheme is deprecated and only allowed for reasons of backwards compatibility. It is the same as ‘single Advection, iterated Stokes’. The ‘Stokes only’ scheme is deprecated and only allowed for reasons of backwards compatibility. It is the same as ‘no Advection, iterated Stokes’. The ‘Advection only’ scheme is deprecated and only allowed for reasons of backwards compatibility. It is the same as ‘single Advection, no Stokes’. The ‘Newton Stokes’ scheme is deprecated and only allowed for reasons of backwards compatibility. It is the same as ‘iterated Advection and Newton Stokes’.
Parameter name: Nonlinear solver tolerance#
Default value: 1e-5
Pattern: [Double 0…1 (inclusive)]
Documentation: A relative tolerance up to which the nonlinear solver will iterate. This parameter is only relevant if the ‘Nonlinear solver scheme’ does nonlinear iterations, in other words, if it is set to something other than ‘single Advection, single Stokes’ or ‘single Advection, no Stokes’.
Parameter name: Output directory#
Default value: output
Pattern: [DirectoryName]
Documentation: The name of the directory into which all output files should be placed. This may be an absolute or a relative path.
Parameter name: Pressure normalization#
Default value: surface
Pattern: [Selection surface|volume|no ]
Documentation: If and how to normalize the pressure after the solution step. This is necessary because depending on boundary conditions, in many cases the pressure is only determined by the model up to a constant. On the other hand, we often would like to have a well-determined pressure, for example for table lookups of material properties in models or for comparing solutions. If the given value is ‘surface’, then normalization at the end of each time steps adds a constant value to the pressure in such a way that the average pressure at the surface of the domain is what is set in the ‘Surface pressure’ parameter; the surface of the domain is determined by asking the geometry model whether a particular face of the geometry has a zero or small ‘depth’. If the value of this parameter is ‘volume’ then the pressure is normalized so that the domain average is zero. If ‘no’ is given, the no pressure normalization is performed.
Parameter name: Resume computation#
Default value: false
Pattern: [Selection true|false|auto ]
Documentation: A flag indicating whether the computation should be resumed from a previously saved state (if true) or start from scratch (if false). If auto is selected, models will be resumed if there is an existing checkpoint file, otherwise started from scratch.
Parameter name: Start time#
Default value: 0.
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: The start time of the simulation. Units: Years if the ’Use years in output instead of seconds’ parameter is set; seconds otherwise.
Parameter name: Surface pressure#
Default value: 0.
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: The value the pressure is normalized to in each time step when ‘Pressure normalization’ is set to ‘surface’ with default value 0. This setting is ignored in all other cases.
The mathematical equations that describe thermal convection only determine the pressure up to an arbitrary constant. On the other hand, for comparison and for looking up material parameters it is important that the pressure be normalized somehow. We do this by enforcing a particular average pressure value at the surface of the domain, where the geometry model determines where the surface is. This parameter describes what this average surface pressure value is supposed to be. By default, it is set to zero, but one may want to choose a different value for example for simulating only the volume of the mantle below the lithosphere, in which case the surface pressure should be the lithostatic pressure at the bottom of the lithosphere.
For more information, see the section in the manual that discusses the general mathematical model.
Parameter name: Timing output frequency#
Default value: 100
Pattern: [Integer range 0…2147483647 (inclusive)]
Documentation: How frequently in timesteps to output timing information. This is generally adjusted only for debugging and timing purposes. If the value is set to zero it will also output timing information at the initiation timesteps.
Parameter name: Use conduction timestep#
Default value: false
Pattern: [Bool]
Documentation: Mantle convection simulations are often focused on convection dominated systems. However, these codes can also be used to investigate systems where heat conduction plays a dominant role. This parameter indicates whether the simulator should also use heat conduction in determining the length of each time step.
Parameter name: Use operator splitting#
Default value: false
Pattern: [Bool]
Documentation: If set to true, the advection and reactions of compositional fields and temperature are solved separately, and can use different time steps. Note that this will only work if the material/heating model fills the reaction_rates/heating_reaction_rates structures. Operator splitting can be used with any existing solver schemes that solve the temperature/composition equations.
Parameter name: Use years in output instead of seconds#
Default value: true
Pattern: [Bool]
Documentation: When computing results for mantle convection simulations, it is often difficult to judge the order of magnitude of results when they are stated in MKS units involving seconds. Rather, some kinds of results such as velocities are often stated in terms of meters per year (or, sometimes, centimeters per year). On the other hand, for non-dimensional computations, one wants results in their natural unit system as used inside the code. If this flag is set to ‘true’ conversion to years happens; if it is ‘false’, no such conversion happens.
Contrary to the word “output” in the name of this parameter, a number of plugins also use this parameter to determine how to interpret their inputs. For example, when ‘true’, several of the boundary velocity models described in Section~\ref{parameters:Boundary_20velocity_20model} interpret both specific times in years instead of seconds, and velocities in meters per year instead of meters per second.
Parameter name: World builder file#
Default value:
Pattern: [FileName (Type: input)]
Documentation: Name of the world builder file. If empty, the world builder is not initialized.