Boundary velocity model
Contents
Boundary velocity model#
Subsection: Boundary velocity model#
Parameter name: Prescribed velocity boundary indicators#
Default value:
Pattern: [Map of <[Anything]>:<[Selection ascii data|function|gplates|zero velocity ]> of length 0…4294967295 (inclusive)]
Documentation: A comma separated list denoting those boundaries on which the velocity is prescribed, i.e., where unknown external forces act to prescribe a particular velocity. This is often used to prescribe a velocity that equals that of overlying plates.
The format of valid entries for this parameter is that of a map given as “key1 [selector]: value1, key2 [selector]: value2, key3: value3, …” where each key must be a valid boundary indicator (which is either an integer or the symbolic name the geometry model in use may have provided for this part of the boundary) and each value must be one of the currently implemented boundary velocity models. “selector” is an optional string given as a subset of the letters ‘xyz’ that allows you to apply the boundary conditions only to the components listed. As an example, ’1 y: function’ applies the type ‘function’ to the y component on boundary 1. Without a selector it will affect all components of the velocity.
Note that the no-slip boundary condition is a special case of the current one where the prescribed velocity happens to be zero. It can thus be implemented by indicating that a particular boundary is part of the ones selected using the current parameter and using “zero velocity” as the boundary values. Alternatively, you can simply list the part of the boundary on which the velocity is to be zero with the parameter “Zero velocity boundary indicator” in the current parameter section.
Note that when “Use years in output instead of seconds” is set to true, velocity should be given in m/yr. The following boundary velocity models are available:
‘ascii data’: Implementation of a model in which the boundary velocity is derived from files containing data in ascii format. 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’, ‘velocity\({}_x\)’, ‘velocity\({}_y\)’ in a 2d model or ‘x’, ‘y’, ‘velocity\({}_x\)’, ‘velocity\({}_y\)’, ‘velocity\({}_z\)’ in a 3d model. Note that the data in the input files need 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 radial distance of the point to the bottom of the model, ‘y’ by the azimuth angle and ‘z’ by the polar angle measured positive from the north pole. The grid will be assumed to be a latitude-longitude grid. Note that the order of spherical coordinates is ‘r’, ‘phi’, ‘theta’ and not ‘r’, ‘theta’, ‘phi’, since this allows for dimension independent expressions. Velocities can be specified using cartesian (by default) or spherical unit vectors. No matter which geometry model is chosen, the unit of the velocities is assumed to be m/s or m/yr depending on the ‘Use years in output instead of seconds’ flag. If you provide velocities in cm/yr, set the ‘Scale factor’ option to 0.01.
‘function’: Implementation of a model in which the boundary velocity is given in terms of an explicit formula that is elaborated in the parameters in section “Boundary velocity model|Function”. The format of these functions follows the syntax understood by the muparser library, see Section~\ref{sec:muparser-format}.
The formula you describe in the mentioned section is a semicolon separated list of velocities for each of the \(d\) components of the velocity vector. These \(d\) formulas are interpreted as having units m/s, unless the global input parameter “Use years in output instead of seconds” is set, in which case we interpret the formula expressions as having units m/year.
Likewise, since the symbol \(t\) indicating time may appear in the formulas for the prescribed velocities, it is interpreted as having units seconds unless the global parameter above has been set.
‘gplates’: Implementation of a model in which the boundary velocity is derived from files that are generated by the GPlates program.
‘zero velocity’: Implementation of a model in which the boundary velocity is zero. This is commonly referred to as a “stick boundary condition”, indicating that the material “sticks” to the material on the other side of the boundary.
Parameter name: Tangential velocity boundary indicators#
Default value:
Pattern: [List of <[Anything]> of length 0…4294967295 (inclusive)]
Documentation: A comma separated list of names denoting those boundaries on which the velocity is tangential and unrestrained, i.e., free-slip where no external forces act to prescribe a particular tangential velocity (although there is a force that requires the flow to be tangential).
The names of the boundaries listed here can either by numbers (in which case they correspond to the numerical boundary indicators assigned by the geometry object), or they can correspond to any of the symbolic names the geometry object may have provided for each part of the boundary. You may want to compare this with the documentation of the geometry model you use in your model.
Parameter name: Zero velocity boundary indicators#
Default value:
Pattern: [List of <[Anything]> of length 0…4294967295 (inclusive)]
Documentation: A comma separated list of names denoting those boundaries on which the velocity is zero.
The names of the boundaries listed here can either by numbers (in which case they correspond to the numerical boundary indicators assigned by the geometry object), or they can correspond to any of the symbolic names the geometry object may have provided for each part of the boundary. You may want to compare this with the documentation of the geometry model you use in your model.
Subsection: Boundary velocity model / Ascii data model#
Parameter name: Data directory#
Default value: $ASPECT_SOURCE_DIR/data/boundary-velocity/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.%d.txt
Pattern: [Anything]
Documentation: The file name of the model data. Provide file in format: (File name).%s%d, where %s is a string specifying the boundary of the model according to the names of the boundary indicators (of the chosen geometry model), and %d is any sprintf integer qualifier specifying the format of the current file number.
Parameter name: Data file time step#
Default value: 1e6
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Time step between following data files. Depending on the setting of the global ‘Use years in output instead of seconds’ flag in the input file, this number is either interpreted as seconds or as years. The default is one million, i.e., either one million seconds or one million years.
Parameter name: Decreasing file order#
Default value: false
Pattern: [Bool]
Documentation: In some cases the boundary files are not numbered in increasing but in decreasing order (e.g. ‘Ma BP’). If this flag is set to ‘True’ the plugin will first load the file with the number ‘First data file number’ and decrease the file number during the model run.
Parameter name: First data file model time#
Default value: 0
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: The ‘First data file model time’ parameter has been deactivated and will be removed in a future release. Do not use this parameter and instead provide data files starting from the model start time.
Parameter name: First data file number#
Default value: 0
Pattern: [Integer range -2147483648…2147483647 (inclusive)]
Documentation: Number of the first velocity file to be loaded when the model time is larger than ‘First velocity file model time’.
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: Use spherical unit vectors#
Default value: false
Pattern: [Bool]
Documentation: Specify velocity as r, phi, and theta components instead of x, y, and z. Positive velocities point up, east, and north (in 3d) or out and clockwise (in 2d). This setting only makes sense for spherical geometries.
Subsection: Boundary velocity model / 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; 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: Use spherical unit vectors#
Default value: false
Pattern: [Bool]
Documentation: Specify velocity as \(r\), \(\phi\), and \(\theta\) components instead of \(x\), \(y\), and \(z\). Positive velocities point up, east, and north (in 3d) or out and clockwise (in 2d). This setting only makes sense for spherical geometries.
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: Boundary velocity model / GPlates model#
Parameter name: Data directory#
Default value: $ASPECT_SOURCE_DIR/data/boundary-velocity/gplates/
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 time step#
Default value: 1e6
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Time step between following velocity files. Depending on the setting of the global ’Use years in output instead of seconds’ flag in the input file, this number is either interpreted as seconds or as years. The default is one million, i.e., either one million seconds or one million years.
Parameter name: Decreasing file order#
Default value: false
Pattern: [Bool]
Documentation: In some cases the boundary files are not numbered in increasing but in decreasing order (e.g. ’Ma BP’). If this flag is set to ’True’ the plugin will first load the file with the number ’First velocity file number’ and decrease the file number during the model run.
Parameter name: First data file model time#
Default value: 0.
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Time from which on the velocity file with number ’First velocity file number’ is used as boundary condition. Previous to this time, a no-slip boundary condition is assumed. Depending on the setting of the global ’Use years in output instead of seconds’ flag in the input file, this number is either interpreted as seconds or as years.
Parameter name: First data file number#
Default value: 0
Pattern: [Integer range -2147483648…2147483647 (inclusive)]
Documentation: Number of the first velocity file to be loaded when the model time is larger than ’First velocity file model time’.
Parameter name: Lithosphere thickness#
Default value: 100000.
Pattern: [Double 0…MAX_DOUBLE (inclusive)]
Documentation: Determines the depth of the lithosphere, so that the GPlates velocities can be applied at the sides of the model as well as at the surface.
Parameter name: Point one#
Default value: 1.570796,0.0
Pattern: [Anything]
Documentation: Point that determines the plane in which a 2d model lies in. Has to be in the format ‘a,b’ where a and b are theta (polar angle) and phi in radians. This value is not utilized in 3d geometries, and can therefore be set to the default or any user-defined quantity.
Parameter name: Point two#
Default value: 1.570796,1.570796
Pattern: [Anything]
Documentation: Point that determines the plane in which a 2d model lies in. Has to be in the format ‘a,b’ where a and b are theta (polar angle) and phi in radians. This value is not utilized in 3d geometries, and can therefore be set to the default or any user-defined quantity.
Parameter name: Scale factor#
Default value: 1.
Pattern: [Double -MAX_DOUBLE…MAX_DOUBLE (inclusive)]
Documentation: Scalar factor, which is applied to the boundary velocity. You might want to use this to scale the velocities to a reference model (e.g. with free-slip boundary) or another plate reconstruction.
Parameter name: Velocity file name#
Default value: phi.%d
Pattern: [Anything]
Documentation: The file name of the material data. Provide file in format: (Velocity file name).%d.gpml where %d is any sprintf integer qualifier, specifying the format of the current file number.