Mf6ObsExtractor

Mf6ObsExtractor is a program for extracting simulated values from MODFLOW 6 output files at particular locations and times and printing them in a simple format. It also can create an instruction file for either PEST or UCODE. Together, these two functions can simplify the usage of PEST or UCODE with MODFLOW 6 models.

The Observation Utility in MODFLOW 6 is used to create output binary or text files containing simulated values for particular cells. When those cells contain model features, some simulated values for those model features can be included in the output files. The output files contain values for the selected observation types at every time step along with the simulation time. These simulated values may require further manipulation before being compared to observed values. For example, simulated head values will be saved at cell centers, but the observed value may not be at the center of a cell. The observation time also may not correspond to a simulation time. Thus, interpolation in space and time may be necessary to generate a value suitable for comparison with an observed value. Observations of flow through boundaries are often helpful in calibrating models but may require combining simulated flows from several cells to obtain a value suitable for comparison with the observed flows. Mf6ObsExtractor can be used to perform the required manipulations to obtain simulated values suitable for comparison with observed values.

The data for Mf6ObsExtractor is specified in four blocks. Each block begins with the keyword BEGIN followed by the name of the block and ends with the keyword END followed by the name of the block. The names of the blocks are OPTIONS, OBSERVATION_FILES, IDENTIFIERS, and DERIVED_OBSERVATIONS. The DERIVED_OBSERVATIONS block is optional but is almost always used. The four blocks must be specified in order.

Any line containing only whitespace will be ignored. Any line whose first non-whitespace character is "#" will be treated as a comment.

Each block is described below using the following conventions:

Keywords are written in ALL CAPITAL LETTERS;

Optional instructions are enclosed in [square brackets];

Values to be specified by the user are enclosed in <angled brackets>.

OPTIONS Block

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 non-blank and non-comment 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 will contain the simulated values extracted from the MODFLOW output file or files. Each line in the VALUES file will contain 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.

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

OBSERVATION_FILES Block

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

END OBSERVATION_FILES

Explanations:

Each non-blank, non-comment 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

IDENTIFIERS Block

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 to observed values or they may be 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]]

...

ID <identifier>

[LOCATION <x> <y>]

OBSNAME <Observation_name> <observation_time> [PRINT]

[OBSNAME <Observation_name> <observation_time> [PRINT]]

END IDENTIFIERS

Explanations:

ID is a keyword used to indicated 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 will specify 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 will interpolate 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 will be used. If the observation time is after the last recorded observation time, Mf6ObsExtractor will ignore it.

PRINT in an optional keyword. If included, the <Observation_name> and simulated value will be printed to the extracted values file or instructions for reading the <Observation_name> and simulated value will be written to the instruction file. Printing the name and value implies that they will be used directly 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 will be 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

DERIVED_OBSERVATIONS Block

Purpose:

The DERIVED_OBSERVATIONS block is used to define 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 will specify an observation name.

PRINT in an optional keyword. If included, the <Observation_name> and simulated value will be printed to the extracted values file or instructions for reading the <Observation_name> and simulated value will be written to the instruction file. Printing the name and value implies that they will be used directly 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 will be 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.

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 the names of one to four previously defined <Observation_name>s, each of which has a location associated with it.

<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> will be 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 H7_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