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

1. 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]\).

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.

3. We use the word “extensive” to mean a quantity that is measuring the quantity, and is not per unit grid cell volume or area.

4. Here the number indicates the coordinate dimension, e.g. x,y,z.

5. Conserved quantity for a PK.

6. 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.

7. 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.

8. Note that, unless otherwise specified, [mol] always means mols of water.

9. [mol C] implies mols of an arbitrary component C.