Operators

The operators in table 1.1 are available for formulas. For the >, <, >=, and <= operators, “true” is considered larger than “false” when applied to Booleans. For the same operators, applied to text, alphabetical order is used to decide which argument is larger.

The operator precedence rules are shown in table 1.2. Operators that are part of the same group have equal precedence. Operators of equal precedence are evaluated in order from left to right.

Functions

The same logical, math, text, and trigonometric functions available in ModelMuse are also available in “EnhancedTemplateProcessor.”

Purpose

The “OPTIONS” block is used to specify the output files to be generated by “Mf6ObsExtractor.”

Structure

BEGIN OPTIONS
	[LISTING <filename>]
	[VALUES <filename>]
	[INSTRUCTION <filename> [<instruction_file_type>]]
END OPTIONS

Explanations

The “OPTIONS” section is used for specifying the names of output files from “Mf6ObsExtractor.” Each nonblank and noncomment line in the “OPTIONS” section must begin with one of the following keywords: “LISTING,” “VALUES,” or “INSTRUCTION.” Each of these keywords must be followed by a file name. The “INSTRUCTION” file name may be optionally followed by either “UCODE” or “PEST.”

The “LISTING” file is optional. If specified, it contains a record of the steps taken during execution of “Mf6ObsExtractor.” It will end either with a line indicating that it terminated normally or with an error message. The “LISTING” file is useful for identifying errors in the input.

Either a “VALUES” or “INSTRUCTION” file is required. Typically, only one or the other is specified, but both may be specified in the same input file.

The “VALUES” file contains the simulated values extracted from the MODFLOW output file or files. Each line in the “VALUES” file contains an observation name followed by the simulated value associated with that name.

The “INSTRUCTION” file contains instructions for either UCODE or PEST to extract simulated values from the “VALUES” file. The desired format may be specified with <instruction_file_type>.

<filename> is the name of a file. If the file name contains whitespace characters, the file name must be surrounded by double quotes.

<instruction_file_type> must be either “UCODE” or “PEST,” which indicates whether the instruction file is designed to be used with the UCODE or PEST parameter estimation programs. If <instruction_file_type> is not specified, it defaults to PEST.

Example

BEGIN OPTIONS
# The file name for the listing file contains white space so it must be enclosed in double quotes
	LISTING "MyListing file.txt"
# The VALUES file contains the values extracted from the observation file.
	VALUES Example.der_obs
# The INSTRUCTION file contains instructions for PEST to extract the values from the
# VALUES file.
	INSTRUCTION Example.ins
END OPTIONS

Purpose

The “OBSERVATION_FILES” block identifies the file or files from which observations are to be extracted.

Structure

BEGIN OBSERVATION_FILES
FILENAME <filename> <file type>
[FILENAME <filename> <file type>]
[FILENAME <filename> <file type>]
...
[FILENAME <filename> <file type>]
END OBSERVATION_FILES

Explanations

Each nonblank, noncomment line in the “OBSERVATION_FILES” group must begin with the keyword “FILENAME” followed by the name of the file and the file type.

<filename> is the name of a file generated by MODFLOW 6 that contains information about simulated values that can be compared with observations. If the file name contains whitespace characters, the file name must be surrounded by double quotes.

<file type> is a keyword indicating the type of MODFLOW 6 output file that will be read. <file type> must be either “BINARY” or “TEXT.”

Example

BEGIN OBSERVATION_FILES
	FILENAME Mf6_ObsExample.ob_gw_out_head.csv TEXT
	FILENAME Mf6_ObsExample.rvob_out_riv.bin BINARY
END OBSERVATION_FILES

Purpose

The “IDENTIFIERS” block is used to extract values from the MODFLOW 6 output files corresponding to user-specified times. Optionally, locations can be associated with specific observed values. These locations can be used for interpolating to observation locations using a linear, triangular, or quadrilateral basis function. The extracted values may either represent values that should be directly compared with observed values or combined with other extracted values using the methods available in the “DERIVED_OBSERVATIONS” section.

Structure

BEGIN IDENTIFIERS
ID <identifier>
[LOCATION <x> <y>]
OBSNAME <Observation_name> <observation_time> [PRINT]
[OBSNAME <Observation_name> <observation_time> [PRINT]]
[OBSNAME <Observation_name> <observation_time> [PRINT]]
...
ID <identifier>
[LOCATION <x> <y>]
OBSNAME <Observation_name> <observation_time> [PRINT]
[OBSNAME <Observation_name> <observation_time> [PRINT]]
[OBSNAME <Observation_name> <observation_time> [PRINT]]
END IDENTIFIERS

Explanations

“ID” is a keyword used to indicate that the following values on the line will be used to identify a particular time series from which values are to be extracted.

<identifier> is the name assigned to the time series from which values are to be extracted.

LOCATION is an optional keyword indicating that the x- and y-coordinates that follow are the coordinates of the cell center of the observation time series.

<x> is the x-coordinate of the cell center of the time series associated with <identifier>.

<y> is the y-coordinate of the cell center of the time series associated with <identifier>.

“OBSNAME” is a keyword indicating that the line specifies an observation name and time.

<Observation_name> is the name of the observation. <Observation_name> must start with a letter or the underscore character. The remaining characters in <Observation_name> must be letters, digits, or the underscore character. All observation names must be unique. “Mf6ObsExtractor” does not limit the length of observation names.

<observation_time> is a real number that indicates the time at which the simulated value is desired. If the specified time is not included in the output file, “Mf6ObsExtractor” interpolates to the time in question from the values recorded for the preceding and following times. If the observation time is before the first recorded time, the value for the first recorded time is used. If the observation time is after the last recorded observation time, “Mf6ObsExtractor” ignores it.

“PRINT” is an optional keyword. If included, the <Observation_name> and simulated value are printed to the extracted values file or instructions for reading the <Observation_name> and simulated values are written into the instruction file. Printing the name and value implies direct use by PEST or UCODE. If the values are not printed, they may still be used in the “DERIVED_OBSERVATIONS” section. Regardless of whether “PRINT” is present or not, the name and simulated value are written to the listing file. “Mf6ObsExtractor” does not limit the length of observation names, but to be used by PEST or UCODE, the observation name must conform to the requirements of those programs.

Example

BEGIN IDENTIFIERS
# heads in layer 1
# heads will be interpolated in time to times 3.5 and 6.5.
# Locations are provided for spatial interpolation.
	ID HEAD1
	LOCATION 550 -550
	OBSNAME H1_1 3.5
	OBSNAME H1_2 6.5
	ID HEAD2
	LOCATION 550 -650
	OBSNAME H2_1 3.5
	OBSNAME H2_2 6.5
	ID HEAD3
	LOCATION 650 -650
	OBSNAME H3_1 3.5
	OBSNAME H3_2 6.5
	ID HEAD4
	LOCATION 650 -550
	OBSNAME H4_1 3.5
	OBSNAME H4_2 6.5
#heads in layer 2
	ID HEAD5
	LOCATION 550 -550
	OBSNAME H5_1 3.5
	OBSNAME H5_2 6.5
	ID HEAD6
	LOCATION 550 -650
	OBSNAME H6_1 3.5
	OBSNAME H6_2 6.5
	ID HEAD7
	LOCATION 650 -650
	OBSNAME H7_1 3.5
	OBSNAME H7_2 6.5
	ID HEAD8
	LOCATION 650 -550
	OBSNAME H8_1 3.5
	OBSNAME H8_2 6.5
# These heads (H9_1 and H9_2) will be printed to the Example.der_obs file.
# The rest won't be printed.
# No locations are required for H9_1 and H9_2 because they will not
# be used for spatial interpolation.
	ID HEAD9
	OBSNAME H9_1 3.5 PRINT
	OBSNAME H9_2 6.5 PRINT
# River observations
# Rivers will be interpolated in time to times 3.5 and 6.5
# Only the rivers associated RIVER1 will be printed to the Example.der_obs file.
# The rest won't be printed.
	ID RIVER1
	OBSNAME RIV1_1 3.5 PRINT
	OBSNAME RIV1_2 6.5 PRINT
	ID RIVER2
	OBSNAME RIV2_1 3.5
	OBSNAME RIV2_2 6.5
	ID RIVER3
	OBSNAME RIV3_1 3.5
	OBSNAME RIV3_2 6.5
	ID RIVER4
	OBSNAME RIV4_1 3.5
	OBSNAME RIV4_2 6.5
END IDENTIFIERS

Purpose

The “DERIVED_OBSERVATIONS” block defines how to combine multiple values extracted from the MODFLOW 6 observation files to generate values that can be compared with observed values. Two methods can be used for this purpose. First, values can be interpolated in space using a linear, triangular, or quadrilateral basis function. Second, mathematical formulas can be defined that manipulate previously extracted values.

The “DERIVED_OBSERVATIONS” section is optional.

Structure

BEGIN DERIVED_OBSERVATIONS
	OBSNAME <Observation_name> [PRINT]
	FORMULA <formula>
	...
	OBSNAME <Observation_name> [PRINT]
	INTERPOLATE <x> <y> <obs> [<obs> <obs> <obs>]
END DERIVED_OBSERVATIONS

Explanations

“OBSNAME” is a keyword indicating that the line specifies an observation name.

<Observation_name> is the name of the observation. <Observation_name> must start with a letter or the underscore character. The remaining characters in <Observation_name> must be letters, digits, or the underscore character. All observation names must be unique. “Mf6ObsExtractor” does not limit the length of observation names. An “OBSNAME” line must be followed by either a single “FORMULA” line or a single “INTERPOLATE” line.

“PRINT” is an optional keyword. If included, the <Observation_name> and simulated value are printed to the extracted values file, or instructions for reading the <Observation_name> and simulated value are written to the instruction file. Printing the name and value implies direct use by PEST or UCODE. If the values are not printed, they may still be used in the “DERIVED_OBSERVATIONS” section. Regardless of whether “PRINT” is present or not, the name and simulated value are written to the listing file. “Mf6ObsExtractor” does not limit the length of observation names, but to be used by PEST or UCODE, the observation name must conform to the requirements of those programs.

“FORMULA” is a keyword indicating that the remainder of the line is a mathematical formula that evaluates to a real number. The result of the formula is the value assigned to <Observation_name>. Variables in the formula can be any of the observation names defined in the “IDENTIFIERS” section or any observation name defined previously in the “DERIVED_OBSERVATIONS” section.

<formula> is a mathematical formula that evaluates to a real number. The result of the formula is the value assigned to <Observation_name>. Variables in the formula can be any of the observation names defined in the “IDENTIFIERS” section or any observation name defined previously in the “DERIVED_OBSERVATIONS” section. The operators and functions available for use in formulas are the same as in “EnhancedTemplateProcessor.”

“INTERPOLATE” is a keyword indicating that the remainder of the line consists of an x-coordinate, a y-coordinate, and from one to four previously defined <Observation_name> names, each of which has an associated location.

<x> and <y> are the x- and y-coordinates associated with <Observation_name>. Together, they define the observation point at which a value is desired.

<obs> is a previously defined <Observation_name> that has an associated pair of x- and y-coordinates. If only one <obs> is included, its value is taken as the value of <Observation_name>. If two to four <obs> are defined, those values define the nodes and values of a linear, triangular, or quadrilateral basis function and the value of <Observation_name> is defined using a linear, triangular, or quadrilateral basis function.

Example

#(Optional)
BEGIN DERIVED_OBSERVATIONS
# Spatially Interpolate the head in layer 1 at (575, -575) at time 3.5
	OBSNAME H_Layer1_Time1
	INTERPOLATE 575 -575 H1_1 H2_1 H3_1 H4_1
# Spatially Interpolate the head in layer 1 at (575, -575) at time 6.5
	OBSNAME H_Layer1_Time2
	INTERPOLATE 575 -575 H1_2 H2_2 H3_2 H4_2
# Spatially Interpolate the head in layer 2 at (575, -575) at time 3.5
	OBSNAME H_Layer2_Time1
	INTERPOLATE 575 -575 H5_1 H6_1 H7_1 H8_1
# Spatially Interpolate the head in layer 2 at (575, -575) at time 6.5
	OBSNAME H_Layer2_Time2
	INTERPOLATE 575 -575 H5_2 H6_2 H7_2 H8_2
# Calculate multilayer head observations at times 3.5 and 6.5 weighted by transmissivity
# Transmissivity of layer 1 = 3
# Transmissivity of layer 2 = 6
# Print the multilayer head observations
	OBSNAME H_Time1 PRINT
	FORMULA (H_Layer1_Time1 * 3 + H_Layer2_Time1 * 6) / (3 + 6)
	OBSNAME H_Time2 PRINT
	FORMULA (H_Layer1_Time2 * 3 + H_Layer2_Time2 * 6) / (3 + 6)
# Calculate a drawdown observation too.
	OBSNAME Drawdown PRINT
	FORMULA H_Time1 - H_Time2
# Calculate a river observation by combining several separate river observations.
# Only half of rivers 2 and 4 will be used.
	OBSNAME MyRiver_1 PRINT
	FORMULA RIV2_1*0.5 + RIV3_1 + RIV4_1*0.5
	OBSNAME MyRiver_2 PRINT
	FORMULA RIV2_2*0.5 + RIV3_2 + RIV4_2*0.5
END DERIVED_OBSERVATIONS

Structure of Blocks

BEGIN OUTPUT_FILES
LIST <filename>
[INSTRUCTION_FILE <filename>]
[OBSERVATIONS_FILE <filename>]
END OUTPUT_FILES
BEGIN INPUT_FILES
[<file_type> <filename>]
[MNW2 <filename>]
[LAK <filename>]
[SFR <filename>]
[SUB <filename>]
[SWT <filename>]
[SWI <filename>]
[HOB <filename>]
[CHOB <filename>]
[DROB <filename>]
[RVOB <filename>]
[GBOB <filename>]
[STOB <filename>]
[DERIVED <filename>]
END INPUT_FILES

Explanation of Variables

Example

BEGIN OUTPUT_FILES
LIST DryCells.Mf2005ObsExtInsLst
INSTRUCTION_FILE DryCells.PestIns
END OUTPUT_FILES
BEGIN INPUT_FILES
DROB DryCells.drob_out
SFR DryCells.Sfr_script
HOB DryCells.hob_out
END INPUT_FILES

Structure of Observation Definition Files

BEGIN OBSERVATIONS
FILENAME <filename>
OBSERVATION <Observation_name> <Observation_type> <Observation_time> <Observed_value> <Weight> [PRINT|NO_PRINT]
[NUMBER_OF_ZETA_SURFACES <number_of_zeta_surfaces>]
[TOTAL_NUMBER_OF_OBSERVATIONS <number_of_observation_locations_in_SWI_observation_file>]
[SWI_OBS_FORMAT (ASCII | BINARY SINGLE | BINARY DOUBLE)]
OBSERVATION <Observation_name> <Observation_type> <Observation_time> <Observed_value> <Weight> [PRINT|NO_PRINT]
[ZETA_SURFACE_NUMBER <zeta_surface_number>]
[SWI_OBSERVATION <number> <fraction> <name>]
FILENAME <filename>
OBSERVATION <Observation_name> <Observation_type> <Observation_time> <Observed_value> <Weight> [PRINT|NO_PRINT]
OBSERVATION <Observation_name> <Observation_type> <Observation_time> <Observed_value> <Weight> [PRINT|NO_PRINT]
[CELL <layer_or_interbed_system> <row> <column> <cellweight>]
END OBSERVATIONS
[BEGIN DERIVED_OBSERVATIONS]
[DIFFERENCE <Observation_name> <Prior_observation_name> <Prior_observation_name>] <Observed value> <Weight> [PRINT|NO_PRINT]
[SUM <Observation_name> <Prior_observation_name1> <Prior_observation_name2> ... <Prior_observation_nameN>] <Observed value> <Weight> [PRINT|NO_PRINT]
[END DERIVED_OBSERVATIONS]

Explanation of Variables

Block: OBSERVATIONS.

The “OBSERVATIONS” block is required in all but the “DERIVED” input file. The “OBSERVATIONS” block cannot be included in the “DERIVED” input file.

“FILENAME” is a keyword indicating that the filename that follows is the name of an output file containing the data from which simulated values will be extracted. A “FILENAME” line can be followed by one or more “OBSERVATION” lines.

<filename> is the name of a file. It may be enclosed in either single or double quotation marks.

“NUMBER_OF_ZETA_SURFACES” is a keyword indicating that the integer that follows is the number of zeta surfaces defined in the SWI package. “NUMBER_OF_ZETA_SURFACES” can only be used with SWI observation files. “NUMBER_OF_ZETA_SURFACES” is required for SWI observation files.

<number_of_zeta_surfaces> is the number of zeta surfaces defined in the SWI package.

“TOTAL_NUMBER_OF_OBSERVATIONS” is a keyword indicating that the integer that follows is the number of observation locations in the “SWI observation” output file. “TOTAL_NUMBER_OF_OBSERVATIONS” can only be used with “SWI observation” files. “TOTAL_NUMBER_OF_OBSERVATIONS” is required for “SWI observation” files.

<number_of_observation_locations_in_SWI_observation_file> is the number of observation locations in the “SWI observation” output file.

“SWI_OBS_FORMAT” is a keyword indicating that the text that follows designates the file type of the “SWI observation” output file. “SWI_OBS_FORMAT” must be followed by either “ASCII,” “BINARY SINGLE,” or “BINARY DOUBLE.” “SWI_OBS_FORMAT” can only be used with “SWI observation” files. “SWI_OBS_FORMAT” is required for “SWI observation” files.

“ASCII” is a keyword indicating that the “SWI observation” output file is a text file.

“BINARY SINGLE” is a pair of keywords indicating that the “SWI observation” output file is a single-precision binary file.

“BINARY DOUBLE” is a pair of keywords indicating that the “SWI observation” output file is a double-precision binary file.

“OBSERVATION” is a keyword indicating that the values that follow define a simulated value that should be extracted from the previously specified output file. An “OBSERVATION” line must follow a “FILENAME” line.

<Observation_name> is the name of an observation. All observation names must be unique. Observation names are not case sensitive. An observation name can contain white space if the name is enclosed in double quotation marks. However, observation names containing spaces are not recommended.

<Observation_type> The observation type indicates the type of data to be extracted from the output file. Valid observation types depend on the type of file from which the observations are extracted. Note that the names of the observation types contain periods.

For “MNWI,” the type must be one of the following: “Qin,” “Qout,” “Qnet,” “QCumu,” or “hwell.” (Other observation types may be included in the “MNWI” output file, but they are not included here.)

For lake “GAGE” output files, the type must be one of the following: “Stage(H),” “Volume,” “Precip.,” “Evap.,” “Runoff,” “GW-Inflw,” “GW-Outflw,” “SW-Inflw,” “SW-Outflw,” “Withdrawal,” “Lake-Inflx,” “Total-Cond.,” “Del-H-TS,” “Del-V-TS,” “Del-H-Cum,” or “Del-V-Cum.”

For stream “GAGE” output files, the type must be one of the following: “Stage,” “Flow,” “Depth,” “Width,” “Midpt-Flow,” “Precip.,” “ET,” “Runoff,” “Conductance,” “HeadDiff,” “Hyd.Grad.” or “GW_FLOW.” “GW_FLOW” is not part of the stream “GAGE” output file but will be calculated by multiplying the values for “Conductance” and “HeadDiff.”

For “SUB” observations, the type must be one of the following: “LAYER COMPACTION,” “NDSYS COMPACTION,” “DSYS COMPACTION,” “Z DISPLACEMENT,” “ND CRITICAL HEAD,” or “D CRITICAL HEAD.”

For “SWT” observations, the type must be one of the following: “SUBSIDENCE,” “LAYER COMPACTION,” “SYSTM COMPACTION,” “Z DISPLACEMENT,” “PRECONSOL STRESS,” “CHANGE IN PCSTRS,” “GEOSTATIC STRESS,” “CHANGE IN G-STRS,” “EFFECTIVE STRESS,” “CHANGE IN EFF-ST,” “VOID RATIO,” “THICKNESS,” or “CENTER ELEVATION.”

For “SWI” observations, the observation type must be “ZETA.”

Observation types are not case sensitive. If an observation type contains any space characters, the observation type must be enclosed in single or double quotation marks.

<Observation_time> is the time for which a simulated value is desired. If the time at which a simulated value is desired is not included in the “MNWI” output file, linear interpolation is used to calculate a simulated value at the observation time. If the observation time is before the first time recorded in the output file, the first value from the file is used. If the time is after the last time recorded in the “MNWI” output file, a value of –1E31 is used to indicate that the data are missing

<Observed_value> is the measured value for the observation.

<Weight> is the weight assigned to the observation.

“PRINT” and “NO_PRINT” are optional keywords used to indicate that a simulated value either should or should not be printed in the “OBSERVATIONS_FILE.” If these keywords are omitted, the simulated value is printed. Regardless of the “PRINT” or “NO_PRINT” options, all simulated values are printed in the listing file.

“ZETA_SURFACE_NUMBER” is a keyword indicating that the zeta surface number from an “SWI observation” output file is specified.

<zeta_surface_number> is the number of the zeta surface that is used for the observation.

“SWI_OBSERVATION” is a keyword indicating that the following three pieces of data specify an observation series in the “SWI” output file that is used for interpolating the simulated value to the location and time of the observation. Each observation from an “SWI” output file includes one or more observation series from which the observed value is interpolated. “SWI_OBSERVATION” can only be used with “SWI” observation files. “SWI_OBSERVATION” is required for “SWI” observation files.

<number> indicates the position of the observation series in the list of observation series stored in the “SWI” output file.

<fraction> indicates the fractional weight applied to this observation used to interpolate among all the “SWI” values extracted from the “SWI observation” output file.

<name> indicates the name of the observation series used for interpolating to the observation location. <name> is only used for “ASCII SWI” observation files but must be specified for all observations.

“CELL” is a keyword indicating that one or more cell locations will be specified. Cells can only be specified for “SUB” and “SWT” observations. Each “SUB” or “SWT” observation must include one or more cell locations. Cell locations are used to spatially interpolate to the observation location. The first cell listed must contain the observation location.

<layer_or_interbed_system> is the layer number or interbed system of the cell used for spatial interpolation to the observation location. <layer_or_interbed_system> must be specified for all observation types but is only used for “LAYER COMPACTION,” “Z DISPLACEMENT,” “NDSYS COMPACTION,” and “DSYS COMPACTION” among subsidence observations. It is used for all but the “SUBSIDENCE SWT” observation types. <layer_or_interbed_system> represents a layer for “LAYER COMPACTION,” “Z DISPLACEMENT” among subsidence observations. It represents an interbed system for “NDSYS COMPACTION” and “DSYS COMPACTION” among subsidence observations. <layer_or_interbed_system> represents an interbed system for “SYSTM COMPACTION”, “VOID RATIO”, and “THICKNESS” among “SWT” observations.

<row> is the row number of the cell used for spatial interpolation to the observation location.

<column> is the column number of the cell used for spatial interpolation to the observation location.

<cellweight> is the weight used for spatial interpolation for this cell.

Block: “DERIVED_OBSERVATIONS.”

The “DERIVED_OBSERVATIONS” block is optional. If present, it must follow the “OBSERVATIONS” block unless the file type is “DERIVED.”

“DIFFERENCE” is a keyword indicating that the derived observation is calculated as the difference between two previously defined observations.

“SUM” is a keyword indicating that the derived observation are calculated as the sum of two or more previously defined observations.

<Observation_name> is the name of an observation. All observation names must be unique. Observation names are not case sensitive. An observation name can contain white space if the name is enclosed in double quotation marks. However, observation names containing spaces are not recommended.

<Prior_observation_name> is the name of a previously defined observation. Two prior observation names must be specified. The simulated value is the simulated value for the first observation minus the simulated value for the second observation.

<Prior_observation_name1>, <Prior_observation_name2>, through <Prior_observation_nameN> are the names of previously defined observations. Two or more prior observation names must be specified. The simulated value is the sum of the simulated values of the prior observations.

<Observed value> is the measured value for the derived observation.

<Weight> is the weight assigned to the derived observation.

“[PRINT|NO_PRINT]”—“PRINT” and “NO_PRINT” are optional keywords used to indicate that a simulated value either should or should not be printed in the “OBSERVATIONS_FILE.” If these keywords are omitted, the simulated value is printed. Regardless of the “PRINT” or “NO_PRINT” options, all simulated values are printed in the listing file.

Examples

BEGIN OBSERVATIONS
# Observations defined in Well3
FILENAME Mnw2ObsTest_Well3.mnwi_out
OBSERVATION Mnw2_1MnwObs Hwell 1.000000000000E+000 1.000000000000E+000 1.000000000000E+000 PRINT
END OBSERVATIONS
Observation Definition file for SUB
BEGIN OBSERVATIONS
FILENAME "SubObs.SubSubOut"
OBSERVATION Sub_1SubObs0 "SUBSIDENCE" 1.000000000000E+003 1.000000000000E-002 1.000000000000E+000 PRINT
CELL 1 5 5 6.966249525976E-001
CELL 1 5 6 3.167880496423E-015
CELL 1 4 6 1.379588675633E-015
CELL 1 4 5 3.033750474023E-001
OBSERVATION Sub_2SubObs1 "SUBSIDENCE" 5.000000000000E+003 5.000000000000E-001 0.000000000000E+000 PRINT
CELL 1 5 5 6.966249525976E-001
CELL 1 5 6 3.167880496423E-015
CELL 1 4 6 1.379588675633E-015
CELL 1 4 5 3.033750474023E-001
OBSERVATION Sub_3SubObs2 "SUBSIDENCE" 1.096000000000E+004 1.000000000000E+000 0.000000000000E+000 PRINT
CELL 1 5 5 6.966249525976E-001
CELL 1 5 6 3.167880496423E-015
CELL 1 4 6 1.379588675633E-015
CELL 1 4 5 3.033750474023E-001
END OBSERVATIONS
BEGIN DERIVED_OBSERVATIONS
# Observation comparisons defined in Object6
DIFFERENCE Sub_1SubComp Sub_3SubObs2 Sub_2SubObs1 5.000000000000E-001 1.000000000000E+000 PRINT
END DERIVED_OBSERVATIONS
Observation Definition file for SWT
BEGIN OBSERVATIONS
FILENAME "SwtObsTest.Swt_Out"
OBSERVATION Swt_1SwtObs "SUBSIDENCE" 4.383100000000E+004 1.000000000000E+000 1.000000000000E+000 PRINT
CELL 1 14 5 2.956578414865E-002
CELL 1 14 6 7.863713651218E-001
CELL 1 13 6 1.773932653095E-001
CELL 1 13 5 6.669585420053E-003
END OBSERVATIONS
Observation Definition file for LAK
BEGIN OBSERVATIONS
# Observations defined in Object4
FILENAME C:\ModelingTools\ModelMuse\PestTest\lakeTestObs.lakg2
OBSERVATION Lak_2Lake Stage(H) 1.000000000000E+000 1.000000000000E+000 1.000000000000E+000 PRINT
END OBSERVATIONS
Observation Definition file for SWI
BEGIN OBSERVATIONS
FILENAME "SWI1.swi_obs"
SWI_OBS_FORMAT ASCII
TOTAL_NUMBER_OF_OBSERVATIONS 2
NUMBER_OF_ZETA_SURFACES 1
OBSERVATION SwiObs "Zeta" 4.000000000000E+002 2.000000000000E+001 1.000000000000E+002 PRINT
ZETA_SURFACE_NUMBER 1
SWI_OBSERVATION 1 1.082862523540E-001 Obs_1
SWI_OBSERVATION 2 8.917137476460E-001 Obs_2
END OBSERVATIONS
Observation Definition file for SFR
BEGIN OBSERVATIONS
# Observations defined in Object10
FILENAME C:\ModelingTools\ModelMuse\PestTest\DryCells.sfrg1
OBSERVATION SFR_1sfr Stage 1.000000000000E+000 0.000000000000E+000 1.000000000000E+000 PRINT
END OBSERVATIONS

Purpose

The “OPTIONS” block is used for specifying the names of output files from “SutraObsExtractor.”

Structure

BEGIN OPTIONS
[LISTING <filename>]
[INSTRUCTION <filename> [<instruction_file_type>]]
[VALUES <filename>]
END OPTIONS

Explanations

Each nonblank and noncomment line in the “OPTIONS” section must begin with one of the following keywords: “LISTING,” “VALUES,” or “INSTRUCTION.” Each of these keywords must be followed by a file name. The “INSTRUCTION” file name may be optionally followed by either “UCODE” or “PEST.”

The “LISTING” file is optional. If specified, it contains a record of the steps taken during execution of “SutraObsExtractor.” The file ends either with a line indicating that it terminated normally or with an error message. The “LISTING” file is useful for identifying errors in the input.

Either a “VALUES” or “INSTRUCTION” file is required. Typically, only one or the other is specified, but both may be specified in the same input file.

The “VALUES” file contains the simulated values extracted from the SUTRA output file or files. Each line in the “VALUES” file contains an observation name followed by the simulated value associated with that name.

The “INSTRUCTION” file contains instructions for either UCODE or PEST to extract simulated values from the “VALUES” file. The desired format may be specified with <instruction_file_type>.

<filename> is the name of a file. If the file name contains whitespace characters, the file name must be surrounded by double quotes.

<instruction_file_type> must be either “UCODE” or “PEST.” It indicates whether the instruction file is designed to be used with the UCODE or PEST parameter estimation programs. If <instruction_file_type> is not specified, it defaults to PEST.

Examples

BEGIN OPTIONS
LISTING C:\ModelingTools\SutraObsExtractor\tests\SutraLake2.soeOut
INSTRUCTION C:\ModelingTools\SutraObsExtractor\tests\SutraLake2.soeIns.txt
END OPTIONS
BEGIN OPTIONS
LISTING SutraLake2.soeList
VALUES SutraLake2.soeValues
END OPTIONS

Purpose

The “OBSERVATION_FILES” section functions to identify the files from which simulated values are extracted.

Structure

BEGIN OBSERVATION_FILES
FILENAME <filename> <file type>
[FILENAME <filename> <file type>]
[FILENAME <filename> <file type>]
...
[FILENAME <filename> <file type>]
END OBSERVATION_FILES

Explanations

Each nonblank, noncomment line in the “OBSERVATION_FILES” group must begin with the keyword “FILENAME” followed by the name of the file and the file type.

<filename> is the name of a file generated by SUTRA that contains information about simulated values that can be compared with observations. If the file name contains whitespace characters, the file name must be surrounded by double quotes.

<file type> is a keyword indicating the type of SUTRA output file that is read. <file type> must be one of the following “OBC,” “LKST,” “BCOP,” “BCOF,” “BCOU,” “BCOPG,” or “BCOUG.” For more information about these file types, see the documentation for SUTRA version 2.2 (Voss and Provost, 2002).

Example

BEGIN OBSERVATION_FILES
FILENAME SutraLake2_Object9.obc OBC
FILENAME SutraLake2_Object16.obc OBC
# this is a comment.
# Note that there is more than one OBC file is included in the OBSERVATION_FILES
# section.
# This is the only file type supported by SutraObsExtractor for which SUTRA will create
# more
# than one file for the same model.
FILENAME SutraLake2.lkst LKST
FILENAME SutraLake2.bcop BCOP
FILENAME SutraLake2.bcof BCOF
FILENAME SutraLake2.bcou BCOU
FILENAME SutraLake2.bcopg BCOPG
FILENAME SutraLake2.bcoug BCOUG
END OBSERVATION_FILES

Purpose

The “IDENTIFIERS” section is used to identify simulated values to be extracted from the SUTRA output files corresponding to user-specified times. These values may either represent values that should be directly compared with observed values or combined with other extracted values using the methods available in the “DERIVED_OBSERVATIONS” section.

Structure

BEGIN IDENTIFIERS
ID <identifier> <observation_type> [<secondary_identifier>]
OBSNAME <Observation_name> <observation_time> [PRINT]
OBSNAME <Observation_name> <observation_time> [PRINT]
...
OBSNAME <Observation_name> <observation_time> [PRINT]
ID <identifier> <observation_type> [<secondary_identifier>]
OBSNAME <Observation_name> <observation_time> [PRINT]
OBSNAME <Observation_name> <observation_time> [PRINT]
...
OBSNAME <Observation_name> <observation_time> [PRINT]
END IDENTIFIERS

Explanations

“ID” is a keyword used to indicate that the following values on the line are used to identify a particular time series from which values are to be extracted.

<identifier> is a value in the output file that identifies a particular time series. The nature of <identifier> varies depending on the type of file from which the simulated value is to be extracted.

For OBC files, <identifier> is the “Name” listed in the “OBC” file.

For LKST files, <identifier> is the node number listed in the “LKST” file.

For all other files, <identifier> is the sequence number in which the values appear in the file for each time step for which values are recorded.

<observation_type> is used to identify the type of data to be extracted. The allowed values of <observation_type> depend on the type of file from which values are to be extracted:

P: Pressure in an “OBC” file.

U: Temperature or concentration in an “OBC” file.

S: Saturation in an “OBC” file.

LKST: Lake stage in an “LKST” file.

PF: Resultant source/sink (+/–) of fluid in a “BCOP” file.

PU: Solute concentration/temperature of fluid source/sink in a “BCOP” file.

PR: Resultant source/sink (+/–) of mass/energy in a “BCOP” file.

FF: Specified flow rate in a “BCOF” file.

FU: Solute concentration/temperature of fluid source/sink in a “BCOF” file.

FR: Resultant source/sink (+/–) of mass/energy in a “BCOF” file.

UR: Resultant source/sink (+/–) of mass/energy in a “BCOU” file.

PGF: Resultant source/sink (+/–) of fluid in a “BCOPG” file.

PGU: Solute concentration/temperature of fluid source/sink in a “BCOPG” file.

PGR: Resultant source/sink (+/–) of mass/energy in a “BCOPG” file.

UGR: Resultant source/sink (+/–) of mass/energy in a “BCOUG” file.

UGU: Computed concentration/temperature in a “BCOUG” file.

<secondary_identifier> is a second value on a line that helps identify a particular time series. It is required for observations in “BCOP,” “BCOF,” “BCOU,” “BCOPG,” and “BCOUG” files. It must not be included for observations in “OBC” and “LKST” files. For the file types that require it, <secondary_identifier> must be the node number. Note that the same node number may be repeated more than once for a single time step if the same node is specified more than once for the appropriate boundary condition in the SUTRA input file. However, it is not clear that SUTRA handles specified pressure, specified flows, or specified concentration or temperature boundary conditions that are specified more than once at the same node. It appears that generalized-flow and generalized-transport boundaries are handled appropriately if specified more than once for the same node in the input file. <secondary_identifier> serves as a check that <identifier> has been specified correctly.

After each “ID” line, there must be one or more “OBSNAME” lines. Each such line specifies an observation name and a time at which a simulated value is desired. The value is from the time series identified in the “ID” line.

“OBSNAME” is a keyword indicating that the line specifies an observation name and time.

<Observation_name> is the name of the observation. <Observation_name> must start with a letter or the underscore character. The remaining characters in <Observation_name> must be letters, digits, or the underscore character. All observation names must be unique. “SutraObsExtractor” does not limit the length of observation names.

<observation_time> is a real number that indicates the time at which the simulated value is desired. If the specified time is not included in the output file, “SutraObsExtractor” interpolates to the time in question from the values recorded for the preceding and following times. If the <observation_time> is before the first recorded time, it is ignored. If it is after the last recorded time, the value for the last recorded time is used.

“PRINT” is an optional keyword. If included, the <Observation_name> and simulated value are printed to the extracted values file or instructions for reading the <Observation_name> and simulated value are written to the instruction file. Printing the name and value implies direct use by PEST or UCODE. If the values are not printed, they may still be used in the “DERIVED_OBSERVATIONS” section. Regardless of whether “PRINT” is present or not, the name and simulated value are written to the listing file. “SutraObsExtractor” does not limit the length of observation names, but to be used by PEST or UCODE, the observation name must conform to the requirements of those programs.

Example

BEGIN IDENTIFIERS
ID Object9 P
OBSNAME Test1_P 1.000000000000E+006 PRINT
ID Object9 P
OBSNAME Test2_P 2.000000000000E+006 PRINT
ID Object16 U
OBSNAME ConcOb1_U 1.000000000000E+006 PRINT
ID Object16 U
OBSNAME ConcOb2_U 2.000000000000E+006 PRINT
ID 5435 LKST
OBSNAME lakeobs 1.600000000000E+008 PRINT
# This is an example of a comment because it starts with "#."
# Note that the simulated values for most of these observations are not printed to
# the values output file but instead are used in calculations in the
# DERIVED_OBSERVATIONS section.
ID 367 PF 4027
OBSNAME PF367_4027_0 6.048000000000E+005
OBSNAME PF367_4027_1 5.866600000000E+007
ID 367 PR 4027
OBSNAME PR367_4027_0 6.048000000000E+005
OBSNAME PR367_4027_1 5.866600000000E+007
ID 387 PF 4247
OBSNAME PF387_4247_0 6.048000000000E+005
OBSNAME PF387_4247_1 5.866600000000E+007
ID 387 PR 4247
OBSNAME PR387_4247_0 6.048000000000E+005
OBSNAME PR387_4247_1 5.866600000000E+007
ID 388 PF 4258
OBSNAME PF388_4258_0 6.048000000000E+005
OBSNAME PF388_4258_1 5.866600000000E+007
ID 388 PR 4258
OBSNAME PR388_4258_0 6.048000000000E+005
OBSNAME PR388_4258_1 5.866600000000E+007
ID 1 FF 4731
OBSNAME FF1_4731_0 1.191500000000E+008
ID 1 FR 4731
OBSNAME FR1_4731_0 1.191500000000E+008
ID 1 UR 4552
OBSNAME UR1_4552_0 1.191500000000E+008
OBSNAME UR1_4552_1 2.395000000000E+008
ID 2 UR 4553
OBSNAME UR2_4553_0 1.191500000000E+008
OBSNAME UR2_4553_1 2.395000000000E+008
ID 3 UR 4554
OBSNAME UR3_4554_0 1.191500000000E+008
OBSNAME UR3_4554_1 2.395000000000E+008
ID 1 PGF 5688
OBSNAME PGF1_0_5688 5.866600000000E+007
OBSNAME PGF1_1_5688 5.866600000000E+007
ID 1 PGR 5688
OBSNAME PGR1_1_5688 5.866600000000E+007
OBSNAME PGR1_2_5688 5.866600000000E+007
ID 2 PGF 5689
OBSNAME PGF2_0_5689 5.866600000000E+007
OBSNAME PGF2_1_5689 5.866600000000E+007
ID 2 PGR 5689
OBSNAME PGR2_1_5689 5.866600000000E+007
OBSNAME PGR2_2_5689 5.866600000000E+007
# Note that nodes 6161 and 6162 are each identified in two separate lines.
# This is because two generalized flow boundaries were defined for those nodes.
ID 3 PGF 6161
OBSNAME PGF3_0_6161 5.866600000000E+007
OBSNAME PGF3_1_6161 5.866600000000E+007
ID 3 PGR 6161
OBSNAME PGR3_1_6161 5.866600000000E+007
OBSNAME PGR3_2_6161 5.866600000000E+007
ID 4 PGF 6162
OBSNAME PGF4_0_6162 5.866600000000E+007
OBSNAME PGF4_1_6162 5.866600000000E+007
ID 4 PGR 6162
OBSNAME PGR4_1_6162 5.866600000000E+007
OBSNAME PGR4_2_6162 5.866600000000E+007
ID 5 PGF 6161
OBSNAME PGF5_0_6161 5.866600000000E+007
OBSNAME PGF5_1_6161 5.866600000000E+007
ID 5 PGR 6161
OBSNAME PGR5_1_6161 5.866600000000E+007
OBSNAME PGR5_2_6161 5.866600000000E+007
ID 6 PGF 6162
OBSNAME PGF6_0_6162 5.866600000000E+007
OBSNAME PGF6_1_6162 5.866600000000E+007
ID 6 PGR 6162
OBSNAME PGR6_1_6162 5.866600000000E+007
OBSNAME PGR6_2_6162 5.866600000000E+007
ID 1 UGR 3125
OBSNAME UGR1_0_3125 5.866600000000E+007
ID 2 UGR 3126
OBSNAME UGR2_0_3126 5.866600000000E+007
END IDENTIFIERS

Purpose

The “DERIVED_OBSERVATIONS” section is used to define how to combine multiple values extracted from the “SUTRA Observations” files to generate values that can be compared with observed values.

Structure

BEGIN DERIVED_OBSERVATIONS
OBSNAME <Observation_name> [PRINT]
FORMULA <formula>
OBSNAME <Observation_name> [PRINT]
FORMULA <formula>
...
OBSNAME <Observation_name> [PRINT]
FORMULA <formula>
END DERIVED_OBSERVATIONS

Explanations

“OBSNAME” is a keyword indicating that the line will specify an observation name.

<Observation_name> is the name of the observation. See the description under “IDENTIFIERS.”

“PRINT” is an optional keyword. If included, the <Observation_name> and simulated value are printed to the extracted values file or instructions for reading the <Observation_name> and simulated value will be written to the instruction file. See the description under “IDENTIFIERS.”

“FORMULA” is a keyword indicating that the remainder of the line is a mathematical formula that evaluates to a real number. The result of the formula is the value assigned to <Observation_name>. Variables in the formula can be any of the observation names defined in the “IDENTIFIERS” section or any observation names defined previously in the “DERIVED_OBSERVATIONS” section.

<formula> is a mathematical formula that evaluates to a real number. The result of the formula is the value assigned to <Observation_name>. Variables in the formula can be any of the observation names defined in the “IDENTIFIERS” section or any <Observation_name> defined previously in the “DERIVED_OBSERVATIONS” section. The functions and operators available for use in formulas are the same as in “EnhancedTemplateProcessor.”

Example

In the following example, some formulas may be printed on multiple lines because there is not enough space on a page to print them on a single line. In the actual file, however, they would each be on a single line.

BEGIN DERIVED_OBSERVATIONS
# The observation named "a" is assigned the sum of the flow rates
# at three specified pressure nodes.
OBSNAME a PRINT
FORMULA PF367_4027_0 + PF387_4247_0 + PF388_4258_0
# The observation named "b" is assigned the resultant source/sink (+/-) of mass in three
# specified pressure nodes divided by the sum of the flow rates at those nodes. Assuming fluid
# leaves the system through all these specified pressure nodes, the result is the concentration
# of the combined flow through those nodes.
OBSNAME b PRINT
FORMULA (PR367_4027_1 + PR387_4247_1 + PR388_4258_1)/(PF367_4027_1 + PF387_4247_1 + PF388_4258_1)
# The formula used for the observation named "Well" gives the concentration of solute leaving
# through the well (assuming the specified flow rate is negative.) Because only one node is
# involved, an alternative would be to use a concentration (FU) observation in the
# IDENTIFIERS section.
OBSNAME Wel1 PRINT
FORMULA (FR1_4731_0)/(FF1_4731_0)
# The formula for "Wel2" simply retrieves the value from an observation defined in the
# IDENTIFIERS section.
OBSNAME Wel2 PRINT
FORMULA FR1_4731_0
# The formulas for "SpecConc1" and "SpecConc2" sum the resultant solute mass flux at three
# specified concentration nodes.
OBSNAME SpecConc1 PRINT
FORMULA UR1_4552_0 + UR2_4553_0 + UR3_4554_0
OBSNAME SpecConc2 PRINT
FORMULA UR1_4552_1 + UR2_4553_1 + UR3_4554_1
# The formula for "GenFlow1" sums the flow rates at several generalized-flow boundaries.
# However, two of the flow rates are multiplied by 0.6. If these generalized-flow boundaries
# represent a river but the observed value represents only 60% of the flow into or out of the river
# at these nodes, the 0.6 factor could be used to ensure that the simulated value more closely
# represented what was observed.
OBSNAME GenFlow1 PRINT
FORMULA PGF1_0_5688 + PGF2_0_5689 + PGF3_0_6161 + PGF4_0_6162 + 0.6*PGF5_0_6161 + 0.6*PGF6_0_6162
# For "GenFlow2," the formula calculates a concentration by dividing the weighted sum of the
# resultant mass flows by the weighted sum of the fluid flows.
OBSNAME GenFlow2 PRINT
FORMULA (PGR1_1_5688 + PGR2_1_5689 + PGR3_1_6161 + PGR4_1_6162 + 0.6*PGR5_1_6161 + 0.6*PGR6_1_6162)/(PGF1_1_5688 + PGF2_1_5689 + PGF3_1_6161 + PGF4_1_6162 + 0.6*PGF5_1_6161 + 0.6*PGF6_1_6162)
# "GenFlow3" represents the sum of the resultant flow through several generalized-flow
# boundaries.
OBSNAME GenFlow3 PRINT
FORMULA PGR1_2_5688 + PGR2_2_5689 + PGR3_2_6161 + PGR4_2_6162 + 0.6*PGR5_2_6161 + 0.6*PGR6_2_6162
# "GenTrans1" represents the sum of the resultant mass flows through two generalized-transport
# boundaries.
OBSNAME GenTrans1 PRINT
FORMULA UGR1_0_3125 + UGR2_0_3126
# "test3" represents the difference in pressure between two pressure observations.
OBSNAME test3 PRINT
FORMULA Test1_P - Test2_P
# "c" represents a difference between two previously defined derived observations. "a" is a
# pressure observation and a concentration observation. That doesn't make any sense for a real
# model. The modeler is responsible for ensuring that the formulas result in meaningful values.
OBSNAME c PRINT
FORMULA a - b
# This is another case where the values being compared have different units.
OBSNAME WelComp PRINT
FORMULA Wel1 - Wel2
# "DeltaSpecConc" represents the change in resultant mass flux at a specified concentration
# boundary at two different times.
OBSNAME DeltaSpecConc PRINT
FORMULA SpecConc1 - SpecConc2
# "Comp" computes the difference between a stage observation and the pressure at an
# observation location. Assuming that SUTRA is set up so that head rather than pressure is
# calculated, this value could be compared with an observed head gradient multiplied by the
# distance between the lake and the observation location.
OBSNAME Comp PRINT
FORMULA lakeobs - Test1_P
END DERIVED_OBSERVATIONS