DTOB - Drain Return Observation Package

Abbreviation in Name file

DTOB

Purpose

The Drain Return Observation input file allows observation of flows in the Drain Return package.

Documentation

•	Banta, E.R., 2000, MODFLOW-2000, the U.S. Geological Survey Modular Ground-Water Model - Documentation of Packages for Simulating Evapotranspiration with a Segmented Function (ETS1) and Drains with Return Flow (DRT1): U.S. Geological Survey Open-File Report 00-466, 127 p.

•	release.txt

Related Packages

•	Head-Dependent Flux Boundary packages

•	Drain Return package

•	Drain package

Supported in

MODFLOW-2000

Other Notes

The Drain Return package must be used in models in which the Drain Return Observation input file is used.

Input Instructions

Input for the file used to specify flow observations using the DRT1 Package is read from a file that is specified with “DTOB” as the file type listed in the name file.

MODFLOW allows occurrences of the same head-dependent boundary type in a single finite-difference cell. For example, two canals represented by the Drain Package may cross an area such that they would be represented using the same finite difference cell, as designated by its layer, row, and column. Hence, that layer, row, and column would be listed twice in the Drain Package input file.

To accumulate the information needed to define the simulated equivalent of an observation, OBS uses an observation cell list from the applicable OBS input file, which defines an observation cell group, and additional information specified in the corresponding Groundwater Flow Process input file. The information for each cell is accumulated by matching cells listed in the Observation Process input file with those listed in the Groundwater Flow Process input file. For the General-Head Boundary, Drain, and River Packages documented in this work, features match when the cell’s layer, row, and column match. As long as the cell occurs only once in each list of cells, no problem occurs. If the list of cells used to define the observation cell group includes a feature at a cell where more than one feature is defined for the stress period in which the observation occurs in the Groundwater Flow input file for the same package, a procedure is needed to ensure that the correct feature is included in the simulated equivalent. In OBS, the following sequential matching procedure is used.

If a cell is listed once in the observation cell group, the simulated equivalent for the observation includes flow calculated only for the first occurrence of the cell, as listed in the Groundwater Flow Process input file for the package of concern for the stress period in which the observation occurs. Note that the stress period in which the observation occurs may be the reference stress period for the observation, or a later stress period, depending on the length of the reference stress period and the values of the time-offset multiplier and the variable TOFFSET. The listing order of cells in the Groundwater Flow Process input file is determined as follows: all non-parameter cells are listed before all parameter-controlled cells for a given stress period, and the order in which parameters are listed in the head-dependent boundary flow input file for each stress period determines the listing order of parameter-controlled cells. Within the list of cells controlled by a parameter, the order is determined by the cell list in the parameter definition specified near the top of the Groundwater Flow Process input file.

When a cell in an observation cell group is to be associated with the second or later occurrence of the cell in the Groundwater Flow Process input for a given stress period, the observation cell group needs to include two or more occurrences of the cell, where the number of occurrences corresponds to the sequential occurrence of the feature sought. Occurrences of the cell for which the flow calculated by the Groundwater Flow Process is not to contribute to the flow observation need to be specified with FACTOR=0.0 (see preceding sections for explanation of FACTOR). For each observation cell group, the program starts at the first cell listed for the stress period in the Groundwater Flow Process input file and searches for a match for the first cell in the observation cell group. After a match is found, appropriate calculations are done and the search for a match for the next cell in the observation cell group begins, starting at the feature following the feature matching the previous cell in the observation cell group. When the end of the list for the stress period in the Groundwater Flow Process input file is reached, the search continues at the beginning of the list. This can be confusing and care is needed to obtain the desired results. Searching and matching continues in this fashion until all cells in the observation cell group are matched. For the next observation cell group, the search starts at the beginning of the list for the stress period in the Groundwater Flow Process input file.

Understanding this search logic is necessary when determining the order in which cells are listed in an observation cell group to ensure that observation cells are matched as intended with features listed for the Groundwater Flow Process. When the features simulated by a particular package change from one stress period to the next, the list of cells in an observation cell group may not apply appropriately to both stress periods. In this situation, multiple cell groups may need to be defined to specify flow observations in different stress periods.

As an example, consider a model for an area where a series of springs discharge water from intervals at different elevations in an aquifer. For this model, the Drain Package is used and three drain features are specified in each of three finite-difference cells, for a total of nine features. All features are defined using parameters. One parameter is used to simulate three drain features, in rows 5, 6, and 7 of column 6; the elevations of these drain features are 20, 22, and 24 in this model. A second parameter is used to simulate drain features in the same three cells, each having an elevation of 30. A third parameter is used to simulate drain features in the same three cells; the elevation is 45 at the first two cells, and 47 at the third cell. For this model, the Groundwater Flow Process Drain Package input file, listed with file type DRN in the name file, is as follows:

# DRN input file

parameter 3 9 Item 1: npdrn mxl

10 0 Item 2: mxactd idrncb drn-low drn

10.0 3 Item 3: parnam partyp parval nlst

1 5 6 20 1.0 Item 4: lay row col elev condfact

1 6 6 22 1.0 Item 4: lay row col elev condfact

1 7 6 24 1.0 Item 4: lay row col elev condfact drn-med drn

1.0 3 Item 3: parnam partyp parval nlst

1 5 6 30 1.0 Item 4: lay row col elev condfact

1 6 6 30 1.0 Item 4: lay row col elev condfact

1 7 6 30 1.0 Item 4: lay row col elev condfact drn-high drn

10.0 3 Item 3: parnam partyp parval nlst

1 5 6 45 1.0 Item 4: lay row col elev condfact

1 6 6 45 1.0 Item 4: lay row col elev condfact

1 7 6 47 1.0 Item 4: lay row col elev condfact

0 3 Item 5: itmp np

drn-low Item 7: Pname

drn-med Item 7: Pname

drn-high Item 7: Pname

Observations of flow from the springs are represented such that the drain features in rows 5 and 6 at elevations 20 and 22 are associated with observations named D-low-5 and D-low-6, respectively; all the drain features in row 7 are together associated with an observation named D-7, the drain features in rows 5 and 6 at elevation 30 are together associated with an observation named D-med-56, and the springs in rows 5 and 6 at elevation 45 are associated with an observation named D-high-56. The following DROB file correctly associates the five observations with the nine drain features:

# DROB input file

5 15 5 0 Item 1: NQDR NQCDR NQTDR IUDROBSV

1 Item 2: TOMULTDR

1 1 Item 3: NQOBDR NQCLDR D-low-5

1 0.0 -276. Item 4

1 5 6 1.0 Item 5: LAY ROW COL FACTOR

1 1 Item 3: NQOBDR NQCLDR

D-low-6 1 0.0 -273. Item 4

1 6 6 1.0 Item 5: LAY ROW COL FACTOR

1 3 Item 3: NQOBDR NQCLDR D-7

1 0.0 -321. Item 4

1 7 6 1.0 Item 5: LAY ROW COL FACTOR

1 4 Item 3: NQOBDR NQCLDR

D-med-56 1 0.0 -35. Item 4

1 5 6 0.0 Item 5: LAY ROW COL FACTOR

1 6 6 0.0 Item 5: LAY ROW COL FACTOR

1 5 6 1.0 Item 5: LAY ROW COL FACTOR

1 6 6 1.0 Item 5: LAY ROW COL FACTOR

1 6 Item 3: NQOBDR NQCLDR

D-high-56 1 0.0 -50. Item 4

1 5 6 0.0 Item 5: LAY ROW COL FACTOR

1 6 6 0.0 Item 5: LAY ROW COL FACTOR

1 5 6 0.0 Item 5: LAY ROW COL FACTOR

1 6 6 0.0 Item 5: LAY ROW COL FACTOR

1 5 6 1.0 Item 5: LAY ROW COL FACTOR

1 6 6 1.0 Item 5: LAY ROW COL FACTOR

If there are multiple head-dependent boundaries for a package in the same cell, the search for cells conducted by the Observation Process requires special attention when creating the parameters that define the boundaries. In some situations, it will be necessary to (1) include cells in the flow package that have a conductance multiplier set to zero and (2) use time-varying parameters and instances, which are described by Harbaugh (2005).

To understand the problem and solution, consider an example using the Drain Package of the Groundwater Flow Process. In this example, there are three drains defined in a single cell. Each drain has a different parameter defining its conductance, and the drains are active at different times in the course of three stress periods. One drain and its parameter is used in stress periods 1 and 2. The second is used in stress periods 2 and 3. The third is used in stress periods 1 and 3. The input file below correctly defines the drains.

PARAMETER 2 6 # DataSet 1: PARAMETER NPDRN MXL

3 9 # DataSet 2: MXACTD IDRNCB

DRN_1 DRN 1.0 1 # Data Set 3: PARNAM PARTYP Parval NLST

1 1 1 1.0 1.0 # Data Set 4b: Layer Row Column Elevation Condfact

DRN_2 DRN 2.0 1 # Data Set 3: PARNAM PARTYP Parval NLST

1 1 1 2.0 2.0 # Data Set 4b: Layer Row Column Elevation Condfact

DRN_3 DRN 3.0 1 # Data Set 3: PARNAM PARTYP Parval NLST

1 1 1 3.0 3.0 # Data Set 4b: Layer Row Column Elevation Condfact

0 2 # Data Set 5: ITMP NP Stress period 1

DRN_1 # Data Set 7: PARNAM

DRN_3 # Data Set 7: PARNAM

0 2 # Data Set 5: ITMP NP Stress period 2

DRN_1 # Data Set 7: PARNAM

DRN_2 # Data Set 7: PARNAM

0 2 # Data Set 5: ITMP NP Stress period 3

DRN_2 # Data Set 7: PARNAM

DRN_3 # Data Set 7: PARNAM

If observations are defined using these three drains, it would not be possible to define some perfectly reasonable sets of observations correctly. The drain defined by the second parameter (DRN_2) is the second drain in the cell in stress period 2 but it is the first drain in the cell in stress period 3. That makes it impossible to define an observation for the drain in the second parameter in both the second and third stress period. If what is now the second parameter were listed first, the same problem would arise with one of the other parameters. To solve this problem, insert zero-conductance multiplier drain cells into the parameter definition in the Drain Package input file using instances. The example below illustrates how to do this. For each parameter, two instances are defined. For each parameter, the instance named "inactive" includes Condfact equals zero. That instance is used for the stress periods in which the drain is inactive.

Because each drain is in the same order in all the stress periods, drain observations can be defined correctly with the revised input file.

PARAMETER 3 6 # DataSet 1: PARAMETER NPDRN MXL

3 9 # DataSet 2: MXACTD IDRNCB Option

DRN_1 DRN 1.0 1 INSTANCES 2 # Data Set 3: PARNAM PARTYP Parval NLST INSTANCES NUMINST

Active # Data Set 4a: INSTNAM (Parameter instance for stress periods 1 and 2)

1 1 1 1.0 1.0 # Data Set 4b: Layer Row Column Elevation Condfact

Inactive # Data Set 4a: INSTNAM (Parameter instance for stress period 3)

1 1 1 1.0 0.0 # Data Set 4b: Layer Row Column Elevation Condfact

DRN_2 DRN 2.0 1 INSTANCES 2 # Data Set 3: PARNAM PARTYP Parval NLST INSTANCES NUMINST

Inactive # Data Set 4a: INSTNAM (Parameter instance for stress period 1)

1 1 1 2.0 0.0 # Data Set 4b: Layer Row Column Elevation Condfact

Active # Data Set 4a: INSTNAM (Parameter instance for stress periods 2 and 3)

1 1 1 2.0 2.0 # Data Set 4b: Layer Row Column Elevation Condfact

DRN_3 DRN 3.0 1 INSTANCES 2 # Data Set 3: PARNAM PARTYP Parval NLST INSTANCES NUMINST

Active # Data Set 4a: INSTNAM (Parameter instance for stress periods 1 and 3)

1 1 1 3.0 3.0 # Data Set 4b: Layer Row Column Elevation Condfact

Inactive # Data Set 4a: INSTNAM (Parameter instance for stress period 2)

1 1 1 3.0 0.0 # Data Set 4b: Layer Row Column Elevation Condfact

0 3 # Data Set 5: ITMP NP Stress period 1

DRN_1 Active # Data Set 7: PARNAM Iname

DRN_2 Inactive # Data Set 7: PARNAM Iname

DRN_3 Active # Data Set 7: PARNAM Iname

0 3 # Data Set 5: ITMP NP Stress period 2

DRN_1 Active # Data Set 7: PARNAM Iname

DRN_2 Active # Data Set 7: PARNAM Iname

DRN_3 Inactive # Data Set 7: PARNAM Iname

0 3 # Data Set 5: ITMP NP Stress period 3

DRN_1 Inactive # Data Set 7: PARNAM Iname

DRN_2 Active # Data Set 7: PARNAM Iname

DRN_3 Active # Data Set 7: PARNAM Iname

Data Set 0

[#Text]

Item 0 is optional and can include as many lines as desired. Each line needs to begin with the “#” character in the first column.

Text—is a character variable (79 characters) that starts in column 2. Any characters can be included in Text. The “#” character must be in column 1. Lines beginning with “#” are restricted to these first lines of the input file. Text is written to the LIST output file when the input file is read and provides an opportunity for the user to include information about the model both in the input file and the associated output file.

Data Set 1

NQDT NQCDT NQTDT (free format)

NQDT—is the number of cell groups for which drain-return flow observations are listed. A group consists of the drain-return cells needed to represent one flow measurement. Recipient cells are not included in NQDT.

NQCDT—is greater than or equal to the total number of drain-return cells in all cell groups. NQCDT must be greater than or equal to the sum of all |NQCLDT|. Recipient cells are not included in NQCDT.

NQTDT—is the total number of drain-return observations for all cell groups. NQTDT must equal the sum of all NQOBDT, which are specified in repetitions of item 3 in the DTOB input file.

Data Set 2

TOMULTDT EVFDT IOWTQDT (free format)

TOMULTDT—is the time-offset multiplier for drain-return observations [-- or T/T]. The product of TOMULTDT and TOFFSET must produce a time value in units consistent with other model input. TOMULTDT can be dimensionless or can be used to convert the units of TOFFSET to the time unit used in the simulation.

EVFDT—is the error variance multiplier for observations represented by the DRT1 Package, and is used to calculate the weights as described below in the explanation of STATISTIC. EVFDT makes it easy to change the weights uniformly for all flow observations represented using the DRT1 Package.

IOWTQDT—is a flag that indicates that the variance-covariance matrix on drain-return flow observations is to be read into array WTQ of item 7. If IOWTQDT equals zero, weights are calculated using STATISTIC of item 4; if it is greater than zero, items 6 and 7 are read and used to calculate the weights.

Read items 3, 4, and 5 for each of NQDT groups of cells for which flow observations are to be specified for features simulated with the DRT1 Package.

Data Set 3

NQOBDT NQCLDT (free format)

NQOBDT—is the number of times at which flows are observed for the group of cells.

NQCLDT—is a flag, and the absolute value of NQCLDT is the number of drain-return cells in the group. If NQCLDT is less than zero, FACTOR = 1.0 for all cells in the group. Recipient cells are not included in NQCLDT.

Data Set 4

OBSNAM IREFSP TOFFSET HOBS STATISTIC STAT-FLAG PLOT-SYMBOL (free format)

Read item 4 for each of NQOBDT observation times for this group of cells. STATISTIC and STAT-FLAG are ignored if IOWTQDT > 0.

OBSNAM—is a string of 1 to 12 non-blank characters used to identify the observation.

IREFSP—is the reference stress period to which observation times are referenced. The reference point is the beginning of the stress period.

TOFFSET—is the time offset of the observation from the beginning of stress period IREFSP [T]. TOFFSET must be in units such that the product of TOMULTDT and TOFFSET is in time units consistent with other model input. TOFFSET and TOMULTDT from the DTOB file and values of PERLEN, NSTP, and TSMULT from the DIS file (Harbaugh and others, 2000) are used to determine the stress period, time step, and time during the time step for the observation. To specify that an observation is for a steady-state model solution, specify IREFSP as the stress-period number of the steady-state stress period, and specify TOFFSET such that TOMULTDT*TOFFSET is less than or equal to PERLEN for the stress period; if PERLEN is zero, set TOFFSET to zero. If the observation falls within a time step, the simulated equivalent is calculated by linearly interpolating between values for the beginning and end of the time step. If the first stress period is transient and the observation falls within the first time step, the simulated equivalent from the end of the time step is used because no flow from the beginning of the time step is available for interpolation.

HOBS—is the observed drain-return-boundary flow [L3/T]. For the DRT1 Package, only negative values of HOBS are expected. Negative values indicate flow out of the groundwater system.

STATISTIC—is the value from which the weight for the observation is calculated as determined using STAT-FLAG.STATISTIC is ignored if IOWTQDT is greater than zero, in which case WTQ of item 7 is used to define the weighting.

STAT-FLAG—is a flag identifying what STATISTIC is and how the weight is calculated.

•	STAT-FLAG is ignored if IOWTQDT is greater than zero.

•	STAT-FLAG = 0, STATISTIC is a scaled variance [(L3/T)2], weight = 1/(STATISTIC × EVFDT)

•	STAT-FLAG = 1, STATISTIC is a scaled standard deviation [L3 /T], weight = 1/(STATISTIC2 × EVFDT)

•	STAT-FLAG = 2, STATISTIC is a scaled coefficient of variation [dimensionless], weight = 1/[(STATISTIC × HOBS)2 × EVFDT]

PLOT-SYMBOL—is an integer that will be written to output files intended for graphical analysis to allow control of the symbols used when plotting data.

Data Set 5

Layer Row Column Factor (free format)

Read item 5 for each cell in this group; the number of cells equals the absolute value of NQCLDT from item 3.

LAYER—is the layer index of a drain cell included in the cell group.

ROW—is the row index of a drain cell included in the cell group.

COLUMN—is the column index of a drain cell included in the cell group.

FACTOR—is the portion of the simulated drain flow in the cell that is included in the total simulated drain flow for this cell group (fn of eq. 9).

Read items 6 and 7 if IOWTQDTQDG > 0.

Data Set 6

FMTIN IPRN (free format)

FMTIN—is the Fortran format to be used in reading each line of the variance-covariance matrix used to calculate the weighting. The format needs to be enclosed in parentheses and needs to accommodate real numbers.

IPRN—is a flag identifying the format in which the variance-covariance matrix is printed. If IPRN is less than zero, the matrix is not printed. Permissible values of IPRN and corresponding formats are:

Output requires more than 80 columns		Output requires 80 columns or less
IPRN	FORMAT	IPRN	FORMAT
1	10G12.3	6	5G12.3
2	10G12.4	7	5G12.4
3	9G12.5	8	5G12.5
4	8G13.6	9	4G13.6
5	8G14.7	10	4G14.7

Data Set 7

WTQ(1,1), WTQ(1,2), WTQ(1,3), ... , WTQ(1,NQTDR) (format: FMTIN)

WTQ(2,1), WTQ(2,2), WTQ(2,3), ... , WTQ(2,NQTDR)

...

WTQ(NQTDR,1), WTQ(NQTDR,2), WTQ(NQTDR,3), ... , WTQ(NQTDR,NQTDR)

WTQ—is an NQTDR by NQTDR array containing the variance-covariance matrix on drain observations [(L3/T)2]. For elements WTQ(I,J), if I ≠ J, WTQ(I,J) is the covariance between observations I and J; if I = J, WTQ(I,J) is the variance of observation I. Note that the variance-covariance matrix is symmetric, but the entire matrix (upper and lower parts) must be entered.

Help URL: https://www.yourdomain.com/help/index.html?dtob.htm