Function: base class for all functions of space and time.
System Message: WARNING/2 (ATSNativeSpec_dev.rst, line 2240)
Block quote ends without a blank line; unexpected unindent.
Analytic, algabraic functions of space and time are used for a variety of
purposes, including boundary conditions, initial conditions, and independent
variables.
For initial conditions, functions are prescribed of space only, i.e.
u = f(x, y, z)
For boundary conditions and independent variables, functions are also a
function of time:
u = f(t, x, y, z)
A [function-spec] is used to prescribe these functions.
It is straightforward to add new functions as needed.
ConstantFunction: Implements the Function interface using a constant value.
Constant function is defined as f(x) = a, for all x.
- "value" [double] The constant to be applied.
Example:
<ParameterList name="function-constant">
<Parameter name="value" type="double" value="1.0"/>
</ParameterList>
TabularFunction: Piecewise-defined function.
A piecewise function of one variable.
A tabular function is tabulated on a series of intervals; given values
xi, yi, , i = 0, ...n − 1 and functional forms fj, , j = 0, ...n − 2 a tabular function f(x) is defined as:
f(x)
=
y0,
x ≤ x0,
f(x)
=
fi − 1(x)
x ∈ (xi − 1, xi],
f(x)
=
yn − 1,
x > xn − 1.
The functional forms fj may be constant, which uses the left endpoint, i.e.
fi(x) = yi,
linear, i.e.
fi(x) = (yi*(x − xi) + yi + 1*(xi + 1 − x)) ⁄ (xi + 1 − xi)
or arbitrary, in which the fj must be provided.
The xi and yi may be provided in one of two ways -- explicitly in the input spec or from an HDF5 file. The length of these must be equal, and the xi must be monotonically increasing. Forms, as defined on intervals, must be of length equal to the length of the xi less one.
Explicitly specifying the data:
- "x values" [Array(double)] the xi
- "y values" [Array(double)] the yi
- "forms" [Array(string)] linear, "constant", "USER_DEFINED"
- "USER_DEFINED" [function-spec] user-provided functional forms on the interval
- "x coordinate" [string] t, "x", "y", "z" defines which coordinate direction the xi are formed, defaulting to time.
The below example defines a function that is zero on interval ( − ∞, 0],
linear on interval (0, 1], constant (f(x)=1) on interval (1, 2],
square root of t on interval (2, 3],
and constant (f(x)=2) on interval (3, ∞].
Example:
<ParameterList name="function-tabular">
<Parameter name="x values" type="Array(double)" value="{0.0, 1.0, 2.0, 3.0}"/>
<Parameter name="x coordinate" type="string" value="t"/>
<Parameter name="y values" type="Array(double)" value="{0.0, 1.0, 2.0, 2.0}"/>
<Parameter name="forms" type="Array(string)" value="{linear, constant, USER_FUNC}"/>
<ParameterList name="USER_FUNC">
<ParameterList name="function-standard-math">
<Parameter name="operator" type="string" value="sqrt"/>
</ParameterList>
</ParameterList>
</ParameterList>
Loading table from file (note that "USER_DEFINED" is not an option here, but could be made so if requested):
- "file" [string] filename of the HDF5 data
- "x header" [string] name of the dataset for the xi in the file
- "y header" [string] name of the dataset for the yi in the file
- "forms" [Array(string)] linear, "constant"
The example below would perform linear-interpolation on the intervals provided by data within the hdf5 file "my_data.h5".
Example:
<ParameterList name="function-tabular">
<Parameter name="file" type="string" value="my_data.h5"/>
<Parameter name="x coordinate" type="string" value="t"/>
<Parameter name="x header" type="string" value="/time"/>
<Parameter name="y header" type="string" value="/data"/>
</ParameterList>
SmoothStepFunction: a smoothed discontinuity.
A smooth C2 function f(x) on interval [x0, x1] is
defined such that f(x) = y_0 for x < x0, f(x) = y_1 for x > x_1, and
monotonically increasing for x ∈ [x0, x1] through cubic
interpolation.
Example:
<ParameterList name="function-smooth-step">
<Parameter name="x0" type="double" value="0.0"/>
<Parameter name="y0" type="double" value="0.0"/>
<Parameter name="x1" type="double" value="1.0"/>
<Parameter name="y1" type="double" value="2.0"/>
</ParameterList>
PolynomialFunction: a polynomial
A generic polynomial function is given by the following expression:
f(x) = n⎲⎳j = 0cj(x − x0)pj
where cj are coefficients of monomials,
pj are integer exponents, and x0 is the reference point.
Example:
<ParameterList name="function-polynomial">
<Parameter name="coefficients" type="Array(double)" value="{{1.0, 1.0}}"/>
<Parameter name="exponents" type="Array(int)" value="{{2, 4}}"/>
<Parameter name="reference point" type="double" value="0.0"/>
</ParameterList>
LinearFunction: a multivariate linear function.
A multi-variable linear function is formally defined by
f(x) = y0 + n − 1⎲⎳j = 0gj(xj − x0, j)
with the constant term "math:y_0 and gradient g0, g1 ..., gn − 1.
If the reference point x0 is specified, it must have the same
number of values as the gradient. Otherwise, it defaults to zero.
Note that one of the parameters in a multi-valued linear function can be time.
Here is an example:
<ParameterList name="function-linear">
<Parameter name="y0" type="double" value="1.0"/>
<Parameter name="gradient" type="Array(double)" value="{{1.0, 2.0, 3.0}}"/>
<Parameter name="x0" type="Array(double)" value="{{2.0, 3.0, 1.0}}"/>
</ParameterList>
SeparableFunction: f(x,y) = f1(x)*f2(y)
A separable function is defined as the product of other functions such as
f(x0, x1, ..., xn − 1) = f1(x0) f2(x1, ..., xn − 1)
where f1 is defined by the "function1" sublist, and
f2 by the "function2" sublist:
<ParameterList name="function-separable">
<ParameterList name="function1">
function-specification
</ParameterList>
<ParameterList name="function2">
function-specification
</ParameterList>
</ParameterList>
AdditiveFunction: f(x,y) = f1(x,y) + f2(x,y)
An additive function simply adds two other function results together.
f(x) = f1(x) + f2(x)
where f1 is defined by the "function1" sublist, and
f2 by the "function2" sublist:
<ParameterList name="function-additive">
<ParameterList name="function1">
function-specification
</ParameterList>
<ParameterList name="function2">
function-specification
</ParameterList>
</ParameterList>
MultiplicativeFunction: f(x,y) = f1(x,y) * f2(x,y)
A multiplicative function simply multiplies two other function results together.
f(x) = f1(x)*f2(x)
where f1 is defined by the "function1" sublist, and
f2 by the "function2" sublist:
<ParameterList name="function-multiplicative">
<ParameterList name="function1">
function-specification
</ParameterList>
<ParameterList name="function2">
function-specification
</ParameterList>
</ParameterList>
CompositionFunction: f(x,y) = f1(x,y) * f2(x,y)
Function composition simply applies one function to the result of another.
f(x) = f1(f2(x))
where f1 is defined by the "function1" sublist, and
f2 by the "function2" sublist:
<ParameterList name="function-composition">
<ParameterList name="function1">
function-specification
</ParameterList>
<ParameterList name="function2">
function-specification
</ParameterList>
</ParameterList>
BilinearFunction: a piecewise bilinear function.
A piecewise bilinear function extends the linear form of the tabular function to two variables.
Define i(x) = i : xi < x < = xi + 1 and similarly j(y) = j : yj < y < = yj + 1 for monotonically increasing xi and yj.
Given a two-dimensional array ui, j, f is then defined by
bilinear interpolation on ui(x), j(y), ui(x) + 1, j(y), ui(x), j(y) + 1, ui(x) + 1, j(y) + 1, if : math : is in
[x0, xn] × [y0, ym], linear interpolation if one of x, y
are out of those bounds, and constant at the corner value if both are out of
bounds.
- "file" [string] HDF5 filename of the data
- "row header" [string] name of the row dataset, the xi
- "row coordinate" [string] one of "t",`"x`",`"y`",`"z`"
- "column header" [string] name of the column dataset, the yi
- "column coordinate" [string] one of "t",`"x`",`"y`",`"z`"
- "value header" [string] name of the values dataset, the ui, j
Example:
<ParameterList name="function-bilinear">
<Parameter name="file" type="string" value="pressure.h5"/>
<Parameter name="row header" type="string" value="/time"/>
<Parameter name="row coordinate" type="string" value="t"/>
<Parameter name="column header" type="string" value="/x"/>
<Parameter name="column coordinate" type="string" value="x"/>
<Parameter name="value header" type="string" value="/pressure"/>
</ParameterList>
DistanceFunction: distance from a reference point.
A distance function calculates distance from reference point x0
using by the following expression:
f(x) = n⎲⎳j = 0mj(xj − x0, j)2
Note that the first parameter in x can be time.
Here is an example of a distance function using isotropic metric:
Example:
.. code-block:: xml
- <ParameterList name="function-distance">
- <Parameter name="x0" type="Array(double)" value="{1.0, 3.0, 0.0}"/>
<Parameter name="metric" type="Array(double)" value="{1.0, 1.0, 1.0}"/>
System Message: WARNING/2 (ATSNativeSpec_dev.rst, line 2595)
Definition list ends without a blank line; unexpected unindent.
</ParameterList>
MonomialFunction: a multivariate monomial function.
A multi-variable monomial function is given by the following expression:
f(x) = cn∏j = 0(xj − x0, j)pj
with the constant factor c, the reference point x0, and
integer exponents pj.
Note that the first parameter in x can be time.
Here is an example of monomial of degree 6 in three variables:
<ParameterList name="function-monomial">
<Parameter name="c" type="double" value="1.0"/>
<Parameter name="x0" type="Array(double)" value="{1.0, 3.0, 0.0}"/>
<Parameter name="exponents" type="Array(int)" value="{2, 3, 1}"/>
</ParameterList>
StandardMathFunction: provides access to many common mathematical functions.
System Message: WARNING/2 (ATSNativeSpec_dev.rst, line 2628)
Block quote ends without a blank line; unexpected unindent.
These functions allow to set up non-trivial time-dependent boundary conditions
which increases a set of analytic solutions that can be used in convergence
analysis tests.
f(x) = A*operator(p*(x − s))
or
f(x) = A*operator(x − s, p)
Note that these operate only on the first coordinate, which is often time.
Function composition can be used to apply these to other coordinates (or
better yet a dimension could/should be added upon request).
- "operator" [string] specifies the name of a standard mathematical function.
Available options are "cos", "sin", "tan", "acos", "asin", "atan",
"cosh", "sinh", "tanh", "exp", "log", "log10", "sqrt", "ceil",
"fabs", "floor", "mod", and "pow".
- "amplitude" [double] specifies a multiplication factor a in formula a f(x).
The multiplication factor is ignored by function mod. Default value is 1.
- "parameter" [double] 1.0 specifies additional parameter p for
math functions with two arguments. These functions are "a pow(x[0], p)"
and "a mod(x[0], p)". Alternative, scales the argument before
application, for use in changing the period of trig functions.
- "shift" [double] specifies a shift of the function argument. Default is 0.
Example:
<ParameterList name="function-standard-math">
<Parameter name="operator" type="string" value="sqrt"/>
<Parameter name="amplitude" type="double" value="1e-7"/>
<Parameter name="shift" type="double" value="0.1"/>
</ParameterList>
This example defines function 1e-7 sqrt(t-0.1).
Operator represents a linear map, and typically encapsulates a discretization.
Operator represents a map from linear space X to linear space Y. Typically,
this map is a linear map, and encapsulates much of the discretization involved
in moving from continuous to discrete equations. At the moment, it is assumed
that X = Y, but this could be changed if future needs require it.
An Operator provides an interface for applying both the forward and inverse
linear map (assuming the map is invertible).
Typically the Operator is never seen by the user; instead the user provides
input information for helper classes based on the continuous mathematical
operator and the desired discretization. These helpers build the needed
Operator, which may incldude information from multiple helpers (i.e. in the
case of Jacobian Operators for a PDE).
However, one option may be provided by the user, which is related to dealing
with nearly singular operators:
- "diagonal shift" [double] 0.0 Adds a scalar shift to the diagonal
of the Operator, which can be useful if the Operator is singular or
near-singular.
OperatorAccumulation generates a diagonal matrix representing accumulation
OperatorAccumulation assembles the discrete form of (∂A)/(∂t).
This class is usually used as part of a preconditioner, providing the linearization:
(∂)/(∂A)⎡⎣(∂A)/(∂t)⎤⎦A0 = (|ΩE|)/(Δt)
for a grid element ΩE.
No options are available here.
OperatorDiffusion form local Op s and global Operator s for elliptic equations:
∇⋅k∇u
with a variety of discretizations. Note also, for reasons that are one part historical and potentially not that valid, this also supports and implementation with an advective source, i.e.:
∇⋅k(∇u + ẑ)
for gravitational terms in Richards equations.
The input spec for a diffusion operator consists of:
- "discretization primary" [string] Currently supported options include:
- "fv: default" the standard two-point flux finite volume discretization
- "nlfv: default" the nonlinear finite volume method of ???
- MFD methods, including:
- "mfd: default"
- "mfd: monotone for hex"
- "mfd: optimized for monotonicity"
- "mfd: two-point flux approximation"
- "mfd: optimized for sparsity"
- "mfd: support operator"
Note that the most commonly used are "fv: default" for simple test
problems (this method is not particularly accurate for distorted
meshes), "mfd: optimized for sparsity" for most real problems on
unstructured meshes, and "mfd: optimized for monotonicity" for
orthogonal meshes with diagonal tensor/scalar coefficients.
- "gravity" [bool] false specifies if the gravitational flow term is included
- "Newton correction" [string] specifies a model for non-physical terms
that must be added to the matrix. These terms represent Jacobian and are needed
for the preconditioner. Available options are "true Jacobian" and "approximate Jacobian".
The FV scheme accepts only the first options. The other schemes accept only the second option.
- "scaled constraint equation" [bool] false rescales flux continuity equations
on mesh faces. These equations are formed without the nonlinear
coefficient. This option allows us to treat the case of zero nonlinear
coefficient, which otherwise generates zero rows in the operator, which is
then singular. At moment this feature does not work with non-zero gravity
term.
- "constraint equation scaling cutoff"" [double] specifies the cutoff value for
applying rescaling strategy described above.
Additional options available only for the MFD family of discretizations include:
- "nonlinear coefficient" [string] specifies a method for treating nonlinear
diffusion coefficient, if any. Available options are "none", "upwind:
face", "divk: cell-face" (default), "divk: face", "standard: cell",
"divk: cell-face-twin" and "divk: cell-grad-face-twin". Symmetry
preserving methods are the divk-family of methods and the classical
cell-centered method ("standard: cell"). The first part of the name
indicates the base scheme. The second part (after the semi-column)
indicates required components of the composite vector that must be provided
by a physical PK.
- "discretization secondary" [string] specifies the most robust
discretization method that is used when the primary selection fails to
satisfy all a priori conditions. This is typically "mfd: default".
Used only when an MFD `"primary discretization`" is used
- "schema" [Array(string)] defines the operator stencil. It is a collection of
geometric objects. Typically this is set by the implementation and is not provided.
- "preconditioner schema" [Array(string)] {face,cell} Defines the
preconditioner stencil. It is needed only when the default assembling
procedure is not desirable. If skipped, the "schema" is used instead.
In addition to the default, {face} may be used, which forms the Schur
complement.
- "consistent faces" [list] may contain a "preconditioner" and
"linear operator" list (see sections Preconditioners_ and LinearSolvers_
respectively). If these lists are provided, and the "discretization
primary" is of type "mfd: *", then the diffusion method
UpdateConsistentFaces() can be used. This method, given a set of cell
values, determines the faces constraints that satisfy the constraint
equation in MFD by assembling and inverting the face-only system. This is
not currently used by any Amanzi PKs.
- "diffusion tensor" [string] allows us to solve problems with symmetric and non-symmetric
(but positive definite) tensors. Available options are symmetric (default) and nonsymmetric.
Additional options for MFD with the gravity term include:
- "gravity term discretization" [string] selects a model for discretizing the
- gravity term. Available options are "hydraulic head" [default] and "finite volume".
The first option starts with equation for the shifted solution, i.e. the hydraulic head,
and derives gravity discretization by the reserve shifting.
The second option is based on the divergence formula.
Example:
<ParameterList name="OPERATOR_NAME">
<Parameter name="discretization primary" type="string" value="mfd: optimized for monotonicity"/>
<Parameter name="discretization secondary" type="string" value="mfd: two-point flux approximation"/>
<Parameter name="schema" type="Array(string)" value="{face, cell}"/>
<Parameter name="preconditioner schema" type="Array(string)" value="{face}"/>
<Parameter name="gravity" type="bool" value="true"/>
<Parameter name="gravity term discretization" type="string" value="hydraulic head"/>
<Parameter name="nonlinear coefficient" type="string" value="upwind: face"/>
<Parameter name="Newton correction" type="string" value="true Jacobian"/>
<ParameterList name="consistent faces">
<ParameterList name="linear solver">
...
</ParameterList>
<ParameterList name="preconditioner">
...
</ParameterList>
</ParameterList>
</ParameterList>
OperatorAdvection assembles the discrete form of:
∇⋅Aq
which advects quantity A with fluxes q.
This is a simple, first-order donor-upwind scheme, and is mostly intended for
use in diffusion-dominated advection-diffusion equations. No options are
available here.