Gravity model#
Subsection: Gravity model#
Parameter: Model name
Default value: unspecified
Pattern: [Selection ascii data|function|radial constant|radial linear|radial with tidal potential|vertical|unspecified ]
Documentation: Select one of the following models:
‘ascii data’: Gravity is read from a file that describes the reference state. The default profile follows the preliminary reference Earth model (PREM, Dziewonski and Anderson, 1981). 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 a column named ‘gravity’. 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.
‘function’: Gravity is given in terms of an explicit formula that is elaborated in the parameters in section “Gravity model|Function”. The format of these functions follows the syntax understood by the muparser library, see How to write Function expressions in parameter files.
‘radial constant’: A gravity model in which the gravity has a constant magnitude and the direction is radial (pointing inward if the value is positive). The magnitude is read from the parameter file in subsection ’Radial constant’.
‘radial linear’: A gravity model which is radial (pointing inward if the gravity is positive) and the magnitude changes linearly with depth. The magnitude of gravity at the surface and bottom is read from the input file in a section “Gravity model/Radial linear”.
‘radial with tidal potential’: A gravity model that is the sum of the ‘radial constant’ model (which is radial, pointing inward if the gravity is positive), and a term that results from a tidal potential and that leads to a gravity field that varies with latitude and longitude, as well as time from Tobie et al. (2025) (https://doi.org/10.1007/s11214-025-01136-y). Out of five components for tidal potential from \(T_*\) to \(T_3\), \(T_*\) and \(T_0\) control the shape of the modeled body and are not related to heating, which are pulling of perturbing body and nonsynchronous rotation of modeled body, respectively (The heating-related components are simplified as an equation in Tidal Heating Module). Nonsynchronous rotation occurs in planetary bodies where a liquid layer decouples rotation of surrounding solid layers. The magnitude of gravity for the radial constant part is read from the input file in a section ‘Gravity model/Radial constant’; the parameters that describe the tidal potential contribution are read from a section ‘Gravity model/Radial with tidal potential’. This module only works in spherical geometries. For 2d models, the geometry is interpreted to lie in the equatorial plane.
‘vertical’: A gravity model in which the gravity direction is vertical (pointing downward for positive values) and at a constant magnitude by default equal to one.
Subsection: Gravity model / Ascii data model#
Parameter: Data directory
Default value: $ASPECT_SOURCE_DIR/data/gravity-model/
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. A trailing slash at the end of the directory path is optional; the plugin will automatically append a ’/’ when the parameters are parsed if it is missing.
Parameter: Data file name
Default value: prem.txt
Pattern: [Anything]
Documentation: The file name of the model data.
Parameter: 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: Gravity model / Function#
Parameter: 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: 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: Function expression
Default value: 0; 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: 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: Gravity model / Radial constant#
Parameter: Magnitude
Default value: 9.81
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Magnitude of the gravity vector in \(\mathrm{m}\,\mathrm{s}^{-2}\). For positive values the direction is radially inward towards the center of the earth.
Subsection: Gravity model / Radial linear#
Parameter: Magnitude at bottom
Default value: 10.7
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Magnitude of the radial gravity vector at the bottom of the domain. ‘Bottom’ means the maximum depth in the chosen geometry, and for example represents the core-mantle boundary in the case of the ‘spherical shell’ geometry model, and the center in the case of the ‘sphere’ geometry model. Units: \(\mathrm{m}\,\mathrm{s}^{-2}\).
Parameter: Magnitude at surface
Default value: 9.8
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Magnitude of the radial gravity vector at the surface of the domain. Units: \(\mathrm{m}\,\mathrm{s}^{-2}\).
Subsection: Gravity model / Radial with tidal potential#
Parameter: Mass of perturbing body
Default value: 1.898e27
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Mass of body that perturbs gravity of modeled body. The default value is chosen for modeling Europa, therefore, it is the mass of Jupiter. Units: \(\mathrm{kgram}\).
Parameter: Period of nonsynchronous rotation
Default value: 10000
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Period of nonsynchronous rotation (NSR). The default value is the period of NSR on Europa’s icy shell. Units is year when ’Use years instead of seconds’ is true, and \(\mathrm{s}\) when ’Use years instead of seconds’ is false.
Parameter: Semimajor axis of orbit
Default value: 670900000
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: The length of the semimajor axis of the orbit that cause the tidal perturbation. For example, tidal perturbation on Europa happens by Europa orbiting Jupiter, and that on Earth, if Moon is in consideration, happens by Moon orbiting Earth. The default value is for the semimajor axis of Europa’s orbit. Units: \(\mathrm{m}\).
Subsection: Gravity model / Vertical#
Parameter: Magnitude
Default value: 1.
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Value of the gravity vector in \(\mathrm{m}\,\mathrm{s}^{-2}\) directed along the negative \(y\) (in 2d) or \(z\) (in 3d) axis (if the magnitude is positive.