Input File XML Schema¶

Overview¶

The present document describes how to specify the data required to execute Amanzi and perform a simulation. This specification should be regarded as a companion to the mathematical requirements document entitled Mathematical Formulation Requirements and Specifications for the Process Models (see ASCEM Overview), and parameterizations of the individual submodels are consistent between Amanzi, the mathematical requirements document and this document.

The open-source, platform independent Akuna user environment can generate Amanzi models and generate corresponding valid, human-readable XML input files that can then be executed by Amanzi. Example input files are available in the Amanzi source repository.

XML Schema 2.3.0¶

Amanzi solves a set of parameterized models for multiphase flow in porous media. An Amanzi simulation is specified by providing:

values for a parameterized PDE-based transport model, including boundary and initial conditions, constitutive laws, and parameterized/phenomenological models for fluid and chemical sources and characterizations of the porous medium,
parameters controlling the selection of key algorithmic options and output,
a description of the (discrete) state of the computational system, including a list of the independent variables and instructions for obtaining or generating the discrete mesh, and a characterization of the (parallel) computing environment.

The primary input to Amanzi is through an XML file. The Amanzi input XML format is defined in terms of the XML schema that can be found in the Amanzi source code repository. Users can construct models and generate compliant XML input files using the Akuna tool suite. Users can also choose to generate compliant file using a text editor or other method.

The following is a description of each of the sections with the XML input schema. Each section includes a short description of what is defined within the section followed by the XML elements available for the section. Not all elements described are required to generated a valid input file. The limited set of required elements is noted in each section. Note that tags for all sections must be present for an input file to be valid even if no elements within that section are required.

Please note, many attributes within the XML list a limited set of specified values. During validation of the input file or initialization of Amanzi the values in the user provided input file will be compared against the limited set provided in the XML Schema document. Errors will occur is the values do not match exactly. These values are CASE SENSITIVE. The Amanzi schema has been designed will all LOWER CASE values. Please note this when writing input file. In particular, “Exodus II” will be evaluated as “exodus ii”.

Amanzi Input¶

The entire input file is encapsulated under the root tag amanzi_input. At this level the version of the input schema and the type of simulation to be conducted are specified through required attributes. The version is specified with the attribute version. The current schema can be found in the repository and install location amanzi.xsd. The simulation type is specified using the attribute type as either structured or unstructured.

For an unstructured simulations the root tag would looks as the following.

<amanzi_input version="2.3.0" type="unstructured">
</amanzi_input>

Model Description¶

This section allows the user to provide information about the model being developed and how and when it was developed. Default units for the model are also stored in this section. This entire section is optional but encouraged for documentation purposes.

The opening tag model_description accepts an attribute name in which the user may give the current model a name. The available elements within model_description include: comments, author, created, modified, model_name, description, purpose, and units. Under the units element, the user may define the default units to used throughout the rest of the input file. The options available for the units element are as follows:

Model_Description Elements	Value Type
comments	string
author	string
created	string
modified	string
model_id	string
description	string
purpose	string
units	element block

The units block specifies the default units to be used through out the input file unless otherwise specified.

Units Elements	Value Type	Value Options
length_unit	string	`m, cm`
time_unit	string	`y, d, h, s`
mass_unit	string	`kg`
conc_unit	string	`molar, mol/m^3`

Here is an overall example for the model description element.

<model_description name="BC Cribs">
  <comments>Some comment here</comments>
  <model_id>DVZ-212a-3217</model_id>
  <author>David Moulton</author>
  <units>
    <length_unit>m</length_unit>
    <time_unit>s</time_unit>
    <mass_unit>kg</mass_unit>
    <conc_unit>molar</conc_unit>
  </units>
</model_description>

Definitions¶

This section allows the user to provide useful definitions to be used throughout the other sections. Definitions are grouped as element blocks: constants and macros.

Constants¶

The user may specify as many constants as desired. The available constants fall into the following types and descriptions:

Constants Elements	Description
constant	general constant definition, can be of any of the following types
time_constant	define a constant with a time value
numerical_constant	define a constant with a numerical value (no units specified)
area_mass_flux_constant	define a constant with an area mass flux value

Each element has the following format:

Constants Elements	Attribute Names	Attribute Type	Attribute Values
constant	name value type	string string string	(user specified name) (value of constant) `none, time, area_mass_flux`
time_constant	name value	string time(,char)	(user specified name) (time value with optional units)
numerical_constant	name value	string exponential	(user specified name) (numerical constant value)
area_mass_flux_constant	name value	string exponential	(user specified name) (flux value)

Here is an overall structure for the constants element.

<constants>
  <constant name="Name of Constant" type="none | time | area_mass_flux" value="constant_value"/>
  <time_constant  name="Name of Time"  value="value,y|d|h|s"/>
  <numerical_constant name="Name of Numerical Constant" value="value_constant"/>
  <area_mass_flux_constant name="Name of Flux Constant" value="value_of_flux"/>
</constants>

Macros¶

The macros section defines time and cycle macros. These specify a series of times or cycles for writing out visualization, checkpoint, walkabout, or observation files. Each macro type is described in the following table. The macro can contain a list of specific time values at which to perform an action or a time/cycle interval at which to perform an action.

Macros Elements	Attribute Names	Attribute Type	Sub-Elements	Sub-Element Type/Value
time_macro (time series)	name	string	time	time(,unit) / value of time with optional unit
time_macro (interval)	name	string	start timestep_interval stop	time(,unit) / value of start time time(,unit) / time interval between actions time(,unit) / final time value ( -1 specifies final time )
cycle_macro (interval)	name	string	start timestep_interval stop	integer / cycle number to start action integer / number of cycles between actions integer / cycle number to stop action ( -1 specifies final step )

Here are examples of the macros:

<time_macro name="Name of Macro">
  <time>Value</time>
</time_macro>

<cycle_macro name="Name of Macro">
  <start>Value</start>
  <timestep_interval>Value</timestep_interval>
  <stop>Value|-1</stop>
</cycle_macro>

Here is an overall example for the definition element.

<definitions>
  <constants>
    <constant name="zero" type="none" value="0.000"/>
    <constant name="start" type="time" value="1956.0,y"/>
    <constant name="future_recharge" type="area_mass_flux" value="1.48666E-6"/>
    <time_constant name="start_time" value="1956.0,y"/>
    <numerical_constant name="zero" value="0.000"/>
  </constants>
  <macros>
    <time_macro name="Macro 1">
      <time>6.17266656E10</time>
      <time>6.3372710016E10</time>
      <time>6.33834396E10</time>
    </time_macro>
    <cycle_macro name = "Every_1000_timesteps">
      <start>0</start>
      <timestep_interval>1000</timestep_interval>
      <stop>-1 </stop>
    </cycle_macro>
  </macros>
</definitions>

Execution Control¶

The execution_controls section defines the general execution of the Amanzi simulation. Amanzi can execute in four modes: steady state, transient, transient with static flow, or initialize to a steady state and then continue to transient. The transient with static flow mode does not compute the flow solution at each time step. During initialization the flow field is set in one of two ways: (1) A constant Darcy velocity is specified in the initial condition; (2) Boundary conditions for the flow (e.g., pressure), along with the initial condition for the pressure field are used to solve for the Darcy velocity. At present this mode only supports the “Single Phase” flow model.

Default values for execution are defined in the execution_control_defaults element. These values are used for any time period during the simulation for which the controls were not specified. Individual time periods of the simulation are defined using execution_control elements. For a steady state simulation, only one execution_control element will be defined. However, for a transient simulation a series of controls may be defined during which different control values will be used. For a valid execution_controls section the execution_control_defaults element and at least one execution_control element must appear.

The execution_controls element has the following subelements:

Execution_controls Elements	Element Type	Description
comments	string	user specified comments
verbosity	string	verbosity level `extreme, high, medium, low, none`
restart	string	name of Amanzi checkpoint file to be used for restart
execution_control_defaults	see below	default values to be used if not specified in execution_control elements
execution_control	see below	execution control values for a given time period

Execution_control_defaults¶

The execution_control_defaults element has the following attributes.

Attribute Names	Attribute Type	Attribute Values
init_dt	time	time value(,unit)
max_dt	time	time value(,unit)
reduction_factor	exponential	factor for reducing time step
increase_factor	exponential	factor for increasing time step
mode	string	`steady, transient`
method	string	`bdf1, picard`

Execution_control¶

The execution_control element has the following attributes.

Attribute Names	Attribute Type	Attribute Values
start	time	time value(,unit) (start time for this time period)
end	time	time value(,unit) (stop time for this time period)
max_cycles	integer	max cycles to use for structured
init_dt	time	time value(,unit)
max_dt	time	time value(,unit)
reduction_factor	exponential	factor for reducing time step
increase_factor	exponential	factor for increasing time step
mode	string	`steady, transient`
method	string	`bdf1, picard`

Each execution_control is required to define a start time. The final control period must define an end time. It is assumed that the start time of the next control period is the end time of the previous period. Therefore, it is not required that each execution_control element have an end time defined.

The attribute max_cycles is only valid for transient and transient with static flow execution modes.

The execution_control section also provides the elements comments and verbosity. Users may provide any text within the comment element to annotate this section. verbosity takes the attribute level=`` extreme | high | medium | low | none``. This triggers increasing levels of reporting from inside Amanzi. For debugging purposes use the level extreme.

Restarting a simulation is available using the restart element. The text given for the restart element is the name of the Amanzi checkpoint file to be read in and initialized from.

Here is an overall example for the execution_control element.

<execution_controls>
  <execution_control_defaults init_dt="3.168E-08" max_dt="0.01" reduction_factor="0.8"
                              increase_factor="1.25" mode="transient" method="bdf1"/>
  <execution_control start="0.0 y" end="1956.0 y" init_dt="1 d" max_dt="500.0 y"
                     reduction_factor="0.8" mode="steady" />
  <execution_control start="1956.0 y" end="3000.0 y" init_dt="1 s" max_dt="10.0 y"
                     reduction_factor="0.8" mode="transient" />
</execution_controls>

Numerical Controls¶

This section allows the user to define control parameters associated with the underlying numerical implementation. The list of available options is lengthy. However, none are required for a valid input file. The numerical_controls section is divided up into the subsections: common_controls, unstructured_controls, and structured_controls.

Common_controls¶

The section is currently empty. However, in future versions controls that are common between the unstructured and structured executions will be moved to this section and given common terminology.

Unstructured_controls¶

The unstructured_controls sections is divided in the subsections: unstr_steady-state_controls, unstr_transient_controls, unstr_linear_solver, unstr_nonlinear_solver, unstr_flow_controls, unstr_transport_controls, and unstr_chemistry_controls. The list of available options is as follows:

<unstructured_controls>

  <unstr_flow_controls>
    <discretization_method> fv-default | fv-monotone | fv-multi_point_flux_approximation |
                            fv-extended_to_boundary_edges | mfd-default | mfd-optimized_for_sparsity |
                            mfd-support_operator | mfd-optimized_for_monotonicity |
                            mfd-two_point_flux_approximation </discretization_method>
    <rel_perm_method> upwind-darcy_velocity (default) | upwind-gravity | upwind-amanzi |
                      other-arithmetic_average | other-harmonic_average </rel_perm_method>
    <preconditioning_strategy> diffusion_operator | linearized_operator (default) </preconditioning_strategy>
    <atmospheric_pressure> exp </atmospheric_pressure>
  </unstr_flow_controls>

  <unstr_transport_controls>
    <algorithm> explicit first-order (default) | explicit second-order | implicit upwind </algorithm>
    <sub_cycling> on (defulat) | off </sub_cycling>
    <cfl> exp </cfl>
  </unstr_transport_controls>

  <unstr_chemistry_controls>
    <process_model> implicit operator split | none </process_model>

    <!-- Amanzi native chemistry -->
    <activity_model> unit (default) | debye-huckel </activity_model>
    <tolerance> exp </tolerance> <!-- default: 100 -->
    <maximum_newton_iterations> int </maximum_newton_iterations> <!-- default: 1e-12 -->
    <auxiliary_data> pH </auxiliary_data>

    <!-- Pflotran chemistry -->
    <activity_coefficients> timestep (default) | off </activity_coefficients>
    <max_relative_change_tolerance> exp </max_relative_change_tolerance> <!-- suggested 1.0e-16 -->
    <max_residual_tolerance> exp </max_residual_tolerance> <!-- suggested 1.0e-16 -->
    <log_formulation> on (default) | off </log_formulation>
  </unstr_chemistry_controls>

  <unstr_steady-state_controls>
    <min_iterations> int </min_iterations>
    <max_iterations> int </max_iterations>
    <limit_iterations> int </limit_iterations>
    <nonlinear_tolerance> exp </nonlinear_tolerance>
    <error_control_options> pressure (default) | residual </error_control_options>
    <nonlinear_iteration_damping_factor> exp </nonlinear_iteration_damping_factor>
    <max_preconditioner_lag_iterations> int </max_preconditioner_lag_iterations>
    <max_divergent_iterations> int </max_divergent_iterations>
    <nonlinear_iteration_divergence_factor> exp </nonlinear_iteration_divergence_factor>
    <restart_tolerance_relaxation_factor> exp </restart_tolerance_relaxation_factor>
    <restart_tolerance_relaxation_factor_damping> exp </restart_tolerance_relaxation_factor_damping>
    <preconditioner> hypre_amg (default) | trilinos_ml | block_ilu </preconditioner>
    <nonlinear_iteration_initial_guess_extrapolation_order> int </nonlinear_iteration_initial_guess_extrapolation_order>
    <unstr_initialization>
      <!-- NOTE: including an empty section here turns intialization on with default values
           To deactive intialization, remove section completely -->
      <clipping_saturation> exp </clipping_saturation>
      <clipping_pressure> exp </clipping_pressure>
      <method> picard (default) | darcy_solver </method>
      <preconditioner> hypre_amg (default) | trilinos_ml | block_ilu </preconditioner>
      <linear_solver>aztec00 | aztecoo | AztecOO</linear_solver>
      <error_control_options> pressure (default) | residual </error_control_options>
      <convergence_tolerance> exp </convergence_tolerance>
      <max_iterations> int </max_iterations>
    </unstr_initialization>
  </unstr_steady-state_controls>

  <unstr_transient_controls>
    <min_iterations> int </min_iterations>
    <max_iterations> int </max_iterations>
    <limit_iterations> int </limit_iterations>
    <nonlinear_tolerance> exp </nonlinear_tolerance>
    <nonlinear_iteration_damping_factor> exp </nonlinear_iteration_damping_factor>
    <max_preconditioner_lag_iterations> int </max_preconditioner_lag_iterations>
    <max_divergent_iterations> int </max_divergent_iterations>
    <nonlinear_iteration_divergence_factor> exp </nonlinear_iteration_divergence_factor>
    <restart_tolerance_relaxation_factor> exp </restart_tolerance_relaxation_factor>
    <restart_tolerance_relaxation_factor_damping> exp </restart_tolerance_relaxation_factor_damping>
    <error_control_options> pressure,residual (default) </error_control_options>
    <preconditioner> hypre_amg (default) | trilinos_ml | block_ilu </preconditioner>
    <initialize_with_darcy> true | false (default) </initialize_with_darcy>
    <nonlinear_iteration_initial_guess_extrapolation_order>int</nonlinear_iteration_initial_guess_extrapolation_order>
  </unstr_transient_controls>

  <unstr_linear_solver>
    <method> gmres (default) | pcg </method>
    <max_iterations>int </max_iterations>
    <tolerance> exp </tolerance>
    <preconditioner> hypre_amg (default) | trilinos_ml | block_ilu </preconditioner>
  </unstr_linear_solver>

  <unstr_nonlinear_solver name="nka | newton | jfnk | newton_picard" >
    <modify_correction> true | false (default) </modify_correction>
    <update_upwind_frequency> every_timestep (default) | every_nonlinear_iteration </update_upwind_frequency>
  </unstr_nonlinear_solver>

  <unstr_preconditioners>
    <hypre_amg>
      <hypre_cycle_applications> int </hypre_cycle_applications> <!-- default: 5 suggested range: 1-5 -->
      <hypre_smoother_sweeps> int </hypre_smoother_sweeps> <!-- default: 3 suggested range: 1-5 -->
      <hypre_tolerance> exp </hypre_tolerance> <!-- default: 0.0 suggested range: 0.0-0.1 -->
      <hypre_strong_threshold> exp </hypre_strong_threshold> <!-- default: 0.5 suggested range: 0.2-0.8 -->
    </hypre_amg>
    <trilinos_ml>
      <trilinos_cycle_applications> int </trilinos_cycle_applications>
      <trilinos_smoother_sweeps> int </trilinos_smoother_sweeps>
      <trilinos_threshold> exp </trilinos_threshold>
      <trilinos_smoother_type> jacobi (default) | gauss_seidel | ilu </trilinos_smoother_type>
    </trilinos_ml>
    <block_ilu>
      <ilu_overlap> int </ilu_overlap>
      <ilu_relax> exp </ilu_relax>
      <ilu_rel_threshold> exp </ilu_rel_threshold>
      <ilu_abs_threshold> exp </ilu_abs_threshold>
      <ilu_level_of_fill> int </ilu_level_of_fill>
    </block_ilu>
  </unstr_preconditioners>
</unstructured_controls>

Here is an overall example for the unstructured_controls element.

<unstructured_controls>
  <comments>Numerical controls comments here</comments>
  <unstr_steady-state_controls>
    <comments>Note that this section contained data on timesteps, which was moved into the execution control section.</comments>
    <min_iterations>10</min_iterations>
    <max_iterations>15</max_iterations>
    <max_preconditioner_lag_iterations>30</max_preconditioner_lag_iterations>
    <nonlinear_tolerance>1.0e-5</nonlinear_tolerance>
  </unstr_steady-state_controls>
  <unstr_transient_controls>
    <comments>Proposed comments section.</comments>
    <bdf1_integration_method min_iterations="10" max_iterations="15" max_preconditioner_lag_iterations="5" />
  </unstr_transient_controls>
  <unstr_linear_solver>
    <comments>Proposed comment section.</comments>
    <method>gmres</method>
    <max_iterations>20</max_iterations>
    <tolerance>1.0e-18</tolerance>
    <preconditioner> trilinos_ml | hypre_amg | block_ilu </preconditioner>
  </unstr_linear_solver>
</unstructured_controls>

Structured_controls¶

The structured_controls sections is divided in the subsections: str_steady-state_controls, str_transient_controls, str_amr_controls, <petsc_options_file>, and max_n_subcycle_transport. The list of available options is as follows:

<structured_controls>

  <comments>Numerical controls comments here</comments>

  <petsc_options_file> String </petsc_options_file>
  <str_steady-state_controls>
    <max_pseudo_time> Exponential </max_pseudo_time>
    <limit_iterations> Integer </limit_iterations>
    <min_iterations> Integer </min_iterations>
    <min_iterations_2> Integer </min_iterations_2>
    <time_step_increase_factor> Exponential </time_step_increase_factor>
    <time_step_increase_factor_2> Exponential </time_step_increase_factor_2>
    <max_consecutive_failures_1> Integer </max_consecutive_failures_1>
    <time_step_retry_factor_1> Exponential </time_step_retry_factor_1>
    <max_consecutive_failures_2> Integer </max_consecutive_failures_2>
    <time_step_retry_factor_2> Exponential </time_step_retry_factor_2>
    <time_step_retry_factor_f> Exponential </time_step_retry_factor_f>
    <max_num_consecutive_success> Integer </max_num_consecutive_success>
    <extra_time_step_increase_factor> Exponential </extra_time_step_increase_factor>
    <abort_on_psuedo_timestep_failure> true | false </abort_on_psuedo_timestep_failure>
    <limit_function_evals> Integer </limit_function_evals>
    <do_grid_sequence> true | false </do_grid_sequence>
    <grid_sequence_new_level_dt_factor>
      <dt_factor> Exponential </dt_factor> <!-- one element for each AMR level -->
    </grid_sequence_new_level_dt_factor>
  </str_steady-state_controls>


  <str_transient_controls>
    <max_ls_iterations> Integer </max_ls_iterations>
    <ls_reduction_factor> Exponential </ls_reduction_factor>
    <min_ls_factor> Exponential </min_ls_factor>
    <ls_acceptance_factor> Exponential </ls_acceptance_factor>
    <monitor_line_search> Integer </monitor_line_search>
    <monitor_linear_solve> Integer </monitor_linear_solve>
    <perturbation_scale_for_J> Exponential </perturbation_scale_for_J>
    <use_dense_Jacobian> true | false </use_dense_Jacobian>
    <upwind_krel> true | false </upwind_krel>
    <pressure_maxorder> Integer </pressure_maxorder>
    <scale_solution_before_solve> true | false </scale_solution_before_solve>
    <semi_analytic_J> true | false </semi_analytic_J>
    <cfl> Exponential </cfl>
  </str_transient_controls>

  <str_transient_controls>
    <amr_levels> Integer </amr_levels>
    <refinement_ratio>Integer Integer</refinement_ratio> <!-- amr_levels-1 number of integers should be listed-->
    <do_amr_cubcycling> true | false </do_amr_cubcycling>
    <regrid_interval>Integer Integer</regrid_interval> <!-- amr_levels number of integers should be listed-->
    <blocking_factor>Integer Integer</blocking_factor> <!-- amr_levels number of integers should be listed-->
    <number_error_buffer_cells>Integer Integer</number_error_buffer_cells> <!-- amr_levels-1 number of integers should be listed-->
    <max_grid_size>Integer Integer</max_grid_size> <!-- amr_levels number of integers should be listed-->
    <refinement_indicators>
      <field_name> String </field_name>
      <regions> String </regions>
      <max_refinement_level> Integer </max_refinement_level>
      <start_time> Exponential </start_time>
      <end_time> Exponential </end_time>
      <!-- user may specify exactly 1 of the following -->
      <value_greater> Exponential </value_greater>
      <inside_region> true | false </inside_region>
      <value_less> Exponential </value_less>
      <adjacent_difference_greater> Exponential </adjacent_difference_greater>
      <inside_region> true | false </inside_region>
    </refinement_indicators>
  </str_transient_controls>

  <max_n_subcycle_transport> Integer </max_n_subcycle_transport>
</structured_controls>

Mesh¶

A mesh must be defined for the simulation to be conducted on. The mesh can be structured or unstructured. Structured meshes are always internally generated while unstructured meshes may be generated internally or imported from an existing Exodus II file. Generated meshes in both frameworks are always regular uniformly spaced meshes.

Mesh - Generate (Structured)¶

The mesh section takes a dimension element which indicates if the mesh is 2D or 3D. A 2D mesh can be given in 3D space with a third coordinate of 0. If a 2D mesh is specified this impacts other aspects of the input file. It is up to the user to ensure consistency within the input file. Other effected parts of the input file include region definitions and initial conditions which use coordinates, the material property permeability which must be specified using the correct subset of x, y, and z coordinates, and the initial condition velocity which also requires the correct subset of x, y, and z coordinates.

This section also takes an element indicating how the mesh is to be internally generated. The generate element specifies the details about the number of cells in each direction and the low and high coordinates of the bounding box. It should be noted that in order to accommodate mesh refinement, the number of cells in each direction must be even.

Finally, as in other sections, a comments element is provide to include any comments or documentation the user wishes.

Here is an example specification for internally generated mesh element for structured.

<mesh>
  <comments>3D block</comments>
  <dimension>3</dimension>
  <generate>
    <number_of_cells nx="400"  ny="200"  nz="10"/>
    <box  low_coordinates="0.0,0.0,0.0" high_coordinates="200.0,200.0,1.0"/>
  </generate>
</mesh>

Mesh - Generate (Unstructured)¶

The unstructured portion of Amanzi can utilize different mesh frameworks. Therefore the framework is specified as an attribute to the mesh element. The available options are: mstk, moab, and simple. If no framework is specified, the default mstk is used.

The mesh section takes a dimension element which indicates if the mesh is 2D or 3D. A 2D mesh can be given in 3D space with a third coordinate of 0. If a 2D mesh is specified this impacts other aspects of the input file. It is up to the user to ensure consistency within the input file. Other effected parts of the input file include region definitions and initial conditions which use coordinates, the material property permeability which must be specified using the correct subset of x, y, and z coordinates, and the initial condition velocity which also requires the correct subset of x, y, and z coordinates.

This section also takes an element indicating how the mesh is to be internally generated. The generate element specifies the details about the number of cells in each direction and the low and high coordinates of the bounding box.

Finally, as in other sections, a comments element is provide to include any comments or documentation the user wishes.

The following is an example specification for a generated unstructured mesh.

<mesh framework="mstk">
  <comments>Pseudo 2D</comments>
  <dimension>3</dimension>
  <generate>
    <number_of_cells nx="432"  ny="1"  nz="256"/>
    <box low_coordinates="0.0,0.0,0.0" high_coordinates="216.0,1.0,107.52"/>
  </generate>
</mesh>

Mesh - Read (Unstructured)¶

The unstructured mode of Amanzi can utilize different mesh frameworks. Therefore the framework is specified as an attribute to the mesh element. The available options are: mstk, moab, and simple. If no framework is specified, the default mstk is used.

The mesh section takes a dimension element which indicates if the mesh is 2D or 3D. A 2D mesh can be given in 3D space with a third coordinate of 0. If a 2D mesh is specified this impacts other aspects of the input file. It is up to the user to ensure consistency within the input file. Other effected parts of the input file include region definitions and initial conditions which use coordinates, the material property permeability which must be specified using the correct subset of x, y, and z coordinates, and the initial condition velocity which also requires the correct subset of x, y, and z coordinates.

The unstructured mode of Amanzi can read meshes in the Exodus II format. The read element contains the subelements file, format, and verify for specifying the mesh file format (currently only Exodus II) and the mesh file name (relative path allowed). Any regions or attributes specified in the mesh file will also be read. These names of the regions and attributes can be utilized in appropriate sections of the input file. The subelement verify turns on or off checks performed on the mesh when it is read it. The mesh verification takes time and is only recommended for debugging meshes on first use.

Finally, as in other sections, a comments element is provide to include any comments or documentation the user wishes.

Finally, an example of reading an unstructured mesh from a file is given below.

<mesh framework="mstk">
  <comments>Read from Exodus II</comments>
  <dimension>3</dimension>
  <read>
    <file>dvz.exo</file>
    <format>exodus ii</format>
    <verify>true</verify>
  </read>
</mesh>

Regions¶

Regions are geometrical constructs used in Amanzi to define subsets of the computational domain in order to specify the problem to be solved, and the output desired. Regions are commonly used to specify material properties, boundary conditions and observation domains. Regions may represent zero-, one-, two- or three-dimensional subsets of physical space. For a three-dimensional problem, the simulation domain will be a three-dimensional region bounded by a set of two-dimensional regions. If the simulation domain is N-dimensional, the boundary conditions must be specified over a set of regions are (N-1)-dimensional.

Amanzi automatically defines the special region labeled “All”, which is the entire simulation domain. Under the “Structured” option, Amanzi also automatically defines regions for the coordinate-aligned planes that bound the domain, using the following labels: “XLOBC”, “XHIBC”, “YLOBC”, “YHIBC”, “ZLOBC”, “ZHIBC”

The regions block is required. Within the region block no regions are required to be defined. The optional elements valid for both structured and unstructured include region, box, point, plane, and logical. As in other sections there is also an options comments element.

The elements box, point, and plane allow for in-line description of regions. The region element uses a subelement to either define a box or plane region or specify a region file. Below are further descriptions of these elements.

Additional regions valid only for unstructured are polygonal_surface. Additional regions valid only for structured include polygon and ellipse in 2D and rotated_polygon and swept_polygon in 3D.

Each region definition requires a name attribute. These names must be unique to avoid confusion when other sections refer to the regions.

Box¶

A box region region is defined by a low corner coordinates and high corner coordinates. Box regions can be degenerate in one or more directions.

<box name="MyBox" low_coordinates="x_low,y_low,z_low"
                  high_coordinates="x_high,y_high,z_high"/>

Point¶

A point region is defined by a point coordinates.

<point name="Well" coordinate="x,y,z" />

Plane¶

A plane region is defined by a point on the plane and the normal direction of the plane.

<plane name="plane name" location="x,y,z" normal="nx,ny,nz" tolerance="optional exp"/>

The attribute tolerance is optional. This value prescribes an absolute tolerance for determining the cell face centroids that lie on the defined plane.

Labeled Set¶

A labeled set region is a predefined set of mesh entities defined in the Exodus II mesh file. This type of region is useful when applying boundary conditions on an irregular surface that has been tagged in the external mesh generator. Please note that both the format and entity attribute values are case sensitive. Also not that the attribute label refers to the name of the region used in the mesh file. Currently the label/name needs to be an integer value. Also the region names in the mesh file should be unique to avoid errors and confusion as to which region is being referred to.

<region name="region name">
  <region_file label="integer label" name="filename" type="labeled set"
               format="exodus ii" entity=["cell"|"face"] />
</region>

Color function¶

A color function region defines a region based on a specified integer color in a structured color function file. The color values may be specified at the nodes or cells of the color function grid. A computational cell is assigned the color of the data grid cell containing its cell centroid or the data grid nearest its cell-centroid. Computational cell sets are then build from all cells with the specified color value. In order to avoid gaps and overlaps in specifying materials, it is strongly recommended that regions be defined using a single color function file. At this time, Exodus II is the only file format available. Please note that both the format and entity attribute values are case sensitive.

<region name="region name">
  <region_file label="integer label" name="filename" type="color"
               format="exodus ii"  entity=["cell"|"face"]/>
</region>

Logical¶

Logical regions are compound regions formed from other primitive type regions using boolean operations. Supported operators are union, intersection, subtraction and complement. This region type is only valid for the unstructured algorithm.

<logical name="logical name">
  <operation>union|intersection|subtraction|complement</operation>
  <region_list>region1, region2, region3<region_list/>
</logical>

Polygonal_Surface (unstructured only)¶

A polygonal_surface region is used to define a bounded planar region and is specified by the number of points and a list of points. The points must be listed in order and this ordering is maintained during input translation. This region type is only valid for the unstructured algorithm.

<polygonal_surface name="polygon name" num_points="3" tolerance="optional exp">
  <point>X1, Y1, Z1</point>
  <point>X2, Y2, Z2</point>
  <point>X3, Y3, Z3</point>
  <point>X4, Y4, Z4</point>
</polygonal_surface>

The attribute tolerance is optional. This value prescribes an absolute tolerance for determining the cell face centroids that lie on the defined plane.

Polygon (structured 2D only)¶

A polygon region is used to define a bounded planar region and is specified by the number of points and a list of points. The points must be listed in order and this ordering is maintained during input translation. This region type is only valid for the structured algorithm in 2D.

<polygon name="polygon name" num_points="3">
  <point> (X1, Y1) </point>
  <point> (X2, Y2) </point>
  <point> (X3, Y3) </point>
</polygon>

Ellipse (structured 2D only)¶

An ellipse region is used to define a bounded planar region and is specified by a center and X and Y radii. This region type is only valid for the structured algorithm in 2D.

<ellipse name="polygon name" num_points="3">
  <center> (X, Y) </center>
  <radius> (radiusX, radiusY) </radius>
</ellipse>

Rotated Polygon (structured 3D only)¶

A rotated_polygon region is defined by a list of points defining the polygon, the plane in which the points exist, the axis about which to rotate the polygon, and a reference point for the rotation axis. The points listed for the polygon must be in order and the ordering will be maintained during input translation. This region type is only valid for the structured algorithm in 3D.

<rotated_polygon name="rotated_polygon name">
  <vertex> (X, Y, Z) </vertex>
  <vertex> (X, Y, Z) </vertex>
  <vertex> (X, Y, Z) </vertex>
  <xyz_plane> (XY | YZ | XZ) </xyz_plane>
  <axis> (X | Y | Z) </axis>
  <reference_point> (X, Y) </reference_point>
</rotated_polygon>

Swept Polygon (structured 3D only)¶

A swept_polygon region is defined by a list of points defining the polygon, the plane in which the points exist, the extents (min,max) to sweep the polygon normal to the plane. The points listed for the polygon must be in order and the ordering will be maintained during input translation. This region type is only valid for the structured algorithm in 3D.

<swept_polygon name="swept_polygon name">
  <vertex> (X, Y, Z) </vertex>
  <vertex> (X, Y, Z) </vertex>
  <vertex> (X, Y, Z) </vertex>
  <xyz_plane> (XY | YZ | XZ) </xyz_plane>
  <extent_min> exponential </extent_min>
  <extent_max> exponential </extent_max>
</swept_polygon>

Geochemistry¶

The geochemistry section allows for geochemical constraints to be named and defined. These named constraints are referred to in the initial_conditions, boundary_conditions, and sources sections.

Note, at this time the geochemistry constraints must be named and defined in the external chemistry engine input file. This chemistry input file must be provided by the user. The capability to create the chemistry input file based on information provided within the XML input file is currently under development.

The geochemistry section has the subelements comments, verbosity, and an unbounded number of constraint elements. The verbosity element specifies the verbosity level to be used by the chemistry engine. The current options are: silent, terse, verbose, warnings, and errors.

Currently, each named constraint must correspond to a constraint with matching name in the external chemistry engine input file. With the XML input file, the constraint element takes an attribute name. This name must match the name of a constraint within the chemistry input file. In addition, the use may include the constraint information as subelements to the constraint element for information purposes. The constraint element accepts three version of a primary subelement. The primary element describes the constraint on a primary specie, mineral, or gas.

For each type of primary, the primary element takes the attributes name, type, and value. The name should match a primary listed in the phases section. The type can be: free_ion, pH, total, mineral, gas, total+sorbed, or charge. Note, for a non-reacting primary (i.e. tracer or solute), only the type total is valid. If the type selected is mineral, an additional attribute mineral giving the mineral name is expected. If the type selected is gas, an additional attribute gas giving the gas name is expected. Again, the names given should match names specified in the phases section.

<geochemistry>
  <verbosity>silent | terse | verbose | warnings | errors</verbosity>
  <constraints> <!-- REQUIRED -->
    <constraint name="string"> <!-- REQUIRED -->
      <primary name="primary_name_string"  initial_guess="exp"   type="free_ion | pH | total | total+sorbed | charge"/>
      <primary name="nonreactive_primary"  initial_guess="exp"   type="total"/>
      <primary name="primary_name_string"  initial_guess="exp"   type="mineral" mineral="mineral_name"/>
      <primary name="primary_name_string"  initial_guess="exp"   type="gas" gas = "gas_name"/>
      <mineral name="mineral_name_string"  volume_fraction="exp" surface_area ="exp"/>
    </constraint>
  </constraints>
</geochemistry>

Materials¶

The materials section allows for 1 or more material to be defined. Each material element requires an attribute name to distinguish the material definitions.

The material in this context is meant to represent the media through which fluid phases are transported. In the literature, this is also referred to as the “soil”, “rock”, “matrix”, etc. Properties of the material must be specified over the entire simulation domain, and is carried out using the Region constructs defined above. For example, a single material may be defined over the “All” region (see above), or a set of materials can be defined over subsets of the domain via user-defined regions. If multiple regions are used for this purpose, they should be disjoint, but should collectively tile the entire domain. Each material requires a label and the following set of physical properties using the supported models described below.

While many material properties are available for the user to define, the minimum requirements for a valid material definition are specifying the assigned_regions, either permeability or hydraulic_conductivity, and the porosity. However, if a capillary pressure model or relative permeability model is chosen (other than none), the associated parameters must also be provided. Likewise, all model specific parameters must be provided for the chosen dispersion tensor model.

Assigned_regions¶

The assigned_regions element list the regions to which the following material properties are to be assigned. If only 1 material exists, the All region should be used. If the material properties are to be assigned to multiple regions, provide a comma separated list of the region names. Leading and trailing white space will be trimmed. Also, spaces within the region names will be preserved.

<assigned_regions>Comma seperated list of Regions</assigned_regions>

Mechanical_properties¶

This element collects a series of mechanical properties as subelements. As mentioned above, the only required subelement is porosity.

For dispersion_tensor several models are available. The model is specified using the type attribute and additional attributes are used to specify the properties of the given model. The available dispersion models are described in the following table.

Dispersion Model	Attribute Names	Attribute Values
uniform_isotropic	alpha_l alpha_t	Exponential value Exponential value
burnett_frind	alpha_l alpha_th alpha_tv	Exponential value Exponential value Exponential value
lichtner_kelkar_robinson	alpha_lh alpha_tv alpha_th alpha_tv	Exponential value Exponential value Exponential value Exponential value

<mechanical_properties>
  <porosity value="Exponential"/>
  <particle_density value="Exponential"/>
  <specific_storage value="Exponential"/>
  <specific_yield value="Exponential"/>
  <dispersion_tensor type="uniform_isotropic" alpha_l="Exponential" alpha_t="Exponential"/>
  <tortuosity value="Exponential"/>
</mechanical_properties>

Permeability¶

For each material either the permeability or the hydraulic_conductivity must be specified, but not both. If specifying the permeability either a single value for each direction can be given for the entire material or the permeability values can be read from a file by specifying the attribute type as “file”. The attribute attribute gives the name of the attribute with an Exodus II mesh file to be read. Finally the file name is specified using the attribute filename.

<permeability x="Exponential" y="Exponential" z="Exponential"/>
<permeability filename="file name" type="file" attribute="attribute name"/>

Hydraulic_conductivity¶

As noted above, either the permeability or hydraulic_conductivity must be specified for each material, but not both. The values for each direction are listed as attributes. Currently file read has not yet been implemented.

<hydraulic_conductivity x="Exponential" y="Exponential" z="Exponential"/>

Cap_pressure¶

Capillary pressure can be specified using the element cap_pressure. The attribute model specifies whether the van Genuchten or Brooks-Corey model is to be used. The subelement parameters lists the model specific parameters. Note, for both models a smoothing interval can be specified but is optional. Also, if not specifying capillary pressure this element can be skipped or the value of model set to “none”.

<cap_pressure model="van_genuchten | brooks_corey | none">
  <!-- for van_Genuchten -->
  <parameters m="Exponential" alpha="Exponential" sr="Exponential"
              optional_krel_smoothing_interval="Exponential"/>
  <!-- for Brooks_Corey -->
  <parameters lambda="Exponential" alpha="Exponential" sr="Exponential"
              optional_krel_smoothing_interval="Exponential"/>
</cap_pressure>

Rel_perm¶

Relative permeability can be specified using the element rel_perm. The attribute model specifies whether the Mualam or Burdine model is to be used. The subelement exp lists the model specific parameters for Burdine. Also, if not specifying capillary pressure this element can be skipped or the value of model set to “none”.

<rel_perm model="mualem | burdine | none">
  <!-- Burdine only -->
  <exp value="Exponential"/>
</rel_perm>

Sorption_isotherms¶

Kd models can be specified for 1 or more primaries using the sorption_isotherms element. Note for the Kd model to be active the chemistry state under process_kernels must be “on” and an engine must be specified. Also, all primaries must be listed for each material. Three Kd models are available. All model parameters for the given model must be present.

<sorption_isotherms>
  <primary name="Name of Primary" >
    <kd_model model="linear" kd = "Exponential" />
  </primary>
  <primary name="Name of Primary" >
    <kd_model model="langmuir" kd="Exponential" b="Exponential"/>
  </primary>
  <primary name="Name of Primary" >
    <kd_model model="freundlich" kd="Exponential" n="Exponential" />
  </primary>
</sorption_isotherms>

Minerals¶

Mineral concentrations are specified using the volume fraction and specific surface area attributes volume_fraction and specific_surface_area respectively in the minerals block

<minerals>
  <mineral name="Calcite" volume_fraction="0.1" specific_surface_area"1.0"/>
</minerals>

Ion_exchange¶

Ion exchange reactions are specified in the ion_exchange block. Cations active in the reaction are grouped under the subelement cations. The attribute cec specifies the cation exchange capacity for the reaction. Each cation is listed in a cation subelement with the attributes name and value to specify the cation name and the associated selectivity coefficient.

<ion_exchange>
  <cations cec="750.0">
    <cation name="Ca++" value="0.2953"/>
    <cation name="Mg++" value="0.1666"/>
    <cation name="Na+" value="1.0"/>
  </cations>
</ion_exchange>

Surface_complexation¶

Surface complexation reactions are specified in the surface_complexation block. Individual reactions are specified using the site block. It has the attributes density and name to specify the site density and the name of the site. Note, the site name must match a surface complexation site in the database file without any leading characters, such as >. The subelement complexes provides a comma separated list of complexes. Again, the names of the complexes must match names within the datafile without any leading characters.

<surface_complexation>
  <site density="1.908e-3" name="FeOH_s">
    <complexes>FeOHZn+_s, FeOH2+_s, FeO-_s</complexes>
  </site>
  <site density="7.6355e-2" name="FeOH_w">
    <complexes>FeOHZn+_w, FeO-_w, FeOH2+_w</complexes>
  </site>
</surface_complexation>

An example materials element would look like

<materials>
  <material name="Facies_1">
    <comments>Material corresponds to region facies1</comments>
    <assigned_regions>Between_Planes_1_and_2</assigned_regions>
    <mechanical_properties>
      <porosity value="0.4082"/>
      <particle_density value="2720.0"/>
    </mechanical_properties>
    <permeability x="1.9976E-12" y="1.9976E-12" z="1.9976E-13"/>
    <cap_pressure model="van_genuchten">
      <parameters m="0.2294" alpha="1.9467E-04" sr="0.0"/>
    </cap_pressure>
    <rel_perm model="mualem"/>
  </material>
</materials>

Process Kernels¶

Amanzi current employees three process kernels that need to be defined in the input file (1) flow, (2) transport, and (3) chemistry. The process_kernels section allows the user to define which kernels are to be used during the section and select high level features of those kernels.

Flow¶

Currently three scenarios are available for calculated the flow field. “richards” is a single phase, variably saturated flow assuming constant gas pressure. “saturated” is a single phase, fully saturated flow. “constant” is equivalent to the flow model of single phase (saturated) with the time integration mode of transient with static flow in the version 1.2.1 input specification. This flow model indicates that the flow field is static so no flow solver is called during time stepping. During initialization the flow field is set in one of two ways: (1) A constant Darcy velocity is specified in the initial condition; (2) Boundary conditions for the flow (e.g., pressure), along with the initial condition for the pressure field are used to solve for the Darcy velocity.

<flow state = "on | off"
      model = "richards | saturated | constant" />

Transport¶

For “transport” a “state” must be specified.

<transport state = "on | off" />

Chemistry¶

For “chemistry” a combination of “state”, “engine”, “input_filename”, and “database” must be specified. If “state” is “off” then “engine” is set to “none”. Otherwise the “engine” model must be specified. If PFloTran is specified as the chemistry engine, the user must specify a PFloTran database filename in the “database” attribute. Also, if PFloTran is the chemistry engine, the user may provide a PFloTran input file using the attribute input_filename or omit the attribute. If the attribute is omitted, Amanzi will automatically generate the PFloTran input file using information in the XML input file. It should be noted the automatically generated file is written to a file using the same name as the XML input file, but with the extension .in. If such a file exists in the run directory, Amanzi will not overwrite the file and just use the existing file.

<chemistry state = "on | off"
           engine = "amanzi | pflotran | none"
           input_filename = "string"
           database = "string" />

An example process_kernels is as follows:

<process_kernels>
  <comments>This is a proposed comment field for process_kernels</comments>
  <flow state = "on" model = "richards"/>
  <transport state = "on" algorithm = "explicit first-order" sub_cycling = "on"/>
  <chemistry state = "off" engine="none"/>
</process_kernels>

Phases¶

The phases section is used to specify components of each of the phases that are mobile, and species that are contained within them. For each phase, the list identifies the set of all independent variables that are to be stored on each discrete mesh cell.

The terminology for flow in porous media can be somewhat ambiguous between the multiphase and groundwater communities, particularly in regards to “components”, “solutes”, “primaries/secondaries”, and “chemicals”. Since Amanzi is designed to handle a wide variety of problems, we must settle on a nomenclature for our use here. In the general problem, multiple “phases” may coexist in the domain (e.g. gaseous, aqueous/liquid, etc), and each is comprised of a number of “components” (section 2.2). In turn, each component may carry a number of “primaries” and “secondaries” and some of these may participate in chemical reactions. As a result of reactions, a chemical source or sink term may appear for the primaries involved in the reaction, including primaries in other mobile phases or in the material matrix. Additionally, certain reactions such as precipitation may affect the flow properties of the material itself during the simulation, and some might affect the properties of the fluid (e.g. brines affect the liquid density). While Amanzi does not currently support chemical reactions and thermal processes, the specification here allows for the existence of the necessary data structures and input data framework. Note that if primary concentrations are significant, the system may be better modeled with that primary treated as a separate component. Clearly, these definitions are highly problem-dependent, so Amanzi provide a generalized interface to accommodate a variety of scenarios.

Currently in Amanzi, primaries are transported in the various phase components, and are treated in “complexes”. Each complex is typically in chemical equilibrium with itself and does not undergo phase change. Under these conditions, knowledge of the local concentration of the “basis” or “primary” species (the terms are used here interchangeably) in a chemical complex is sufficient to determine the concentrations of all related secondary species in the phase. Each basis species has a total component concentration and a free ion concentration. The total component concentration for each basis species is a sum of the free ion concentrations in the phase components and its stoichiometric contribution to all secondary species. Amanzi splits the total component concentration into a set of totals for each of the transported phase components, and a total sorbed concentration. Given the free ion concentration of each basis species (and if there is more than one phase, a specification of the thermodynamic relationships that determine the partitioning between phase components (if mass transfer is allowed - not in current Amanzi), we can reconstruct the concentration of the primary and secondary species in each phase. As a result only the basis species are maintained in the state data structures for each phases component.

In addition to primaries in the transported phases, there may be various immobile chemical constituents within the porous media (material) matrix, such as “minerals” and “surface complexes”. Bookkeeping for these constituents is managed in Amanzi data structures by generalizing the “primary” concept - a slot in the state is allocated for each of these immobile species, but their concentrations are not included in the transport/flow components of the numerical integration. To allow selective transport of the various primaries, Amanzi uses the concept of primary groups. The aqueous primary concentrations are typically treated together as a group, for example, and often represent the only chemical constituents that are mobile. Thus, the current Amanzi will assume that any other groups specified in an Aqueous phase are immobile.

This section specifies the phases present and specific properties about those phases. The first grouping is by liquid_phase, solid_phase, and gas_phase.

Liquid_phase¶

The liquid_phase element is required to produce a valid input file. If primaries are being transported properties of the primaries in the current phase can be specified. If primaries are being reacted a list of secondary chemical is also specified.

<liquid_phase name = "water">
  <viscosity> Exponential </viscosity>
  <density> Exponential </density>
  <dissolved_components>
    <primaries>
      <primary coefficient_of_diffusion="Exponential" first_order_decay_constant="Exponential"> PrimaryName </primary>
    </primaries>
    <secondaries>
      <secondary>SecondaryName</secondary>
    </secondaries>
  </dissolved_components>
</liquid_phase>

Solid_phase¶

The solid_phase element allows the user to define a minerals element under which a series of mineral elements can be listed to specify any minerals present in the solid phase. The mineral elements contain the name of the mineral.

<solid_phase>
  <minerals>
    <mineral> MineralName </mineral>
  </minerals>
</solid_phase>

Gas_phase¶

The gas_phase element allows the user to define a gases element under which a series of gas elements can be listed to specify any gases present in the gas phase. The gas elements contain the name of the gas.

<gas_phase>
  <gases>
    <gas> GasName </gas>
  </gases>
</gas_phase>

An example phases element looks like the following.

<phases>
  <liquid_phase name = "water">
    <viscosity>1.002E-03</viscosity>
    <density>998.2</density>
    <dissolved_components>
      <primaries>
        <primary coefficient_of_diffusion="1.0e-9" first_order_decay_constant="1.0e-9">Tc-99</primary>
      </primaries>
    </dissolved_components>
  </liquid_phase>
</phases>

Initial Conditions¶

The “initial_conditions” section contains at least 1 and up to an unbounded number of “initial_condition” elements. Each “initial_condition” element defines a single initial condition that is applied to one or more region specified in the assigned_regions element. The initial condition can be applied to a liquid phase or solid phase using the appropriate subelement.

To specify a liquid phase the liquid_phase element is used. At least one liquid_component must be specified. In addition a geochemistry_component element can be specified. Under the liquid_component element an initial condition can be defined. Under the geochemistry_component element a geochemistry constraint is listed.

The initial conditions are defined using a specific elements. The element name indicates the type of condition and the attributes define the necessary information. Below is a table of the conditions available for the liquid phase and the attributes required to define them.

Initial Condition Type	Attributes	Value Type
uniform_pressure	name value	string double/time_constant/constant
linear_pressure	name value reference_coord gradient	string double/time_constant/constant coordinate coordinate
velocity	name x y (z)	string double/constant double/constant double/constant
uniform_saturation	name value	string double/time_constant/constant
linear_saturation	name value reference_coord gradient	string double/time_constant/constant coordinate coordinate

For the geochemistry_component, an unbounded number of constraint elements can be listed. Each constraint element has the attribute name. The name attribute refers to a geochemical constraint defined in the “geochemisty” section.

If in the process_kernels section the flow model is set to constant then the flow field is set in one of the following ways: (1) A constant Darcy velocity is specified in the initial condition (as above); (2) Boundary conditions for the flow (e.g., pressure), along with the initial condition for the pressure field are used to solve for the Darcy velocity.

An example initial_conditions element looks like the following.

<initial_conditions>
  <initial_condition name="Pressure and concentration for entire domain">
    <comments>Initial Conditions Comments</comments>
    <assigned_regions>All</assigned_regions>
    <liquid_phase name = "water">
      <liquid_component name = "water">
        <linear_pressure value = "101325" reference_coord ="(0.0,0.0,0.5)" gradient="(0.0,0.0,-9793.5192)"/>
      </liquid_component>
      <geochemistry_component>
        <constraint name = "initial"/>
      </geochemistry_component>
    </liquid_phase>
  </initial_condition>
</initial_conditions>

Boundary Conditions¶

Boundary conditions are defined in a similar manor to the initial conditions. Under the tag boundary_conditions and series of individual boundary_condition elements can be defined. Within each boundary_condition element the assigned_regions and liquid_phase elements must appear. The boundary condition can be applied to one or more region using a comma separated list of region names. Under the liquid_phase element the liquid_component element must be define. A geochemistry_component element may optionally be defined.

Under the liquid_component and geochemistry_component elements a time series of boundary conditions is defined using the boundary condition elements available in the table below. Each component element can only contain one type of boundary condition. Both elements also accept a name attribute to indicate the phase associated with the boundary condition.

Boundary Condition Type	Attributes	Value Type
inward_mass_flux inward_volumetric_flux outward_mass_flux outward_volumetric_flux	name start value function	string double/time_constant/constant double `linear \| uniform \| constant`
uniform_pressure	name start value function	string double/time_constant/constant double `uniform \| constant`
linear_pressure	name gradient_value reference_point reference_value	string coordinate coordinate double
hydrostatic	name start value function coordinate_system submodel	string double/time_constant/constant double `uniform \| constant` `absolute \| relative to mesh top` `no_flow_above_water_table \| none`
linear_hydrostatic	name gradient_value reference_point reference_water_table_height submodel	string coordinate coordinate double `no_flow_above_water_table \| none`
seepage_face (unstructured only)	name start inward_mass_flux function	string double/time_constant/constant double/time_constant/constant `linear \| uniform \| constant`
no_flow	name start function	string double/time_constant/constant `linear \| uniform \| constant`

For the geochemistry_component, an unbounded number of constraint elements may be listed. Each constraint has the attributes name, function, and start. The function option available is constant. The name should match a constraint defined in the “phases” section

An example boundary_conditions element looks like the following.

<boundary_conditions>
  <boundary_condition name = "Recharge at top of the domain">
    <assigned_regions>Recharge_Boundary_WestofCribs,Recharge_Boundary_btwnCribs,Recharge_Boundary_EastofCribs</assigned_regions>
    <liquid_phase name = "water">
      <liquid_component name = "water">
        <inward_mass_flux start="0.0"    function= "constant"  value="pre_1956_recharge"/>
        <inward_mass_flux start="1956.0,y" function= "constant"  value="post_1956_recharge"/>
        <inward_mass_flux start="2012.0,y" function= "constant"  value="future_recharge"/>
        <inward_mass_flux start="3000.0,y" function= "constant"  value="future_recharge"/>
      </liquid_component>
      <geochemistry_component>
        <constraint name = "west"  start="0.0"      function= "constant"/>
        <constraint name = "west2" start="1956.0,y" function= "constant"/>
      </geochemistry_component>
    </liquid_phase>
  </boundary_condition>
</boundary_conditions>

Sources¶

Sources are defined in a similar manner to the boundary conditions. Under the tag sources and series of individual source elements can be defined. Within each source element the assigned_regions and liquid_phase elements must appear. Sources can be applied to one or more region using a comma separated list of region names. Under the liquid_phase element the liquid_component element must be define. An unbounded number of solute_component elements and one geochemistry_component element may optionally be defined.

Under the liquid_component and solute_component elements a time series of boundary conditions is defined using the boundary condition elements available in the table below. Each component element can only contain one type of source. Both elements also accept a name attribute to indicate the phase associated with the source.

Liquid Phase Source Type	Attributes	Value Type
volume_weighted perm_weighted	start value function	double/time_constant/constant double `linear \| uniform \| constant`

For the solute component, the source available is aqueous_conc which has the attributes name, value, function, and start. The function options available are uniform, linear, and constant.

An example sources element looks like the following.

<sources>
  <source name = "Pumping Well" >
    <assigned_regions>Well</assigned_regions>
    <liquid_phase name = "water">
      <liquid_component name="water">
        <volume_weighted start="0.0" function="constant" value="-4.0"/>
      </liquid_component>
    </liquid_phase>
  </source>
</sources>

Outputs¶

Output data from Amanzi is currently organized into four specific elements: “Vis”, “Checkpoint”, “Observations”, and “Walkabout Data”. Each of these is controlled in different ways, reflecting their intended use.

“Visualization” is intended to represent snapshots of the solution at defined instances during the simulation to be visualized. The vis element defines the naming and frequency of saving the visualization files. The visualization files may include only a fraction of the state data, and may contain auxiliary “derived” information.
“Checkpoint” is intended to represent all that is necessary to repeat or continue an Amanzi run. The specific data contained in a checkpoint dump is specific to the algorithm options and mesh framework selected. Checkpoint is special in that no interpolation is performed prior to writing the data files; the raw binary state is necessary. As a result, the user is allowed to only write checkpoint at the discrete intervals of the simulation. The checkpoint element defines the naming and frequency of saving the checkpoint files.
“Observations” is intended to represent diagnostic values to be returned to the calling routine from Amanzi’s simulation driver. Observations are typically generated at arbitrary times, and frequently involve various point samplings and volumetric reductions that are interpolated in time to the desired instant. Observations may involve derived quantities or state fields. The observations element may define one or more specific observation.
“Walkabout Data” is intended to be used as input to the particle tracking software Walkabout.

NOTE: Each output type allows the user to specify the base_filename or filename for the output to be written to. The string format of the element allows the user to specify the relative path of the file. It should be noted that the Amanzi I/O library does not create any new directories. Therefore, if a relative path to a location other than the current directory is specified Amanzi assumes the user (or the Agni controller) has already created any new directories. If the relative path does not exist the user will see error meesages from the HDF5 library indicating failure to create and open the output file.

Vis¶

The vis element defines the visualization file naming scheme and how often to write out the files. The base_filename element contain the text component of the how the visualization files will be named. The base_filename is appended with an index number to indicate the sequential order of the visualization files. The num_digits elements indicates how many digits to use for the index. See the about NOTE about specifying a file location other than the current working directory. Finally, the time_macros or cycle_macros element indicates previously defined time_macros or cycle_macros to be used to determine the frequency at which to write the visualization files. One or more macro can be listed in a comma separated list. Amanzi will converted the list of macros to a single list of times or cycles contained by all of the macros listed and output accordingly.

The vis element also includes an optional subelement write_regions. This was primarily implemented for debugging purposes but is also useful for visualizing fields only on specific regions. The subelement accepts an arbitrary number of subelements named field, with attibutes name (a string) and regions (a comma separated list of region names). For each such subelement, a field will be created in the vis files using the name as a label. The field will be initialized to 0, and then, for region list R1, R2, R3…, cells in R1 will be set to 1, cells in R2 will be set to 2, etc. When regions in the list overlap, later ones in the list will take precedence.

An example vis element looks like the following.

<vis>
  <base_filename>plot</base_filename>
  <num_digits>5</num_digits>
  <time_macros>Macro 1</time_macros>
  <write_regions>
    <field name="fieldname" regions="region1, region2, region3" />
  </write_regions>
</vis>

Checkpoint¶

The checkpoint element defines the file naming scheme and frequency for writing out the checkpoint files. The base_filename element contains the text component of the how the checkpoint files will be named. The base_filename is appended with an index number to indicate the sequential order of the checkpoint files. The num_digits elements indicates how many digits to use for the index. See the about NOTE about specifying a file location other than the current working directory. Finally, the cycle_macro element indicates the previously defined cycle_macro to be used to determine the frequency at which to write the checkpoint files.

An example checkpoint element looks like the following.

<checkpoint>
  <base_filename>chk</base_filename>
  <num_digits>5</num_digits>
  <cycle_macro>Every_1000_steps</cycle_macro>
</checkpoint>

Observations¶

The observations element defines the file for writing observations to and specifies individual observations to be made. At this time, all observations are written to a single file defined in the filename element. See the about NOTE about specifying a file location other than the current working directory. Also, observations are only available for the liquid phases. Therefore individual observations are defined in subelements under the liquid_phase tag. The liquid_phase tag takes an attribute name to identify which phase the observations are associated with.

The element name of individual observations indicate the quantity being observed. Below is a list of currently available observations. Individual observations require the subelements assigned_regions, functional, and time_macros. aqueous_conc and primary_volumetric_flow_rate observations also require the name of the primary. This is specified with an extra subelement primary.

Available Observations:

integrated_mass
volumetric_water_content
gravimetric_water_content
aqueous_pressure
x_aqueous_volumetric_flux
y_aqueous_volumetric_flux
z_aqueous_volumetric_flux
material_id
hydraulic_head
aqueous_mass_flow_rate
aqueous_volumetric_flow_rate
aqueous_conc
drawdown
primary_volumetric_flow_rate

An example observations element looks like the following.

<observations>
  <filename>observation.out</filename>
  <liquid_phase name="water">
    <aqueous_pressure>
      <assigned_regions>Obs_r1</assigned_regions>
      <functional>point</functional>
      <time_macros>Observation Times</time_macros>
    </aqueous_pressure>
    <aqueous_pressure>
      <assigned_regions>Obs_r2</assigned_regions>
      <functional>point</functional>
      <time_macros>Observation Times</time_macros>
    </aqueous_pressure>
    <aqueous_pressure>
      <assigned_regions>Obs_r2</assigned_regions>
      <functional>point</functional>
      <time_macros>Observation Times</time_macros>
    </aqueous_pressure>
  </liquid_phase>
</observations>

Walkabout¶

The ‘’walkabout’’ element defines the file naming scheme and frequency for writing out the walkabout files. As mentioned above, the user does not influence what is written to the walkabout files only the writing frequency and naming scheme. Thus, the ‘’walkabout’’ element requires the subelements base_filename, num_digits, and cycle_macro.

The base_filename element contain the text component of the how the walkabout files will be named. The base_filename is appended with an index number to indicate the seqential order of the walkabout files. The num_digits elements indicates how many digits to use for the index. Final the cycle_macro element indicates the previously defined cycle_macro to be used to determine the frequency at which to write the walkabout files.

Example:

<walkabout>
  <base_filename>chk</base_filename>
  <num_digits>5</num_digits>
  <cycle_macro>Every_100_steps</cycle_macro>
</walkabout>