About the Specification#
ATS, and Amanzi’s “native” specificiation, is an xml file following Trilinos’s Teuchos ParameterList schema. There are only two types of tags used – “Parameter” and “ParameterList”. “Parameter” elements consist of “name”, “type”, and “value” attributes. “ParameterList” elements use the “name” attribute and include subelements that are other “ParameterList” and “Parameter” elements.
The top-most, “main” list is read by the code and used to provide all information needed to run the simulation. This input spec is designed for the code, not necessarily for the user. In general, avoid writing input files from scratch, and prefer to modify existing demos or examples.
Additionally, the ATS Input Spec tool can be used to generate ATS input files through a python script. Despite this tool, it is important to be able to parse and understand the resulting xml file.
Here we document the input spec by defining what each possible element used by the code needs to be well posed.
Specs#
In many cases, the input specifies data for a particular parameterized model, and ATS supports a number of parameterizations. For example, initial data might be uniform (the value is required), or linear in y (the value and its gradient are required). Where ATS supports a number of parameterized models for quantity Z, the available models will be listed by name, and then will be described in the subsequent section. For example, the specification for an “apple” list might look like:
apple-spec
“apple kind”
[string]
A string defining the kind of apple; valid choices include “cosmic crisp”, “granny smith”, or “golden delicious”“color”
[string]
red The color of the apple, defaults to “red”.
An “apple-spec” might be used when defining a pie recipe:
apple-pie-spec
“apple”
[apple-spec]
“apple volume [cups]”
[double]
1
Note that the “apple” entry would be a ParameterList, named “apple”, that includes all of the parameters required to define an “apple-spec”. Also, note that, wherever possible, units are defined in the name of the parameter.
An example of using such a specification:
<ParameterList name="my apple pie">
<Parameter name="apple volume [cups]" type="double" value="1.5"/>
<ParameterList name="apple">
<Parameter name="apple kind" type="string" value="granny smith"/>
<Parameter name="color" type="string" value="green"/>
</ParameterList>
</ParameterList>
or equivalently,
my apple pie:
apple volume [cups]: 1.5
apple:
apple kind: granny smith
color: green
Syntax#
Reserved keywords and labels are “quoted and italicized” – these labels or values of parameters in user-generated input files must match (using XML matching rules) the specified or allowable values.
User-defined labels are indicated with ALL-CAPS, and are meant to represent a typical or default name given by a user - these can be names or numbers or whatever serves best the organization of the user input data. Things liked PRESSURE or SURFACE-PONDED_DEPTH can be renamed from their defaults if it makes sense to the problem.
Bold values are default values, and are used if the Parameter is not provided.
Units#
Wherever possible, units for a parameter are included in the parameter name, in brackets, and in SI units. When there are common alternative units (e.g. g/mL) we sometimes provide a second parameter option with the same name, but different units.
All units are written in the numerator. ^ is used to indicate powers, including negative powers. For example, a parameter prescribing the density of water might be: “density of water [kg m^-3]”.
Variable Naming#
Unlike parameters (which can only be spelled one way), variables are often named with user-defined strings which have a default value. For instance, a Richards equation might need a variable defining the saturation of the liquid phase. By default, we would call this “saturation_liquid”, but the user may choose to override this name. This makes variables hard to define with certainty, because the user may change these things. This is a feature, but to a new user, it may seem confusing. Prefer to use default names wherever possible, unless there is a good reason not to do so.
Variables are named according to a very strong convention. While variable names may be overridden by the user, users should choose to follow these conventions or things like visualization scripts may not behave as expected.
A variable name looks like one of:
ROOT_NAME
DOMAIN-ROOT_NAME
DOMAIN_SET:ID-ROOT_NAME
where:
ROOT_NAME is the root of the variable, e.g. “temperature”.
When DOMAIN is not supplied, it is implied to be the “default” mesh, called “domain” in the mesh list. Otherwise the domain name is the same as the mesh name (e.g. “surface”). This distinguishes between “surface-temperature” (the temperature on the surface mesh) and “temperature” (the temperature on the subsurface/domain mesh).
DOMAIN_SET:ID is itself a DOMAIN, where the set defines the collection as a whole (from the mesh list) and the ID is defined by an index across the collection, e.g. “column:4”. So “column:4-temperature” is the temperature on the 4th domain of the domain set “column”.
Tags indicate the use of a variable at a specific time in the discretized time interval. Default tags include “current” and “next” indicating the variable at the beginning and end of the interval, respectively. Often subcycling and other schemes will designate special-purpose tags which may be used internally by a subset of the equations begin solved. Tags are combined with variables to indicate a specific data structure, e.g. “surface-pressure@next”. Note that the default tag “” is equivalent to “next”.
Lastly, derivatives are named using the “d” and the “|” character, e.g. “dsurface-water_content|dsurface-pressure” is the derivative of the “water_content” variable on the “surface” domain with respect to the “pressure” on the same domain.
As a result of these conventions, none of the above individual strings, (root names, domains, domain sets, or IDs) can contain any of the following reserved characters: :, -, |, @.
Avoid including spaces in variable names. This doesn’t break the code, but it does break some visualization tools.
Default Names, Symbols, and Units#
- Author:
Coon
Variable Root Name |
Symbol |
Description |
Units |
Process |
---|---|---|---|---|
coordinate, centroid |
\(x\), \(y\), \(z\) |
spatial coordinates |
\([m]\) |
|
time |
\(t\) |
time variable |
\([s]\) |
|
cell_volume |
\(\vert V \vert\), \(V\) |
volume (if 3D) or area (if 2D) of a discrete element |
\([m^3]\) or \([m^2]\) |
|
gravity |
\(g\) |
gravitational acceleration vector |
\([m \, s^{-2}]\) |
|
canopy-drainage |
\(D\) |
flux of water dripping from the canopy to the ground below |
\([m \, s^{-1}]\) |
canopy |
canopy-throughfall_drainage_{rain,snow} |
source of {rain,snow} to the respective layer, throughfall + drainage |
\([m \, s^{-1}]\) |
canopy |
|
canopy-evaporation |
\(E_{can}\) |
evaporative flux of stored water from the leaf surface |
\([m \, s^{-1}]\) |
canopy |
canopy-fracwet |
\(f_{wet}\) |
fraction of the canopy leaf area that is covered in water |
\([-]\) |
canopy |
canopy-water_content |
\(\Theta_{can}\) |
\(^5\) extensive water content on the leaf surface |
\([\mathop{\mathrm{mol}}] ^8\) |
canopy |
canopy-water_equivalent |
effective thickness of water (per unit surface or leaf area???) |
\([m]\) |
canopy |
|
canopy-water_source |
sum of all sources and sinks of water to the leaf surface |
\([\mathop{\mathrm{mol}} \, m^2 \, s^{-1}]\) |
canopy |
|
canopy-water_source_meters |
sum of all sources and sinks of water to the leaf surface |
\([m \, s^{-1}]\) |
canopy |
|
canopy-interception |
\(I_{can}\) |
flux of water to the canopy as intercepted rain or snow |
\([m \, s^{-1}]\) |
canopy |
canopy-leaf_area_index |
\(LAI\) |
leaf area per unit surface area |
\([-]\) |
canopy |
canopy-potential_transpiration |
\(T_{pot}\) |
potential transpiration, unlimited by water availability |
\([m \, s^{-1}]\) |
canopy |
canopy-potential_transpiration_mols |
\(T_{pot}\) |
potential transpiration, unlimited by water availability |
\([\mathop{\mathrm{mol}} \, m^{-2} \, s^{-1}]\) |
canopy |
canopy-temperature |
\(T_{can}\) |
leaf temperature, used in longwave radiation out calculation |
\([K]\) |
canopy |
{canopy,snow,surface}-radiation_balance |
net energy balance including radiation and conduction (Priestley-Taylor’s R - G) |
surface |
||
snow-depth |
\(h_{snow}\) |
thickness of the snowpack |
\([m]\) |
snow |
snow-age |
average age of the snowpack |
\([day]\) |
snow |
|
snow-density |
\(\rho_{snow}\) |
Mass density of the snow |
\([kg \, m^-3]\) |
snow |
snow-melt |
\(M\) |
Snow melt rate (SWE) |
\([m \mathop{\mathrm{SWE}} s^{-1}]\) |
snow |
snow-precipitation |
\(P_{snow}\) |
precipitation of snow, in snow-water-equivalent (SWE) |
\([m \mathop{\mathrm{SWE}} \, s^{-1}]\) |
snow |
snow-evaporation |
\(E_{snow}\) |
evaporation of snow, in snow-water-equivalent (SWE) |
\([m \mathop{\mathrm{SWE}} \, s^{-1}]\) |
snow |
snow-source_sink |
\(Q_{snow}\) |
extensive sum of all sources and sinks of water as snow |
\([\mathop{\mathrm{mol}} \, s^{-1}]\) ?? |
snow |
snow-water_source |
\(Q_{snow}\) |
sum of all sources and sinks of water as snow |
\([\mathop{\mathrm{mol}} \, m^{-2} s^{-1}]\) ?? |
snow |
snow-water_source_meters |
\(Q_{snow}\) |
sum of all sources and sinks of water as snow |
\([m \, s^{-1}]\) ?? |
snow |
snow-source |
sum of all sources of water as snow, excluding sinks |
\([m \, s^{-1}]\) |
snow |
|
snow-death_rate |
If all snow disappears in a timestep, the effective rate of snow loss. |
\([m \mathop{\mathrm{SWE}} s^{-1}]\) |
snow |
|
snow-water_equivalent |
\(SWE\) |
equivalent “ponded_depth” if one melted the snow |
\([m]\) |
snow |
snow-water_content |
\(\Theta_{snow}\) |
\(^5\) extensive water content in snow |
\([\mathop{\mathrm{mol}}] ^8\) |
snow |
snow-temperature |
\(T_{snow}\) |
temperature of the snowpack |
\([K]\) |
snow |
surface-ponded_depth |
\(h\) |
ponded depth, or the water head over the surface |
\([m]\) |
flow |
surface-unfrozen_effective_depth |
\(\eta h\) |
portion of ponded depth that is unfrozen |
\([m]\) |
flow |
surface-unfrozen_fraction |
\(\eta\) |
fraction of water on the surface that is liquid (vs ice) |
\([-]\) |
energy |
surface-albedo |
\(\alpha\) |
area-weighted albedo of the surface, as seen by the canopy/atmosphere |
\([-]\) |
surface |
surface-albedos.{bare,water,snow} |
\(\alpha\) |
albedo of a given media |
\([-]\) |
surface |
surface-emissivities.{bare,water,snow} |
\(\epsilon\) |
emissivity (equivalently absorptivity) of a given media |
\([-]\) |
surface |
surface-area_fractions.{bare,water,snow} |
\(a\) |
fraction of the ground surface of a given media |
\([-]\) |
surface |
surface-incoming_longwave_radiation |
\(Q^e_{SW}\) |
longwave radiation from the atmosphere |
\([W \, m^{-2}]\) |
surface |
surface-incoming_shortwave_radiation |
\(Q^e_{SW}\) |
shortwave radiation from the atmosphere |
\([W \, m^{-2}]\) |
surface |
surface-incident_shortwave_radiation |
\(Q^e_{SWin}\) |
shortwave radiation incident on a surface (of a given slope/aspect) |
\([W \, m^{-2}]\) |
surface |
surface-qE_conducted |
\(Q^e_{c}\) |
energy conducted to the ground surface |
\([W \, m^{-2}]\) |
surface |
surface-qE_lw_out |
\(Q^e_{LWout}\) |
longwave energy radiated away from the surface |
\([W \, m^{-2}]\) |
surface |
surface-qE_sensible_heat |
\(Q^e_{h}\) |
sensible heat flux to the atmosphere |
\([W \, m^{-2}]\) |
surface |
surface-qE_latent_heat |
\(Q^e_{E}\) |
latent heat flux to the atmosphere |
\([W \, m^{-2}]\) |
surface |
surface-qE_snowmelt |
\(Q^e_{snow}\) |
latent heat released via snowmelt |
\([W \, m^{-2}]\) |
surface |
surface-transpiration |
\(T\) |
actual transpiration, integrated vertically and limited by water availability |
\([m \, s^{-1}]\) |
flow |
surface-total_evapotranspiration |
\(ET\) |
total evaporation (canopy, snow, and bare ground) plus transpiration |
\([m \, s^{-1}]\) |
flow |
surface-capillary_pressure_plant |
\(pc_{can}\) |
capillary pressure in the plant stem at the ground surface |
\([Pa]\) |
flow |
surface-overland_conductivity |
\(k\) |
coefficient for the diffusion wave equation |
\([...]\) |
flow |
surface-manning_coefficient |
\(m_n\) |
coefficient in Manning’s equation, a measure of surface roughness |
\([...]\) |
flow |
surface-precipitation_rain |
\(P_{r}\) |
precipitation of rain |
\([m \, s^{-1}]\) |
surface |
surface-air_temperature |
\(T_{air}\) |
temperature of the air at the ground surface |
\([K]\) |
surface |
surface-vapor_pressure_air |
\(vp_{air}\) |
partial pressure of water vapor in the atmosphere |
\([Pa]\) |
surface |
surface-wind_speed |
\({v}_{air}\) |
magnitude of the wind speed |
\([m \, s^{-1}]\) |
surface |
surface-water_source |
\(Q_s\) |
extensive sum of all sources and sinks of water as liquid (surface) |
\([\mathop{\mathrm{mol}} \, s^{-1}]\) |
flow |
surface-elevation |
\(z\) |
elevation |
\([m]\) |
|
surface-aspect |
\(\psi\) |
aspect, clockwise relative to North, in [0,360) |
\([degrees]\) |
surface |
surface-slope_magnitude |
\(\vert S \vert\) |
1 - dot product of the surface’s normal with the vertical |
\([-]\) |
flow |
surface-water_flux |
\(\mathbf{q_s}\) |
surface flux vector |
\([\mathop{\mathrm{mol}} \, s^{-1}]\) |
flow |
surface-velocity.{1,2} \(^4\) |
\(\mathbf{V_s}\) |
surface water velocity vector |
\([m \, s^{-1}]\) |
flow |
surface-evaporative_flux |
\(E\) |
water sink due to evaporation |
\([m \, s^{-1}]\) |
flow |
surface-evaporation |
\(E\) |
water sink due to evaporation |
\([m \, s^{-1}]\) |
flow |
surface-soil_resistance |
\(r_{soil}\) |
resistance of soil to water vapor transport, used in evaporation downregulation |
\([-]\) |
flow |
surface-subsurface_flux |
\(\mathbf{q_{ss}}\) |
infiltration, the flux of water into the ground |
\([\mathop{\mathrm{mol}} \, s^{-1}]\) |
flow |
surface-subsurface_energy_flux |
\(\mathbf{q^e_{ss}}\) |
diffusive flux of energy into the ground |
\([\mathop{\mathrm{MJ}} \, s^{-1}]\) |
energy |
surface-advected_energy_flux |
\(\mathbf{eq_s}\) |
extensive energy flux due to advection (face-based) |
\([\mathop{\mathrm{MJ}} \, s^{-1}]\) |
energy |
surface-diffusive_energy_flux |
\(\mathbf{q_s^e}\) |
extensive energy flux due to diffusion (face-based) |
\([\mathop{\mathrm{MJ}} \, s^{-1}]\) |
energy |
surface-water_content |
\(\Theta_s\) |
\(^5\) extensive water content (liquid or ice, but not snow) of a cell |
\([\mathop{\mathrm{mol}}]\) |
flow |
surface-temperature |
\(T_s\) |
temperature of ponded water or the ground surface |
\([K]\) |
energy |
surface-source_molar_density |
\(n_{source}\) |
molar density of all water sources (surface) |
\([\mathop{\mathrm{mol}} \, m^{-3}]\) |
flow |
transpiration |
\(T\) |
actual transpiration, vertically distributed to the subsurface |
\([\mathop{\mathrm{mol}} \, m^-3 \, s^{-1}]\) |
flow |
root_fraction |
\(f_r\) |
fraction of all roots in this soil layer (vertically sums to 1) |
\([-]\) |
flow |
permeability |
\(K\) |
absolute permeability |
\([m^2]\) |
flow |
relative_permeability \(^1\) |
\(k_r\) |
relative **conductivity**, \(\frac{n}{\mu} k\) |
see note |
flow |
molar_density_{liquid,gas,ice} \(^7\) |
\(n_{\{l,g,i\}}\) |
molar density of a given phase |
\([\mathop{\mathrm{mol}} \, m^{-3}]\) |
|
mass_density_{liquid,gas,ice} |
\(\rho_{\{l,g,i\}}\) |
mass density of a phase |
\([\mathop{\mathrm{kg}} \, m^{-3}]\) |
|
density_rock |
\(\rho_{rock}\) |
mass density of the medium |
\([\mathop{\mathrm{kg}} \, m^{-3}]\) |
|
pressure |
\(p\) |
pressure of the liquid phase |
\([\mathop{\mathrm{Pa}}]\) |
flow |
water_source |
\(Q\) |
extensive sum of all sources and sinks of water as liquid (subsurface) |
\([\mathop{\mathrm{mol}} \, s^{-1}]\) |
flow |
source_molar_density |
\(n_{source}\) |
molar density of all water sources (subsurface) |
\([\mathop{\mathrm{mol}} \, m^{-3}]\) |
flow |
saturation_{liquid,gas,ice} |
\(s_{\{l,g,i\}}\) |
saturation of a given phase |
\([-]\) |
flow |
capillary_pressure_{A}_{B} |
\(p_c^{A-B}\) |
capillary pressure of phase A over phase B |
\([Pa]\) |
flow |
viscosity_liquid |
\(\nu\) |
dynamic viscosity of water |
\([\mathop{\mathrm{Pa}} \, s]\) |
flow |
base_porosity |
\(\phi_0\) |
porosity of the undeformed medium |
\([-]\) |
flow |
porosity |
\(\phi\) |
porosity of the medium, including any compressibility/specific storage |
\([-]\) |
flow |
water_flux |
\(\mathbf{q}\) |
extensive water flux (face-based) |
\([\mathop{\mathrm{mol}} \, s^{-1}]\) |
flow |
darcy_velocity.{1,2,3} \(^4\) |
\(\mathbf{V}\) |
subsurface water velocity vector |
\([m \, s^{-1}]\) |
flow |
water_content |
\(\Theta\) |
\(^5\) extensive water content (liquid, ice, or vapor) of a cell |
\([\mathop{\mathrm{mol}}] ^8\) |
flow |
temperature |
\(T\) |
temperature |
\([K]\) |
energy |
thermal_conductivity |
\(\kappa\) |
thermal conductivity of the grid cell |
\([\mathop{\mathrm{MW}} \, m^{-1} \, K^{-1}]\) |
energy |
total_energy_source \(^2\) |
\(Q^e\) |
\(^3\) extensive sum of all sources and sinks of energy |
\([\mathop{\mathrm{MJ}} \, s^{-1}]\) |
energy |
advected_energy_flux |
\(\mathbf{eq}\) |
extensive energy flux due to advection (face-based) |
\([\mathop{\mathrm{MJ}} \, s^{-1}]\) |
energy |
diffusive_energy_flux |
\(\mathbf{q^e}\) |
extensive energy flux due to diffusion (face-based) |
\([\mathop{\mathrm{MJ}} \, s^{-1}]\) |
energy |
internal_energy_{liquid,gas,ice,rock} |
\(u_X\) |
\(^6\) specific internal energy of a given phase/medium |
\([\mathop{\mathrm{MJ}} \, \mathop{\mathrm{mol}}^{-1}]\) |
energy |
energy |
\(E\) |
\(^5\) extensive energy of a cell |
\([\mathop{\mathrm{MJ}}]\) |
energy |
enthalpy |
\(e\) |
\(^6\) specific enthalpy |
\([\mathop{\mathrm{MJ}} \, \mathop{\mathrm{mol}}^{-1}]\) |
energy |
mole_ratio |
\(\xi^C\) |
ratio of mols of C to mols of H2O, typically in the liquid phase |
\([\mathop{\mathrm{mol C}} \, \mathop{\mathrm{mol H2O}}^{-1}] ^9\) |
transport |
total_component_concentration |
\(C\) |
concentration of a component C in liquid water |
$[mathop{mathrm{mol C}} \, L^{-1} |
chemistry |
mineral_volume_fractions |
mineral volume fractions for solid phase reactions |
\([-]\) |
chemistry |
|
mineral_specific_surface_area |
specific surface area of solid phase |
\([m^2 \mathop{\mathrm{(surface area)}} m^-3]\) |
chemistry |
|
mineral_rate_constant |
reaction rate constants for solid phase |
?? |
chemistry |
|
surface_site_density |
density of sites for surface complexation ?? |
?? |
chemistry |
|
total_sorbed |
C^{sorb} |
concentration of sorbed C |
\([\mathop{\mathrm{mol C}} \, L^{-1}]\) |
chemistry |
isotherm_kd |
isotherm k |
?? |
chemistry |
|
isotherm_freundlich_n |
Freundlich’s n for isotherms |
?? |
chemistry |
|
isotherm_langmuir_b |
Langmuir’s b for isotherms |
?? |
chemistry |
|
first_order_decay_rate_constant |
k_{C1,C2} |
decay rate constant for first order reactions from C1 to C2 |
?? |
chemistry |
cation_exchange_capacity |
CEC |
cation exchange capacity |
?? |
chemistry |
aux_data |
auxiliary data needed by the geochemical engine |
n/a |
chemistry |
Note
This is incorrectly named in ATS, as it is not what is traditionally called the relative_permeability. As ATS works in a pressure basis (as opposed to a head basis), it uses Darcy equations that use permeability, not conductivity. The “diffusion” coefficient in Darcy’s equation in pressure form is \(\frac{n}{\mu}k_r K\), where the density, viscosity, and relative permeability are scalars that are typically upwinded or averaged to faces, while the absolute permeability may be a tensor. We therefore store the first three terms together, but incorrectly call this “relative_permeability.” Furthermore, because K is order \(10^{\{-10 -- -15\}}\), but \(\frac{{n}}{{\mu}}\) is order \(10^7\), we are multiplying a very small number by a very large number, a classic problem in numerics. Therefore, we typically rescale both, moving 7 orders of magnitude off of the scalar and putting them on the tensor. As a result, the units of this variable are something like: [mol m^-3 Pa^-1 s^-1 10^7]`, and typical values range from 0 to ~6. Note that the rescaling factor is NOT stored on the absolute permeability, so permeability is in the typical units \([m^2]\).
The total energy source includes both direct sources of energy (e.g. warming/cooling, radiation, etc), but also sources/sinks of internal energy due to sources/sinks of mass. It does not include fluxes of energy, e.g. diffusion or advection of energy.
We use the word “extensive” to mean a quantity that is measuring the quantity, and is not per unit grid cell volume or area.
Here the number indicates the coordinate dimension, e.g. x,y,z.
Conserved quantity for a PK.
We use the word “specific” to mean a quantity that is per unit extent, e.g. specific enthalpy is per unit mol of water, or specific leaf area is per unit dry mass.
This is somewhat of a misnomer – molar density is a property of a component in a phase. These are the molar density of H2O in a given phase, not total mols in a given phase. Perhaps a better name would be molar_density_water_as_liquid.
Note that, unless otherwise specified, [mol] always means mols of water.
[mol C] implies mols of an arbitrary component C.