Logfile Control#

The user has a lot of control over what text appears in the logfile, or what is written to the screen during an ATS run. Typically one will forward this to a file, e.g.:

ats --verbosity=LEVEL path_to_input.xml &> out.log

The verbosity LEVEL controls how much is written to the logfile (see below for valid options). This option sets the default verbosity of all evaluators, PKs, operators, solvers, etc of the simulation. For more fine-grained control, each component also accepts a Verbose Object spec which overrides the global verbosity to control output from that component.

Verbose Object#

src/utils/VerboseObject.hh

This allows control of log-file verbosity for a wide variety of objects and physics.

verbose-object-spec

  • “verbosity level” [string] optional valid options are:

    • “none”

    • “low”

    • “medium”

    • “high”

    • “extreme”

    The default is set by the global verbosity spec, wich can be set on the command line, and defaults to “medium”. See below for a list of what each level produces.

  • “write on rank” [int] 0 VerboseObjects only write on a single rank – by deafult the 0th rank. However, sometimes it is useful for debugging to write from another rank due to a need for cleaner output or writing a specific cell/entity information.

  • “output filename” [string] optional Redirect this output to a specific file rather than writing to screen. Note this will be done by-the-instance, so this may not catch as much as one might think.

In general, the levels are as follows:

  • “none” No log output at all

  • “low” Basic flow control from the cycle driver including timing info of each main step (mesh creation, setup, initialization, etc). Each PK that takes a step writes basic info for that step, including the size of the step and the result of the step (success, fail, etc).

  • “medium” In addition to the above, each PK that advances a step writes basic error control information, e.g. nonlinear solver convergence information.

  • “high” In addition to the above, all PKs may write debug cells. Evaluators write debug cell info.

  • “extreme” Each subroutine of a PK writes some info for debugging. Each Update() writes info about the state of the dependency graph trace to debug whether it is actually updated or not.

Example:

<ParameterList name="verbose object">
  <Parameter name="verbosity level" type="string" value="medium"/>
  <Parameter name="name" type="string" value="my header"/>
  <Parameter name="hide line prefix" type="bool" value="false"/>
  <Parameter name="write on rank" type="int" value="0"/>
</ParameterList>

Debugger#

src/state/Debugger.hh

A utility for printing field values at specific IDs controlled by the user.

This is a utility that makes it easier for the user to control output written to the screen. It allows the user to provide element IDs, and then provides functionality for a PK to write mesh geometry information and vector values of those elements to screen based upon verbosity levels.

Note, most information is only written if the owning object’s verbosity level from the “verbose object” spec is set to “high” or higher.

debugger-spec

  • “debug cells” [Array(int)] optional For each global ID of a cell provided here, controls writing of vectors inside of the using PK.

  • “debug faces” [Array(int)] optional For each global ID of a face provided here, writes all adjoining cell information as if each cell was included in “debug cells”.

Residual Debugger#

src/solvers/ResidualDebugger.hh

Debugging object for writing vectors to file within an iterative process for use with vis tools.

residual-debugger-spec

  • “file name base” [string] amanzi_dbg Prefix for output filenames.

INCLUDES: