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.
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 “X” list might look like:
X-spec
“Y”
[string]default_value Documentation desribing Y.“Z”
[Z-spec]Model for Z, One of “z1” or “z2” (see below)
Here, an “X” is defined by a “Y” and a “Z”. The “Y” is a string parameter but the “Z” is given by a model (which will require its own set of parameters). The options for “Z” will then be described seperately as a “Z-spec”
An example of using such a specification:
<ParameterList name="X">
<Parameter name="Y" type="string" value="hello"/>
<ParameterList name="z2">
<Parameter name="z2a" type="double" value="0.7"/>
<Parameter name="z2b" type="int" value="3"/>
</ParameterList>
</ParameterList>
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.
Naming#
Variables are named according to a very strong convention. While some variables 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:
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”).
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”
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”.
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: :, -, |, @.
Name and Symbol Index#
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}\) |
extensive water content on the leaf surface:math:^5 |
\([mol]\) |
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 |
\([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 |
\([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 |
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 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 |
\([mol s^{-1}]\) ?? |
snow |
snow-water_source |
\(Q_{snow}\) |
sum of all sources and sinks of water as snow |
\([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 SWE s^-1]\) |
snow |
|
snow-water_equivalent |
\(SWE\) |
equivalent “ponded_depth” if one melted the snow |
\([m]\) |
snow |
snow-water_content |
\(\Theta_{snow}\) |
extensive water content in snow:math:^5 |
\([mol]\) |
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}:math:^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\) |
extensive water content (liquid or ice, but not snow) of a cell:math:^5 |
\([\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 |
\([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:math:^1 |
\(k_r\) |
relative **conductivity**, \(\frac{n}{\mu} k\) |
see note |
flow |
molar_density_{liquid,gas,ice} |
\(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}:math:^4 |
\(\mathbf{V}\) |
subsurface water velocity vector |
\([m s^{-1}]\) |
flow |
water_content |
\(\Theta\) |
extensive water content (liquid, ice, or vapor) of a cell:math:^5 |
\([\mathop{\mathrm{mol}}]\) |
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:math:^2 |
\(Q^e\) |
extensive:math:^3 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\) |
specific internal energy of a given phase/medium |
\([\mathop{\mathrm{MJ}} \mathop{\mathrm{mol}}^{-1}]\) |
energy |
energy |
\(E\) |
extensive energy of a cell:math:^5 |
\([\mathop{\mathrm{MJ}}]\) |
energy |
enthalpy |
\(e\) |
specific:math:^3 enthalpy |
\([\mathop{\mathrm{MJ}} \mathop{\mathrm{mol}}^{-1}]\) |
energy |
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 \dash -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.