Input parameter files

4.7 Input parameter files

What ASPECT computes is driven by two things:

The models implemented in ASPECT. This includes the geometries, the material laws, or the initial conditions currently supported. Which of these models are currently implemented is discussed below; Section 6 discusses in great detail the process of implementing additional models.
Which of the implemented models is selected, and what their run-time parameters are. For example, you could select a model that prescribes constant coefficients throughout the domain from all the material models currently implemented; you could then select appropriate values for all of these constants. Both of these selections happen from a parameter file that is read at run time and whose name is specified on the command line. (See also Section 4.1.)

In this section, let us give an overview of what can be selected in the parameter file. Specific parameters, their default values, and allowed values for these parameters are documented in Section A. An index with page numbers for all run-time parameters can be found on page ??.

4.7.1 The structure of parameter files

Most of the run-time behavior of ASPECT is driven by a parameter file that looks in essence like this:

set ??                     = 2
set ??            = false
set ??                      = 1e10
set ??                    = 1.0
set ??              = output

subsection ??
  set ?? = 1
  set ??   = 4
end

subsection ??
  set ??                  = simple

  subsection ??
    set ??         = 3300
    set ??     = 293
    set ??                 = 5e24
  end
end

...

Some parameters live at the top level, but most parameters are grouped into subsections. An input parameter file is therefore much like a file system: a few files live in the root directory; others are in a nested hierarchy of sub-directories. And just as with files, parameters have both a name (the thing to the left of the equals sign) and a content (what’s to the right).

All parameters you can list in this input file have been declared in ASPECT. What this means is that you can’t just list anything in the input file, and expect that entries that are unknown are simply ignored. Rather, if your input file contains a line setting a parameter that is unknown, you will get an error message. Likewise, all declared parameters have a description of possible values associated with them – for example, some parameters must be non-negative integers (the number of initial refinement steps), can either be true or false (whether the computation should be resumed from a saved state), or can only be a single element from a selection (the name of the material model). If an entry in your input file doesn’t satisfy these constraints, it will be rejected at the time of reading the file (and not when a part of the program actually accesses the value and the programmer has taken the time to also implement some error checking at this location). Finally, because parameters have been declared, you do not need to specify a parameter in the input file: if a parameter isn’t listed, then the program will simply use the default provided when declaring the parameter.

Note: In cases where a parameter requires a significant amount of text, you can end a line in the input file with a backslash. This indicates that the following line will simply continue to be part of the text of the current line, in the same way as the C/C++ preprocessor expands lines that end in backslashes. The underlying implementation always eats whitespace at the beginning of each continuing line, but not before the backslash. This means that the parameter file
set Some parameter = abc

∖

def
is equivalent to
set Some parameter = abcdef
that is, with no space between abc and def despite the leading whitespace at the beginning of the second line. If you do want space between these two parts, you need to add it before the backslash in the first of the two lines.

4.7.2 Categories of parameters

The parameters that can be provided in the input file can roughly be categorized into the following groups:

Global parameters (see Section ??): These parameters determine the overall behavior of the program. Primarily they describe things like the output directory, the end time of the simulation, or whether the computation should be resumed from a previously saved state.
Parameters for certain aspects of the numerical algorithm: These describe, for example, the specifics of the spatial discretization. In particular, this is the case for parameters concerning the polynomial degree of the finite element approximation (Section ??), some details about the stabilization (Section ??), and how adaptive mesh refinement is supposed to work (Section ??).
Parameters that describe certain global aspects of the equations to be solved: This includes, for example, a description if certain terms in the model should be omitted or not. See Section ?? for the list of parameters in this category.
Parameters that characterize plugins: Certain behaviors of ASPECT are described by what we call plugins – self-contained parts of the code that describe one particular aspect of the simulation. An example would be which of the implemented material models to use, and the specifics of this material model. The sample parameter file above gives an indication of how this works: within a subsection of the file that pertains to the material models, one can select one out of several plugins (or, in the case of the postprocessors, any number, including none, of the available plugins), and one can then specify the specifics of this model in a sub-subsection dedicated to this particular model.
A number of components of ASPECT are implemented via plugins. Some of these, together with the sections in which their parameters are declared, are the following:
- The material model: Sections ?? and following.
- The geometry: Sections ?? and following.
- The gravity description: Sections ?? and following.
- Initial conditions for the temperature: Sections ?? and following.
- Temperature boundary conditions: Sections ?? and following.
- Postprocessors: Sections ?? and following for most postprocessors, section ?? and following for postprocessors related to visualization.

The details of parameters in each of these categories can be found in the sections linked to above. Some of them will also be used in the cookbooks in Section 5.

4.7.3 A note on the syntax of formulas in input files

Input files have different ways of describing certain things to ASPECT. For example, you could select a plugin for the temperature initial values that prescribes a constant temperature, or a plugin that implements a particular formula for these initial conditions in C++ in the code of the plugin, or a plugin that allows you to describe this formula in a symbolic way in the input file (see Section ??). An example of this latter case is this snippet of code discussed in Section 5.2.2:

subsection ??
  set ?? = function

  subsection ??
    set ??      = x,y,z
    set ??  = p=0.01, L=1, pi=3.1415926536, k=1
    set ?? = (1.0-z) - p*cos(k*pi*x/L)*sin(pi*z)*y^3
  end
end

The formulas you can enter here need to use a syntax that is understood by the functions and classes that interpret what you write. Internally, this is done using the muparser library, see http://muparser.beltoforion.de/. The syntax is mostly self-explanatory in that it allows to use the usual symbols x, y and z to reference coordinates (unless a particular plugin uses different variables, such as the depth), the symbol t for time in many situations, and allows you to use all of the typical mathematical functions such as sine and cosine. Another common case is an if-statement that has the general form if(condition, true-expression, false-expression). For more examples of the syntax understood, reference the documentation of the muparser library linked to above.

4.7.4 Compatibility of input files with newer ASPECT versions

We strive to maintain compatibility for options in input files as long as possible. However, occasionally we have to reorder, rename, or remove options from parameter files to improve ASPECT further. This is in particular true for new major versions. In order to allow running old parameter files with newer ASPECT versions we provide scripts that can automatically update existing parameter files to the new syntax. Executing doc/update_prm_files.sh with one or more parameter files as arguments will create a backup of the old parameter file (named old_filename.bak), and replace the existing file with a version that should work with the current ASPECT version. Using this script would look like this:

bash doc/update_prm_files.sh cookbooks/convection_box.prm

Note: Not all text replacements are unique, and the structure of input files allows for constructions the script can not properly parse. Also we can not guarantee to preserve the structure and position of comments, as it is not always clear to which part of the input file they refer. Thus, it is important that you check your updated input file for errors. That being said, all input files in the main ASPECT repository are updated successfully using this script.

[next] [prev] [prev-tail] [front] [up]