# Geometry model#

**Subsection:** Geometry model#

**Parameter name:** Model name#

**Default value:** unspecified

**Pattern:** [Selection box|box with lithosphere boundary indicators|chunk|chunk with lithosphere boundary indicators|ellipsoidal chunk|sphere|spherical shell|unspecified ]

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

‘box’: A box geometry parallel to the coordinate directions. The extent of the box in each coordinate direction is set in the parameter file. The box geometry labels its 2*dim sides as follows: in 2d, boundary indicators 0 through 3 denote the left, right, bottom and top boundaries; in 3d, boundary indicators 0 through 5 indicate left, right, front, back, bottom and top boundaries (see also the documentation of the deal.II class “ReferenceCell”). You can also use symbolic names “left”, “right”, etc., to refer to these boundaries in input files. It is also possible to add initial topography to the box model. Note however that this is done after the last initial adaptive refinement cycle. Also, initial topography is supposed to be small, as it is not taken into account when depth or a representative point is computed.

‘box with lithosphere boundary indicators’: A box geometry parallel to the coordinate directions. The extent of the box in each coordinate direction is set in the parameter file. This geometry model labels its sides with 2*dim+2*(dim-1) boundary indicators: in 2d, boundary indicators 0 through 3 denote the left, right, bottom and top boundaries, while indicators4 and 5 denote the upper part of the left and right vertical boundary, respectively. In 3d, boundary indicators 0 through 5 indicate left, right, front, back, bottom and top boundaries (see also the documentation of the deal.II class “ReferenceCell”), while indicators 6, 7, 8 and 9 denote the left, right, front and back upper parts of the vertical boundaries, respectively. You can also use symbolic names “left”, “right”, “left lithosphere”, etc., to refer to these boundaries in input files.

Note that for a given “Global refinement level” and no user-specified “Repetitions”, the lithosphere part of the mesh will be more refined.

The additional boundary indicators for the lithosphere allow for selecting boundary conditions for the lithosphere different from those for the underlying mantle. An example application of this geometry is to prescribe a velocity on the lithospheric plates, but use open boundary conditions underneath.

‘chunk’: A geometry which can be described as a chunk of a spherical shell, bounded by lines of longitude, latitude and radius. The minimum and maximum longitude, latitude (if in 3d) and depth of the chunk is set in the parameter file. The chunk geometry labels its 2*dim sides as follows: “west” and “east”: minimum and maximum longitude, “south” and “north”: minimum and maximum latitude, “inner” and “outer”: minimum and maximum radii.

The dimensions of the model are specified by parameters of the following form: Chunk (minimum || maximum) (longitude || latitude): edges of geographical quadrangle (in degrees)Chunk (inner || outer) radius: Radii at bottom and top of chunk(Longitude || Latitude || Radius) repetitions: number of cells in each coordinate direction.

When used in 2d, this geometry does not imply the use of a spherical coordinate system. Indeed, in 2d the geometry is simply a sector of an annulus in a Cartesian coordinate system and consequently would correspond to a sector of a cross section of the fluid filled space between two infinite cylinders where one has made the assumption that the velocity in direction of the cylinder axes is zero. This is consistent with the definition of what we consider the two-dimension case given in Two-dimensional models. It is also possible to add initial topography to the chunk geometry, based on an ascii data file.

‘chunk with lithosphere boundary indicators’: A geometry which can be described as a chunk of a spherical shell, bounded by lines of longitude, latitude and radius. The side boundaries have two boundary indicators, so the user can prescribe different boundary conditions on these boundaries. The minimum and maximum longitude, (latitude) and depth of the chunk are set in the parameter file. The chunk geometry labels its 2*dim+2*(dim-1) sides as follows: “lowerwest” and “lowereast”: minimum and maximum longitude of the lower part of the east and west side boundaries, “upperwest” and “uppereast”: minimum and maximum longitude of the upper part of the east and west side boundaries, “lowersouth” and “lowernorth”: minimum and maximum latitude of the lower part of the south and north side boundaries, “uppersouth” and “uppernorth”: minimum and maximum latitude of the upper part of the south and north side boundaries,

The dimensions of the model are specified by parameters of the following form: Chunk (minimum | maximum) (longitude | latitude): edges of geographical quadrangle (in degrees). Chunk (inner | outer | middle boundary) radius: Radii at bottom and top of chunk and the radius at which the lower boundary indicator along a side boundary transitions into the upper boundary indicator. (Longitude | Latitude) repetitions: number of cells in each coordinate direction.(Inner | Outer) chunk radius repetitions: number of cells in the radial coordinate direction for the lower part of the domain (up to the Middle boundary radius) and for the upper part of the domain.

When used in 2d, this geometry does not imply the use of a spherical coordinate system. Indeed, in 2d the geometry is simply a sector of an annulus in a Cartesian coordinate system and consequently would correspond to a sector of a cross section of the fluid filled space between two infinite cylinders where one has made the assumption that the velocity in direction of the cylinder axes is zero. This is consistent with the definition of what we consider the two-dimension case given in Two-dimensional models. It is also possible to add initial topography to the chunk geometry, based on an ascii data file.

‘ellipsoidal chunk’: A 3d chunk geometry that accounts for Earth’s ellipticity (default assuming the WGS84 ellipsoid definition) which can be defined in non-coordinate directions. In the description of the ellipsoidal chunk, two of the ellipsoidal axes have the same length so that there is only a semi-major axis and a semi-minor axis. The user has two options for creating an ellipsoidal chunk geometry: 1) by defining two opposing points (SW and NE or NW and SE) a coordinate parallel ellipsoidal chunk geometry will be created. 2) by defining three points a non-coordinate parallel ellipsoidal chunk will be created. The points are defined in the input file by longitude:latitude. It is also possible to define additional subdivisions of the mesh in each direction. The boundary of the domain is formed by linear interpolation in longitude-latitude space between adjacent points (i.e. \(\[lon, lat\](f) = [lon1 \cdot f + lon2 \cdot(1-f), lat1 \cdot f + lat2 \cdot (1-f)]\), where f is a value between 0 and 1). Faces of the model are defined as 0, west; 1,east; 2, south; 3, north; 4, inner; 5, outer.

This geometry model supports initial topography for deforming the initial mesh.

‘sphere’: A geometry model for a sphere with a user specified radius. This geometry has only a single boundary, so the only valid boundary indicator to specify in input files is “0”. It can also be referenced by the symbolic name “surface” in input files.

Despite the name, this geometry does not imply the use of a spherical coordinate system when used in 2d. Indeed, in 2d the geometry is simply a circle in a Cartesian coordinate system and consequently would correspond to a cross section of the fluid filled interior of an infinite cylinder where one has made the assumption that the velocity in direction of the cylinder axes is zero. This is consistent with the definition of what we consider the two-dimension case given in Two-dimensional models.

‘spherical shell’: A geometry representing a spherical shell or a piece of it. Inner and outer radii are read from the parameter file in subsection ’Spherical shell’.

The spherical shell may be generated as per the original code (with respect to the inner and outer radius, and an initial number of cells along circumference) or following a custom mesh scheme: list of radial values or number of slices. A surface mesh is first generated and refined as desired, before it is extruded radially. A list of radial values subdivides the spherical shell at specified radii. The number of slices subdivides the spherical shell into N slices of equal thickness. The custom spherical shell only works with an opening angle of 360 degrees.

Despite the name, this geometry does not imply the use of a spherical coordinate system when used in 2d. Indeed, in 2d the geometry is simply an annulus in a Cartesian coordinate system and consequently would correspond to a cross section of the fluid filled space between two infinite cylinders where one has made the assumption that the velocity in direction of the cylinder axes is zero. This is consistent with the definition of what we consider the two-dimension case given in Two-dimensional models.

The model assigns boundary indicators as follows: In 2d, inner and outer boundaries get boundary indicators zero and one, and if the opening angle set in the input file is less than 360, then left and right boundaries are assigned indicators two and three. These boundaries can also be referenced using the symbolic names ‘inner’, ‘outer’ and (if applicable) ‘left’, ‘right’.

In 3d, inner and outer indicators are treated as in 2d. If the opening angle is chosen as 90 degrees, i.e., the domain is the intersection of a spherical shell and the first octant, then indicator 2 is at the face \(x=0\), 3 at \(y=0\), and 4 at \(z=0\). These last three boundaries can then also be referred to as ‘east’, ‘west’ and ‘south’ symbolically in input files.

**Subsection:** Geometry model / Box#

**Parameter name:** Box origin X coordinate#

**Default value:** 0.

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

**Documentation:** X coordinate of box origin. Units: \si{\meter}.

**Parameter name:** Box origin Y coordinate#

**Default value:** 0.

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

**Documentation:** Y coordinate of box origin. Units: \si{\meter}.

**Parameter name:** Box origin Z coordinate#

**Default value:** 0.

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

**Documentation:** Z coordinate of box origin. This value is ignored if the simulation is in 2d. Units: \si{\meter}.

**Parameter name:** X extent#

**Default value:** 1.

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

**Documentation:** Extent of the box in x-direction. Units: \si{\meter}.

**Parameter name:** X periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in X direction

**Parameter name:** X repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in X direction.

**Parameter name:** Y extent#

**Default value:** 1.

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

**Documentation:** Extent of the box in y-direction. Units: \si{\meter}.

**Parameter name:** Y periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in Y direction

**Parameter name:** Y repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in Y direction.

**Parameter name:** Z extent#

**Default value:** 1.

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

**Documentation:** Extent of the box in z-direction. This value is ignored if the simulation is in 2d. Units: \si{\meter}.

**Parameter name:** Z periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in Z direction

**Parameter name:** Z repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in Z direction.

**Subsection:** Geometry model / Box with lithosphere boundary indicators#

**Parameter name:** Box origin X coordinate#

**Default value:** 0.

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

**Documentation:** X coordinate of box origin. Units: \si{\meter}.

**Parameter name:** Box origin Y coordinate#

**Default value:** 0.

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

**Documentation:** Y coordinate of box origin. Units: \si{\meter}.

**Parameter name:** Box origin Z coordinate#

**Default value:** 0.

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

**Documentation:** Z coordinate of box origin. This value is ignored if the simulation is in 2d. Units: \si{\meter}.

**Parameter name:** Lithospheric thickness#

**Default value:** 0.2

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

**Documentation:** The thickness of the lithosphere used to create additional boundary indicators to set specific boundary conditions for the lithosphere.

**Parameter name:** Use merged grids#

**Default value:** true

**Pattern:** [Bool]

**Documentation:** Whether to make the grid by gluing together two boxes, or just use one chunk to make the grid. Using two grids glued together is a safer option, since it forces the boundary conditions to be always applied to the same depth, but using one grid allows for a more flexible usage of the adaptive refinement. Note that if there is no cell boundary exactly on the boundary between the lithosphere and the mantle, the velocity boundary will not be exactly at that depth. Therefore, using a merged grid is generally recommended over using one grid.When using one grid, the parameter for lower repetitions is used and the upper repetitions are ignored.

**Parameter name:** X extent#

**Default value:** 1.

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

**Documentation:** Extent of the box in x-direction. Units: \si{\meter}.

**Parameter name:** X periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in X direction.

**Parameter name:** X periodic lithosphere#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in X direction in the lithosphere.

**Parameter name:** X repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in X direction of the lower box. The same number of repetitions will be used in the upper box.

**Parameter name:** Y extent#

**Default value:** 1.

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

**Documentation:** Extent of the box in y-direction. Units: \si{\meter}.

**Parameter name:** Y periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in Y direction.

**Parameter name:** Y periodic lithosphere#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in Y direction in the lithosphere. This value is ignored if the simulation is in 2d.

**Parameter name:** Y repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in Y direction of the lower box. If the simulation is in 3d, the same number of repetitions will be used in the upper box.

**Parameter name:** Y repetitions lithosphere#

**Default value:** 1

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

**Documentation:** Number of cells in Y direction in the lithosphere. This value is ignored if the simulation is in 3d.

**Parameter name:** Z extent#

**Default value:** 1.

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

**Documentation:** Extent of the box in z-direction. This value is ignored if the simulation is in 2d. Units: \si{\meter}.

**Parameter name:** Z periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the box should be periodic in Z direction. This value is ignored if the simulation is in 2d.

**Parameter name:** Z repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in Z direction of the lower box. This value is ignored if the simulation is in 2d.

**Parameter name:** Z repetitions lithosphere#

**Default value:** 1

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

**Documentation:** Number of cells in Z direction in the lithosphere. This value is ignored if the simulation is in 2d.

**Subsection:** Geometry model / Chunk#

**Parameter name:** Chunk inner radius#

**Default value:** 0.

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

**Documentation:** Radius at the bottom surface of the chunk. Units: \si{\meter}.

**Parameter name:** Chunk maximum latitude#

**Default value:** 1.

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

**Documentation:** Maximum latitude of the chunk. This value is ignored if the simulation is in 2d. Units: degrees.

**Parameter name:** Chunk maximum longitude#

**Default value:** 1.

**Pattern:** [Double -180…360 (inclusive)]

**Documentation:** Maximum longitude of the chunk. Units: degrees.

**Parameter name:** Chunk minimum latitude#

**Default value:** 0.

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

**Documentation:** Minimum latitude of the chunk. This value is ignored if the simulation is in 2d. Units: degrees.

**Parameter name:** Chunk minimum longitude#

**Default value:** 0.

**Pattern:** [Double -180…360 (inclusive)]

**Documentation:** Minimum longitude of the chunk. Units: degrees.

**Parameter name:** Chunk outer radius#

**Default value:** 1.

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

**Documentation:** Radius at the top surface of the chunk. Units: \si{\meter}.

**Parameter name:** Latitude repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in latitude. This value is ignored if the simulation is in 2d

**Parameter name:** Longitude repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in longitude.

**Parameter name:** Radius repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in radius.

**Subsection:** Geometry model / Chunk with lithosphere boundary indicators#

**Parameter name:** Chunk inner radius#

**Default value:** 0.

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

**Documentation:** Radius at the bottom surface of the chunk. Units: \si{\meter}.

**Parameter name:** Chunk maximum latitude#

**Default value:** 1.

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

**Documentation:** Maximum latitude of the chunk. This value is ignored if the simulation is in 2d. Units: degrees.

**Parameter name:** Chunk maximum longitude#

**Default value:** 1.

**Pattern:** [Double -180…360 (inclusive)]

**Documentation:** Maximum longitude of the chunk. Units: degrees.

**Parameter name:** Chunk middle boundary radius#

**Default value:** 1

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

**Documentation:** Radius at the top surface of the lower chunk, where it merges with the upper chunk. Units: \si{\meter}.

**Parameter name:** Chunk minimum latitude#

**Default value:** 0.

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

**Documentation:** Minimum latitude of the chunk. This value is ignored if the simulation is in 2d. Units: degrees.

**Parameter name:** Chunk minimum longitude#

**Default value:** 0.

**Pattern:** [Double -180…360 (inclusive)]

**Documentation:** Minimum longitude of the chunk. Units: degrees.

**Parameter name:** Chunk outer radius#

**Default value:** 1.

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

**Documentation:** Radius at the top surface of the chunk. Units: \si{\meter}.

**Parameter name:** Inner chunk radius repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in radial direction for the lower chunk.

**Parameter name:** Latitude repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in latitude. This value is ignored if the simulation is in 2d

**Parameter name:** Longitude repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in longitude.

**Parameter name:** Outer chunk radius repetitions#

**Default value:** 1

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

**Documentation:** Number of cells in radial direction for the upper chunk.

**Parameter name:** Use merged grids#

**Default value:** true

**Pattern:** [Bool]

**Documentation:** Whether to make the grid by gluing together two boxes, or just use one chunk to make the grid. Using two grids glued together is a safer option, since it forces the boundary conditions to be always applied to the same depth, but using one grid allows for a more flexible usage of the adaptive refinement. Note that if there is no cell boundary exactly on the boundary between the lithosphere and the mantle, the velocity boundary will not be exactly at that depth. Therefore, using a merged grid is generally recommended over using one grid. When using one grid, the parameter for lower repetitions is used and the upper repetitions are ignored.

**Subsection:** Geometry model / Ellipsoidal chunk#

**Parameter name:** Depth#

**Default value:** 500000.0

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

**Documentation:** Bottom depth of model region.

**Parameter name:** Depth subdivisions#

**Default value:** 1

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

**Documentation:** The number of subdivisions of the coarse (initial) mesh in depth.

**Parameter name:** East-West subdivisions#

**Default value:** 1

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

**Documentation:** The number of subdivisions of the coarse (initial) mesh in the East-West direction.

**Parameter name:** Eccentricity#

**Default value:** 8.1819190842622e-2

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

**Documentation:** Eccentricity of the ellipsoid. Zero is a perfect sphere, default (8.1819190842622e-2) is WGS84.

**Parameter name:** NE corner#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Longitude:latitude in degrees of the North-East corner point of model region.The North-East direction is positive. If one of the three corners is not provided the missing corner value will be calculated so all faces are parallel.

**Parameter name:** NW corner#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Longitude:latitude in degrees of the North-West corner point of model region. The North-East direction is positive. If one of the three corners is not provided the missing corner value will be calculated so all faces are parallel.

**Parameter name:** North-South subdivisions#

**Default value:** 1

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

**Documentation:** The number of subdivisions of the coarse (initial) mesh in the North-South direction.

**Parameter name:** SE corner#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Longitude:latitude in degrees of the South-East corner point of model region. The North-East direction is positive. If one of the three corners is not provided the missing corner value will be calculated so all faces are parallel.

**Parameter name:** SW corner#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Longitude:latitude in degrees of the South-West corner point of model region. The North-East direction is positive. If one of the three corners is not provided the missing corner value will be calculated so all faces are parallel.

**Parameter name:** Semi-major axis#

**Default value:** 6378137.0

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

**Documentation:** The semi-major axis (a) of an ellipsoid. This is the radius for a sphere (eccentricity=0). Default WGS84 semi-major axis.

**Subsection:** Geometry model / Initial topography model#

**Parameter name:** Model name#

**Default value:** zero topography

**Pattern:** [Selection ascii data|function|prm polygon|zero topography ]

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

‘ascii data’: Implementation of a model in which the surface topography is derived from a file containing data in ascii format. The following geometry models are currently supported: box, chunk. Note the required format of the input data: The first lines may contain any number of comments if they begin with ‘#’, but one of these lines needs to contain the number of grid points in each dimension as for example ‘# POINTS: 3 3’. The order of the data columns has to be ‘x’, ‘Topography [m]’ in a 2d model and ‘x’, ‘y’, ‘Topography [m]’ in a 3d model, which means that there has to be a single column containing the topography. Note that the data in the input file needs to be sorted in a specific order: the first coordinate needs to ascend first, followed by the second in order to assign the correct data to the prescribed coordinates. If you use a spherical model, then the assumed grid changes. ‘x’ will be replaced by the azimuth angle (longitude) in radians (between zero and \(2\pi\), not between \(-\pi\) corresponding to 180 degrees west, and \(+\pi\) corresponding to 180 degrees east), and ‘y’ by the polar angle in radians (between \(0\) and \(\pi\)) measured positive from the north pole. The grid will be assumed to be a longitude-colatitude grid. Note that the order of spherical coordinates is ‘phi’, ‘theta’ and not ‘theta’, ‘phi’, since this allows for dimension independent expressions.

‘function’: Implementation of a model in which the initial topography is described by a function in Cartesian or spherical coordinates.

‘prm polygon’: An initial topography model that defines the initial topography as constant inside each of a set of polygonal parts of the surface. The polygons, and their associated surface elevation, are defined in the ‘Geometry model/Initial topography/Prm polygon’ section.

‘zero topography’: Implementation of a model in which the initial topography is zero.

**Subsection:** Geometry model / Initial topography model / Ascii data model#

**Parameter name:** Data directory#

**Default value:** $ASPECT_SOURCE_DIR/data/geometry-model/initial-topography-model/ascii-data/test/

**Pattern:** [DirectoryName]

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

**Parameter name:** Data file name#

**Default value:** box_2d_%s.0.txt

**Pattern:** [Anything]

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

**Parameter name:** Scale factor#

**Default value:** 1.

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

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

**Subsection:** Geometry model / Initial topography model / Function#

**Parameter name:** Coordinate system#

**Default value:** cartesian

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

**Documentation:** A selection that determines the assumed coordinate system for the function variables. Allowed values are ‘cartesian’ and ‘spherical’. ‘spherical’ coordinates are interpreted as r,phi or r,phi,theta in 2d/3d respectively with theta being the polar angle.

**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:** Maximum topography value#

**Default value:** 2000.

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

**Documentation:** The maximum value the topography given by the function can take.

**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:** Geometry model / Initial topography model / Prm polygon#

**Parameter name:** Topography parameters#

**Default value:**

**Pattern:** [Anything]

**Documentation:** Set the topography height and the polygon which should be set to that height. The format is : “The topography height extgreater The point list describing a polygon & The next topography height extgreater the next point list describing a polygon.” The format for the point list describing the polygon is “x1,y1;x2,y2”. For example for two triangular areas of 100 and -100 meters high set: ’100 extgreater 0,0;5,5;0,10 & -100 extgreater 10,10;10,15;20,15’. Units of the height are always in meters. The units of the coordinates are dependent on the geometry model. In the box model they are in meters, in the chunks they are in degrees, etc. Please refer to the manual of the individual geometry model to so see how the topography is implemented.

**Subsection:** Geometry model / Sphere#

**Parameter name:** Radius#

**Default value:** 6371000.

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

**Documentation:** Radius of the sphere. Units: \si{\meter}.

**Subsection:** Geometry model / Spherical shell#

**Parameter name:** Cells along circumference#

**Default value:** 0

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

**Documentation:** The number of cells in circumferential direction that are created in the coarse mesh in 2d. If zero, this number is chosen automatically in a way that produces meshes in which cells have a reasonable aspect ratio for models in which the depth of the mantle is roughly that of the Earth. For planets with much shallower mantles and larger cores, you may want to chose a larger number to avoid cells that are elongated in tangential and compressed in radial direction.

In 3d, the number of cells is computed differently and does not have an easy interpretation. Valid values for this parameter in 3d are 0 (let this class choose), 6, 12 and 96. Other possible values may be discussed in the documentation of the deal.II function GridGenerator::hyper_shell. The parameter is best left at its default in 3d.

In either case, this parameter is ignored unless the opening angle of the domain is 360 degrees. This parameter is also ignored when using a custom mesh subdivision scheme.

**Parameter name:** Custom mesh subdivision#

**Default value:** none

**Pattern:** [Selection none|list of radial values|number of slices ]

**Documentation:** Choose how the spherical shell mesh is generated. By default, a coarse mesh is generated with respect to the inner and outer radius, and an initial number of cells along circumference. In the other cases, a surface mesh is first generated and refined as desired, before it is extruded radially following the specified subdivision scheme.

**Parameter name:** Initial lateral refinement#

**Default value:** 0

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

**Documentation:** Initial lateral refinement for the custom mesh subdivision schemes.The number of refinement steps performed on the initial coarse surface mesh, before the surface is extruded radially. This parameter allows the user more control over the ratio between radial and lateral refinement of the mesh.

**Parameter name:** Inner radius#

**Default value:** 3481000.

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

**Documentation:** Inner radius of the spherical shell. Units: \si{\meter}.

Note

The default value of 3,481,000 m equals the radius of a sphere with equal volume as Earth (i.e., 6371 km) minus the average depth of the core-mantle boundary (i.e., 2890 km).

**Parameter name:** List of radial values#

**Default value:**

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

**Documentation:** List of radial values for the custom mesh scheme. Units: \(\si{m}\). A list of radial values subdivides the spherical shell at specified radii. The list must be strictly ascending, and the first value must be greater than the inner radius while the last must be less than the outer radius.

**Parameter name:** Number of slices#

**Default value:** 1

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

**Documentation:** Number of slices for the custom mesh subdivision scheme. The number of slices subdivides the spherical shell into N slices of equal thickness. Must be greater than 0.

**Parameter name:** Opening angle#

**Default value:** 360.

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

**Documentation:** Opening angle in degrees of the section of the shell that we want to build. The only opening angles that are allowed for this geometry are 90, 180, and 360 in 2d; and 90 and 360 in 3d. Units: degrees.

**Parameter name:** Outer radius#

**Default value:** 6336000.

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

**Documentation:** Outer radius of the spherical shell. Units: \si{\meter}.

Note

The default value of 6,336,000 m equals the radius of a sphere with equal volume as Earth (i.e., 6371 km) minus the average depth of the mantle-crust interface (i.e., 35 km).

**Parameter name:** Phi periodic#

**Default value:** false

**Pattern:** [Bool]

**Documentation:** Whether the shell should be periodic in the phi direction.