Observations

observation-spec

• “observation output filename” [string] user-defined name for the file that the observations are written to.

• “delimiter” [string] COMMA Delimiter to split columns of the file

• “write interval” [int] 1 Interval of observations on which to flush IO files.

• “time units” [string] s Controls the unit of the time column in the observation file.

• “domain” [string] “domain” Can be used to set the communicator which writes (defaults to the standard subsurface domain).

• “observed quantities” [observable-spec-list] A list of Observable objects that are all put in the same file.

INCLUDES:

• [io-event-spec] An IOEvent_ spec

Note, for backwards compatibility, an observable-spec may be directly included within the observation-spec if it is the only variable to be observed in this file.

Observations are a localized-in-space but frequent-in-time view of simulation output, designed to get at useful diagnostic quantities such as hydrographs, total water content, quantities at a point, etc. These allow frequent collection in time without saving huge numbers of visualization files to do postprocessing. In fact, these should be though of as orthogonal data queries to visualization – vis is pointwise in time but complete in space, while observations are pointwise/finite in space but complete in time.

Observables describe what is observed – the variable, region, integration/averaging scheme, etc.

A user may request any number of specific observables. Each observable spec involves a field quantity, a reduction reduction operator, a region from which it will extract its source data, and a list of discrete times for its evaluation. The observations are evaluated during the simulation and written to disk by the UnstructuredObservation object.

observable-spec

• “variable” [string] any ATS variable used by any PK, e.g. “pressure” or “surface-water_content”

• “region” [string] the label of a user-defined region

• “location name” [string] cell The mesh location of the thing to be measured, i.e. “cell”, “face”, or “node”

• “number of vectors” [int] 1 Number of vector components to write.

• “degree of freedom” [int] -1 Degree of freedom to write. Default of -1 implies writing all degrees of freedom.

• “reduction” [string] the type of function to apply to the variable on the region. One of:

  • “point” returns the value of the field quantity at a point. The region and location name should result in a single entity being selected.

  • “average” returns the volume-weighted average of the field across all entities in the region selected. This is likely what you want for intensive state variables such as “temperature” or “saturation_liquid”.

  • “integral” returns the volume-weighted sum of a variable over the region. This should be used for example on intensive sources, for instance “surface-precipitation”, to get the total source/sink.

  • “extensive integral” returns the sum of an variable over the region. This should be used for extensive quantities such as “water_content” or “energy” which already include the volume in their value.

  • “minimum” returns the min value over the region

  • “maximum” returns the max value over the region

• “modifier” [function-typedinline-spec] optional If provided, defines a function used to modify the “variable” prior to applying the “reduction”.

• “direction normalized flux” [bool] false For flux observations, dots the face-normal flux with a vector to ensure fluxes are integrated pointing the same direction.

• “direction normalized flux direction” [Array(double)] optional For flux observations, provides the vector to dot the face normal with. If this is not provided, then it is assumed that the faces integrated over are all boundary faces and that the default vector is the outward normal direction for each face.

• “direction normalized flux relative to region” [string] optional If provided, the flux observation is assumed to be on a set of faces which are the exterior of a volumetric region. This region provides that volume, and fluxes are oriented in the “outward normal” direction relative to this region’s interior.

• “time integrated” [bool] false If true, observe the time-integral, observing on all cycles and accumulating the backwards-Euler product of dt times the observable at the new time.