Prepared in cooperation with the Colorado Water Conservation Board

MODFLOW-CDSS, a Version of MODFLOW-2005 with 

Modifications for Colorado Decision Support Systems

By Edward R. Banta

Open-File Report 2011–1213

U.S. Department of the Interior

U.S. Geological Survey
ii

U.S. Department of the Interior

KEN SALAZAR, Secretary

U.S. Geological Survey

Marcia K. McNutt, Director 

U.S. Geological Survey, Reston, Virginia: 2011

For product and ordering information:

World Wide Web: http://www.usgs.gov/pubprod

Telephone: 1-888-ASK-USGS

For more information on the USGS—the Federal source for science about the Earth,

its natural and living resources, natural hazards, and the environment:

World Wide Web: http://www.usgs.gov

Telephone: 1-888-ASK-USGS

Suggested citation:

Banta, E.R., 2011, MODFLOW-CDSS, a version of MODFLOW-2005 with modifications for Colorado 

Decision Support Systems: U.S. Geological Survey Open-File Report 2011–1213,19 p.

Any use of trade, product, or firm names is for descriptive purposes only and does not imply 

endorsement by the U.S. Government. 
iii

Preface

This report describes MODFLOW-CDSS, a three-dimensional, finite-difference 

groundwater-modeling program. MODFLOW-CDSS is based on MODFLOW-2005 (Harbaugh, 

2005) and includes modifications to fulfill needs identified by the Colorado Water Conservation 

Board. The modifications include a new Partition Stress Boundaries capability and an option to 

allow execution to continue when the selected solver fails to converge. The Partition Stress 

Boundaries capability also supports the Local Grid Refinement (Mehl and Hill, 2005, 2007, 2010) 

capability.

The performance of the program has been tested in a variety of test simulations. Future 

uses, however, might reveal errors that were not detected in the test simulations. Users are 

requested to notify the U.S. Geological Survey of any errors found in this document or the 

computer program by using the email address available at the Web address below. Updates might 

occasionally be made to both this document and to the program. Users can download the software 

or check for updates on the Internet at http://co.water.usgs.gov/projects/modflowcdss/. 
iv

Contents

Abstract.......................................................................................................................................................................... 1

Introduction.................................................................................................................................................................... 1

Purpose and Scope ....................................................................................................................................................... 2

Partition Stress Boundaries Capability........................................................................................................................... 3

Input Instructions for the Groundwater Flow Process................................................................................................. 4

Input Instructions for the Observation Process........................................................................................................... 4

Use of PSB with Local Grid Refinement..................................................................................................................... 5

Output ........................................................................................................................................................................ 5

Option to Override Solver Convergence Failure ............................................................................................................ 6

Input Instructions........................................................................................................................................................ 7

Output ........................................................................................................................................................................ 7

Distribution and Compiling............................................................................................................................................. 9

Acknowledgments........................................................................................................................................................ 10

References Cited......................................................................................................................................................... 10

Appendix 1: Programmer Documentation for the Partition Stress Boundaries Capability ............................................ 12

Appendix 2: Partition Stress Boundaries Example....................................................................................................... 15

Figures

 1. Excerpt from a name file showing partitions and partition identifiers for 

Groundwater-Flow-Process input files ................................................................................................................. 4

 2. Excerpt from a name file showing partitions and partition identifiers associating 

Observation-Process with Groundwater-Flow-Process input files........................................................................ 5

 3. Example Basic Package input file showing use of OVERRIDE_CONVERGENCE_FAILURE 

option ................................................................................................................................................................... 7

 4. Excerpt from MODFLOW-CDSS listing file showing output generated when convergence failure is 

overridden............................................................................................................................................................ 8

2–1. Model grid and features for the Partition Stress Boundaries example ................................................................ 16

2–2. Name file for the Partition Stress Boundaries example....................................................................................... 17

2–3. Selected output for the Partition Stress Boundaries example ............................................................................. 18

2–4. Volumetric flow rates for water-budget components of the Partition Stress Boundaries example....................... 19

Tables

1. Packages and file types supported by the Partition Stress Boundaries capability .................................................... 3

1–1. Subroutines of the Partition Stress Boundaries (PSB)........................................................................................ 14
v 

Abbreviations

CDSS Colorado Decision Support Systems

CWCB Colorado Water Conservation Board

ET Evapotranspiration

GMG Geometric Multigrid Solver

GWF Groundwater Flow (Process)

LGR Local Grid Refinement

PSB Partition Stress Boundaries 

URL Universal Resource Locator
1 

MODFLOW-CDSS, a Version of MODFLOW-2005 with 

Modifications for Colorado Decision Support Systems

By Edward R. Banta

Abstract

MODFLOW-CDSS is a three-dimensional, finite-difference groundwater-flow model based 

on MODFLOW-2005, with two modifications. The first modification is the introduction of a 

Partition Stress Boundaries capability, which enables the user to partition a selected subset of 

MODFLOW’s stress-boundary packages, with each partition defined by a separate input file. 

Volumetric water-budget components of each partition are tracked and listed separately in the 

volumetric water-budget tables. 

The second modification enables the user to specify that execution of a simulation should 

continue despite failure of the solver to satisfy convergence criteria. This modification is 

particularly intended to be used in conjunction with automated model-analysis software; its use is 

not recommended for other purposes. 

Introduction

This report documents MODFLOW-CDSS, a three-dimensional, finite-difference 

groundwater-flow model application based on MODFLOW-2005 (Harbaugh, 2005) with 

modifications designed to support needs related to development of groundwater models for

Colorado’s Decision Support Systems (CDSS) (Colorado Water Conservation Board and Colorado 

Division of Water Resources, 2005). One need is to be able to enter and separately track 

components of stresses on a groundwater system when the components are to be simulated using 

the same MODFLOW-2005 package. A common approach in this situation is to modify the 

MODFLOW (MODFLOW-2005 or earlier version) source code to add one or more essentially 

identical copies of one (or more) of MODFLOW’s packages; this approach was used, for example, 

by Danskin and others (2006) to track multiple components of recharge and of pumping from wells. 

When this approach is used, the source code needs to be modified and recompiled to accommodate 

each new stress component. A more convenient approach would be to develop a capability to 

allow simulated stresses to be partitioned as desired by the modeler without requiring additional 

revisions to the source code. A second need relates to an ability to make repeated MODFLOW 

simulations during automated parameter estimation, during which a large number of simulations 

are run with a potentially widely varying set of model-input, or parameter, values. In this situation, 

model convergence can be difficult to obtain for all parameter sets generated during parameter 

estimation. An option to override convergence failure, designed to be used in automated parameter 

estimation, would be a valuable addition to MODFLOW. 

To address these needs, MODFLOW-CDSS includes two modifications: (1) a Partition 

Stress Boundaries (PSB) capability and (2) an option to override solver convergence failure and to 
2 

continue execution. The first modification allows the partitioning of simulated stresses by 

separating input of any of the supported packages into multiple input files, where each input file 

defines a partition. The second modification is designed to facilitate automated parameter 

estimation by allowing execution to continue when solver closure criteria are not met for one or 

more time steps. 

Purpose and Scope

In 2008, the Colorado Water Conservation Board (CWCB) identified two needs related to 

the use of MODFLOW-2005 (Harbaugh, 2005) in groundwater-modeling components of CDSS. 

The first was a need to categorize and track components of various types of stresses on aquifers; the 

second was a need to enable MODFLOW-2005 to continue execution despite solver 

nonconvergence when model runs are executed by automated model-analysis software. 

In MODFLOW-2005, a variety of Packages (for example, the River, Drain, Recharge, and 

Evapotranspiration Packages) can be used to define various types of boundary conditions in the 

finite-difference system of equations that is set up to simulate the flow of groundwater in an aquifer 

system. In the original MODFLOW-2005 software, all input for boundaries of a given type of 

stress was specified in a single input file. For example, input for all river boundaries would be 

specified in a single River-Package input file. Output from a MODFLOW-2005 run would then 

include one or more volumetric water-budget tables in which all River-Package stresses would be 

summarized, with one entry that would include all river flow into the groundwater system and one 

entry for all river flow out of the groundwater system. The CWCB identified a need to categorize 

and track user-specified components of each stress package to facilitate interpretation of model 

stresses and water-budget components. The PSB capability described in this report addresses this 

need.

When performing various automated model analyses (for example, parameter estimation) a 

large number of model simulations are commonly required to obtain desired results. During the 

course of an analysis, numeric parameter (model-input) values are manipulated, the model is 

executed, and model results are analyzed, often in an iterative fashion. Parameter values may vary 

widely during the analysis. It can be difficult to assign values to variables that control solver 

performance in a way that will enable the solver to reach convergence in a reasonable amount of 

computational time for all parameter sets that are used in an analysis. In the original version of 

MODFLOW-2005, execution stops if convergence is not achieved at a time step. Model-analysis 

programs generally are not designed to handle situations where the simulation does not run to 

completion. Precise model results are generally desirable throughout the course of parameter 

estimation by nonlinear regression (Yager, 2004). However, depending on solver convergence 

criteria and individual model setup, model results that are sufficiently precise for early parameterestimation iterations may be obtained even when solver convergence is not achieved. One way to 

evaluate the precision of model results in the absence of solver convergence is to look at the error 

listed at the end of the volumetric water-budget table for each time step. In particular, achieving 

solver convergence is likely to be less important during early and intermediate parameterestimation iterations than it is during the final iterations of a parameter-estimation analysis. An 

option to override solver convergence failure and continue execution was implemented to address 

this issue. It is important to recognize the potential for production of highly inaccurate model 

results when this option is used, and to avoid its use in any situation in which accurate model 

results are needed.
3 

The PSB capability was implemented in two programs, MODFLOW-CDSS and 

MODFLOW-LGR-CDSS, which are available at the URL listed in the Preface of this report. 

MODFLOW-CDSS also supports the option to override solver convergence failure. MODFLOWLGR-CDSS implements Local Grid Refinement (LGR; Mehl and Hill, 2005, 2007, 2010). 

Partition Stress Boundaries Capability

When modeling groundwater flow in regional aquifer systems, modelers are often 

confronted with a need to track components of the water budget in greater detail than is provided 

by the set of stress-boundary packages of MODFLOW-2005. For example, it may be desired to 

distinguish between the evapotranspiration (ET) rates of different vegetation types which have 

different ET extinction depths. In this situation MODFLOW-2005 does not make it easy for the 

modeler to distinguish between the simulated ET rates of a variety of vegetation types. The 

Riparian evapotranspiration (RIP-ET) methodology (Maddock and Baird, 2002; Baird and 

Maddock, 2005) provides this and more sophisticated capabilities for simulating ET in riparian 

areas, but it does not address stresses other than ET. In other situations, modelers and waterresources managers may find it convenient to track water-budget components within MODFLOW 

as an alternative to writing project-specific pre- and postprocessor utilities for manipulating model 

input and analyzing model output. 

The PSB capability was developed to allow modelers to partition model input to identify 

and track components of stresses with a degree of detail greater than that of the package-based 

categorization of MODFLOW-2005. When a stress package is partitioned using PSB, partitions are 

defined by the use of multiple input files for supported packages. For example, users may find it 

advantageous to use PSB to track different sources of recharge, different components of ET, or 

pumping rates for different categories of wells. The PSB capability supports partitioning in the 

packages listed in table 1. Another potential use of PSB would be to simplify the task of activating 

or deactivating simulation of specific components of stresses. If partitions are suitably defined, 

only the name file would need to be edited to activate or deactivate a selected component. 

Table 1. Packages and file types supported by the Partition Stress Boundaries capability. 

Package Name File Type for Name File Reference

Groundwater Flow Process

Drain Package DRN Harbaugh (2005)

Drain Return Package DRT Banta (2000)

Evapotranspiration Package EVT Harbaugh (2005)

Evapotranspiration Segments Package ETS Banta (2000)

General Head Boundary Package GHB Harbaugh (2005)

Recharge Package RCH Harbaugh (2005)

River Package RIV Harbaugh (2005)

Well Package WEL Harbaugh (2005)

Observation Process

Drain Package DROB Harbaugh and Hill (2009)

General Head Boundary Package GBOB Harbaugh and Hill (2009)

River Package RVOB Harbaugh and Hill (2009)
4 

Input Instructions for the Groundwater Flow Process

The PSB capability of MODFLOW-CDSS is invoked by entering any of the file types listed 

in table 1 in a MODFLOW-CDSS name file multiple times. Each entry should identify an input 

file appropriately prepared for the associated package; no modifications to stress-package input 

files are required to make use of the PSB capability. Each entry of a Groundwater Flow (GWF) 

Process file type listed multiple times will be treated as a partition of the corresponding package. 

Each partition can be identified by a partition identifier (a text string of 1 to 16 characters) 

following the file name in the name file. The 16-character limit allows the partition identifier to be 

listed in its entirety in the volumetric water-budget tables. The identifier also is written to the 

binary cell-by-cell flow file(s) (Harbaugh, 2005) in the position occupied by the 16-character 

TEXT variable. If a file type is listed only once, it is handled by the corresponding package, not by 

PSB. An example excerpt from a name file is shown in figure 1.

...

RIV 21 Allegheny.riv Allegheny

RIV 22 Monongahela.riv Monongahela

RIV 23 Ohio.riv "Ohio River"

RCH 24 precip.rch Precip_RCH

RCH 25 irrig.rch Irrig_RCH

...

Figure 1. Excerpt from a name file showing partitions and partition identifiers for Groundwater-Flow-Process 

input files.

In this example, these entries would cause PSB to create three River-Package partitions and two 

Recharge-Package partitions. The River-Package partitions would be labeled in the volumetric 

water-budget tables and cell-by-cell flow file(s) with the partition identifiers “Allegheny,”

“Monongahela,” and “Ohio River.” Note the (required) use of quotation marks in the name file to 

specify a partition identifier with an embedded space character. Similarly, the Recharge-Package 

partitions would be labeled “Precip_RCH” and “Irrig_RCH.” 

Input Instructions for the Observation Process

When flow observations are specified for packages that are partitioned using PSB, observations 

must be specified in files that correspond to the partitions defined by the GWF-Process input files. 

The partition identifier used for each partition is then also used with the appropriate ObservationProcess input file to enable PSB to associate observations with the correct partition. The 

association is based on a case-insensitive match between partition identifiers listed for the 

Observation-Process input file and for the GWF-Process input file. Like partition identifiers for 

GWF-Process files, partition identifiers for Observation-Process input files need to be from 1 to 16 

characters in length. When the Observation Process is used with a partitioned stress package, the 

partition identifier for each GWF-Process input file needs to be unique among partition identifiers 

for all GWF-Process input files for that stress package; this requirement ensures correct association 

between each Observation-Process input file and its corresponding GWF-Process input file. 
5 

Observation-Process input files are prepared as described in Harbaugh and Hill (2009). Figure 2

illustrates the use of partition identifiers to associate Observation-Process input files for RiverPackage observations with River-Package partitions of the Groundwater Flow Process. Definition 

of observations based on stress boundaries included in multiple partitions is not supported. This 

restriction means, for example, that the Observation Process cannot be used to define a flow 

observation based on a set of river cells where some river cells in the set are defined in 

Allegheny.riv and other river cells in the set are defined in Ohio.riv (fig. 2). 

...

RIV 21 Allegheny.riv Allegheny

RIV 22 Monongahela.riv Monongahela

RIV 23 Ohio.riv "Ohio River"

RVOB 31 Allegheny.rvob Allegheny

RVOB 32 Monongahela.rvob Monongahela

RVOB 33 Ohio.rvob "Ohio River"

...

Figure 2. Excerpt from a name file showing partitions and partition identifiers associating ObservationProcess with Groundwater-Flow-Process input files.

Use of PSB with Local Grid Refinement

The program MODFLOW-LGR-CDSS, which is provided in the distribution file at the 

URL listed in the Preface of this report, supports both LGR (Mehl and Hill, 2005, 2007, 2010) and 

PSB. PSB is activated in MODFLOW-LGR-CDSS the same way it is activated in MODFLOWCDSS: by listing multiple input files for supported stress packages in the name file(s) (figs. 1 and 

2) listed in an LGR control file. PSB can be activated in any combination of parent and child grids. 

Partition identifiers for each grid are internally treated as being independent of partition identifiers 

for all other grids. As a result, partition identifiers may be reused in different grids, if desired. 

Another result is that partitions for Observation-Process files can only be matched with partitions 

for GWF-Process files listed in the name file for the same grid.

Output

When PSB is activated by inclusion of multiple GWF-Process input files with a given 

stress-boundary type in the name file, PSB writes a message to the listing file. The message

indicates that PSB has been activated and includes a table showing the package, unit number, 

partition identifier, and input file associated with each partition. The unit numbers in this table can 

be used to associate partitions with output generated by the “Allocate and Read” procedure of the 

stress packages for each input file. Each volumetric water-budget table lists entries for each 

partition. Also, the cell-by-cell flow files referenced in stress-package input (for example, IRIVCB 

of the River Package) will have partition identifiers in place of the default identifier associated with 

the stress package. For example, if River-Package output is to be written to a cell-by-cell flow file 

for the three River Package partitions in the example above to one cell-by-cell flow file, the file 

will have multiple River-Package entries for each time step for which output is requested. Instead 
6 

of one entry with the identifier “RIVER LEAKAGE,” the file will contain three entries with 

identifiers “Allegheny,” “Monongahela,” and “Ohio River.” For this reason, post-processing 

programs that rely on the original values of the TEXT identifiers in the cell-by-cell flow file for 

analytical or reporting purposes may need to be modified to handle a cell-by-cell flow file 

containing variable TEXT identifiers written by MODFLOW-CDSS for different partitions. 

Zonebudget (Harbaugh, 1990), a program for calculating zone-based water budgets using results 

from MODFLOW, does not rely on the original identifiers; instead, it identifies water-budget 

components by the 16-character TEXT identifiers read from the cell-by-cell flow files. Therefore, 

Zonebudget requires no modification to work with a cell-by-cell flow file generated by 

MODFLOW-CDSS. Similarly, GW_Chart (Winston, 2000), a program for graphical analysis of 

model output, identifies water-budget components and requires no modification to work with 

output generated by MODFLOW-CDSS. When either GW_Chart or Zonebudget reads data from a 

cell-by-cell flow file containing partitions, water-budget components are identified in output by 

partition identifier. As is the case when either Zonebudget or GW_Chart is used with MODFLOWLGR (Mehl and Hill, 2005, 2007, 2010), a separate analysis is required for each parent or child grid 

for which a zone-based or graphical water-budget analysis is desired for a MODFLOW-LGRCDSS simulation.

Option to Override Solver Convergence Failure

When a large number of model runs are to be made by an automated model-analysis 

program, in which parameter (model-input) values may vary widely, difficulty may be encountered 

in determining solver input that will consistently achieve convergence for all model time steps in an 

acceptable execution time. This problem is addressed by MODFLOW-2000 (Harbaugh and others, 

2000; Hill and others, 2000), which, when used in parameter-estimation mode, does not stop 

execution on solver nonconvergence. Doherty (2010) suggests modifying a model’s source code to 

read closure criteria from a separate file and then using a batch file to rewrite this file with 

increased closure criteria and repeat execution of the model if a model run fails to converge. When 

performing parameter estimation using UCODE_2005 (Poeter and others, 2005) or PEST (Doherty, 

2010), for early parameter-estimation iterations, acceptable progress in the parameter-estimation 

process often can be obtained even if the groundwater-flow equation solver does not achieve 

convergence. This is the situation for which the option to override convergence failure is designed; 

the use of this option for other purposes is not encouraged. Users are reminded that calculated head 

values likely are not accurate within the head-closure criterion specified in solver input when 

closure criteria are overridden. Errors in calculated head also can result in errors in other quantities 

that depend on accurate head values. In particular, values of groundwater flow are dependent on 

calculated head values and will be in error if the head values are in error. Similarly, other 

simulated processes that depend on calculated heads, for example, particle tracking for advective 

transport, will be in error if the head values are in error.

When the option to override solver convergence failure is invoked, acceptability of the 

approximated solution of the groundwater-flow equation is the user’s responsibility. When 

convergence failure is overridden at one or more time steps, a summary of convergence failures is

written at the bottom of the listing file and provides a convenient way to quickly evaluate the 

degree to which convergence failure affects the volumetric water-budget balance. For each time 

step where convergence failure is overridden, the summary lists the percent discrepancy of the 

volumetric water-budget flow rates. These are the rate discrepancies calculated at each time step
7 

and printed at the bottom of the “rates for this time step” column of each volumetric water-budget 

table.

The OVERRIDE_CONVERGENCE_FAILURE option can be used regardless of the solver 

selected to solve the groundwater-flow equation. Convergence-failure override is independent of 

the logic an individual solver uses to determine convergence.

MODFLOW-LGR (Mehl and Hill, 2005, 2007, 2010) is programmed such that, when a 

simulation includes one or more child models, execution continues even if the solver does not reach 

convergence for the parent model or any child model, or if LGR iterations fail to converge in the 

specified number of iterations. MODFLOW-LGR-CDSS preserves this behavior. For this reason 

an option to override solver convergence failure is not needed in MODFLOW-LGR-CDSS. Note 

that if MODFLOW-LGR-CDSS is used to simulate a system that contains no child models, 

execution will stop if the solver fails to converge. 

Input Instructions

The option to override solver convergence failure is activated by entering 

“OVERRIDE_CONVERGENCE_FAILURE” in item 1 (Options) of the Basic Package input file 

(fig. 3). All other input is prepared as documented in Harbaugh (2005). 

FREE SHOWPROGRESS OVERRIDE_CONVERGENCE_FAILURE Item 1: options

CONSTANT 1 Item 2: IBOUND, layer 1

CONSTANT 1 Item 2: IBOUND, layer 2

CONSTANT 1 Item 2: IBOUND, layer 3

 -999.9 Item 3: HNOFLO

CONSTANT 100.0 Item 4: STRT, layer 1

CONSTANT 100.0 Item 4: STRT, layer 2

CONSTANT 100.0 Item 4: STRT, layer 3

Figure 3. Example Basic Package input file showing use of OVERRIDE_CONVERGENCE_FAILURE 

option.

Output

When OVERRIDE_CONVERGENCE_FAILURE is specified in Basic Package input as 

described above, a message is written to the listing file indicating that the 

OVERRIDE_CONVERGENCE_FAILURE option has been selected. If convergence is achieved 

for all time steps, no other output related to this option is generated. 

When OVERRIDE_CONVERGENCE_FAILURE is specified and solver convergence fails 

for one or more time steps, additional output is written to the listing file and to the screen. For each 

time step for which solver convergence fails and execution is allowed to continue, a warning 

message is written to the listing file indicating the time step and stress period in which convergence 

failed. In addition, at the bottom of the listing file, a summary of convergence failures is written, 

showing the stress period, time step, and percent discrepancy of flow rates for the volumetric water 

budget at the indicated time step. The summary of convergence failures is followed by a warning 

message noting the number of time steps for which solver convergence failed (fig. 4). A brief
8 

warning message showing the number of time steps for which solver convergence failed also is 

written to the screen.

Summary of convergence failures:

STRESS TIME VOLUMETRIC BUDGET FLOW RATES

PERIOD STEP PERCENT DISCREPANCY

 4 1 0.004

 4 2 0.004

 4 3 0.002

 4 4 0.004

 4 5 0.004

 4 6 0.007

 4 7 -0.735

 4 8 0.014

 4 9 0.017

!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!

!!!!!!!!!!!!!!!!!!!!!!!!! WARNING !!!!!!!!!!!!!!!!!!!!!!!!

!! !!

!! OVERRIDE_CONVERGENCE_FAILURE is in effect, and !!

!! solver failed to converge for 9 time step(s). !!

!! Calculated heads likely are not accurate within the !!

!! head-closure criterion specified in solver input. !!

!! Check above for acceptability of percent discrepancy !!

!! in volumetric budget of affected time step(s). !!

!! Search for "WARNING" in output above. Also see !!

!! summary of convergence failures immediately above. !!

!! !!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Figure 4. Excerpt from MODFLOW-CDSS listing file showing output generated when convergence failure is 

overridden.
9 

Distribution and Compiling

The compressed distribution file available for download from the URL listed in the Preface 

of this report contains executable files, source-code files, documentation, and input and output files 

for two example problems. When extracted, the distribution file generates several directories,

organized as follows: 

modflow-cdss

 bin 

 doc 

 src

 mf2005_cdss 

 mflgr_cdss

 test-out 

 psb 

 tc1huf_ncnvg 

 test-run

 psb 

 tc1huf_ncnvg 

The “bin” directory contains the executable files for MODFLOW-CDSS (mf2005_cdss.exe) 

and MODFLOW-LGR-CDSS (mflgr_cdss.exe). The “doc” directory contains documentation 

file(s). Each subdirectory under the “test-run” directory contains a batch file and input files 

required to run one example simulation. The “psb” subdirectory contains files for the Partition 

Stress Boundaries example presented in Appendix 2. The “tc1huf_ncnvg” subdirectory contains 

files that demonstrate the use of the OVERRIDE_CONVERGENCE_FAILURE option. Output 

files for each example simulation are in corresponding subdirectories under the “test-out” directory. 

When run, the example problems write output files into subdirectories of the test-run directory; the 

output files can be compared with the files distributed in the corresponding subdirectories of the 

test-out directory to demonstrate that the programs function as intended. 

The “src” directory contains two subdirectories: “mf2005_cdss” contains all source code 

needed to compile MODFLOW-CDSS, and “mflgr_cdss” contains all source code needed for 

MODFLOW-LGR-CDSS. These subdirectories contain both Fortran source-code files (with 

extensions “f” and “f90”) and C source-code files (with extensions “c” and “h”). Generally, users 

will not need to compile these programs; the executable files provided in the distribution can be 

used on computers that run the Microsoft Windows operating system (version XP or later). For 

other operating systems, the programs will need to be compiled. When compiling, if the Geometric 

Multigrid (GMG) solver (Wilson and Naff, 2004; Banta, 2006) is to be supported, the C sourcecode files need to be compiled with a C compiler and all Fortran files except “nogmg.f” need to be 

compiled with a Fortran-90 (or later) compiler. Alternatively, the programs can be compiled using 

only a Fortran compiler; however, the resulting executables will not support GMG. To compile the 
10 

programs using only a Fortran compiler, include file “nogmg.f” in the files to be compiled, and 

omit file “gmg7.f” and the C-language files.

Acknowledgments

Conversations with Steffen Mehl (USGS) and Mary Hill (USGS) encouraged the 

development of support for Local Grid Refinement (Mehl and Hill, 2005, 2007, 2010) as part of the 

development of the PSB capability. 

References Cited

Baird, K.J., and Maddock, Thomas, III, 2005, Simulating riparian evapotranspiration—A new 

methodology and application for groundwater models: Journal of Hydrology v. 312, p. 176–190, 

accessed April 4, 2011, at http://www.sciencedirect.com. 

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. 

(Also available at http://pubs.er.usgs.gov/pubs/ofr/ofr00466.) 

Banta, E.R., 2006, Modifications to MODFLOW boundary conditions and an adaptive-damping 

scheme for Picard iterations for a highly nonlinear regional model, in MODFLOW and more 

2006—Managing ground water systems, Golden, Colo., 2006, Proceedings: Golden, Colo., 

International Ground Water Modeling Center and Colorado School of Mines, p. 596–600. 

Colorado Water Conservation Board and Colorado Division of Water Resources, 2005, Colorado's 

Decision Support Systems: Denver, Colo., Colorado Division of Water Resources, accessed 

April 4, 2011, at http://cdss.state.co.us/DNN/default.aspxx. 

Danskin, W.R., McPherson, K.R., and Woolfenden, L.R., 2006, Hydrology, description of 

computer models, and evaluation of selected water-management alternatives in the San 

Bernardino area, California: U.S. Geological Survey Open-File Report 2005–1278, 178 p. (Also 

available at http://pubs.usgs.gov/of/2005/1278/.) 

Doherty, John, 2010, PEST model-independent parameter estimation user manual (5th ed.): 

[Brisbane, Australia], Watermark Numerical Computing, variously paginated, available on April 

13, 2011, at http://www.pesthomepage.org/Downloads.php. 

Harbaugh, A.W., 1990, A computer program for calculating subregional water budgets using 

results from the U.S. Geological Survey modular three-dimensional finite-difference groundwater model: U.S. Geological Survey Open-File Report 90–392, 46 p. (Also available online at 

http://water.usgs.gov/nrp/gwsoftware/zonebud3/ofr90392.pdf.) 

Harbaugh, A.W., 2005, MODFLOW-2005, the U.S. Geological Survey modular ground-water 

model—The ground-water flow process: U.S. Geological Survey Techniques and Methods, book 

6, chap. A16, variously paginated. (Also available at

http://pubs.er.usgs.gov/usgspubs/tm/tm6A16.) 

Harbaugh, A.W., Banta, E.R., Hill, M.C., and McDonald, M.G., 2000, MODFLOW-2000, the U.S. 

Geological Survey modular ground-water model—User guide to modularization concepts and the 

Ground-Water Flow Process: U.S. Geological Survey Open-File Report 00–92, 121 p. (Also

available at http://water.usgs.gov/nrp/gwsoftware/modflow2000/ofr00-92.pdf.) 

Harbaugh, A.W., and Hill, M.C., 2009, Observations in MODFLOW-2005—File OBS.pdf 

distributed with MODFLOW-2005: U.S. Geological Survey, 32 p. (Also available at 

http://water.usgs.gov/nrp/gwsoftware/modflow2005/modflow2005.html.) 
11 

Hill, M.C., Banta, E.R., Harbaugh, A.W., and Anderman, E.R., 2000, MODFLOW-2000, the U.S. 

Geological Survey modular ground-water model—User guide to the Observation, Sensitivity, and 

Parameter-Estimation Processes and three post-processing programs: U.S. Geological Survey 

Open-File Report 00–184, 209 p. (Also available at 

http://water.usgs.gov/nrp/gwsoftware/modflow2000/ofr00-184.pdf.) 

Maddock, Thomas, III, and Baird, K.J., 2002, A riparian evapotranspiration package for 

MODFLOW-96 and MODFLOW-2000: Tucson, Ariz., University of Arizona Research 

Laboratory for Riparian Studies, HWR No. 02–030, 50 p. 

Mehl, S.W., and Hill, M.C., 2005, MODFLOW-2005, The U.S. Geological Survey modular 

ground-water model—Documentation of shared node Local Grid Refinement (LGR) and the 

Boundary Flow and Head (BFH) Package: U.S. Geological Survey Techniques and Methods, 

book 6, chap. A12, 68 p. (Also available at 

http://water.usgs.gov/nrp/gwsoftware/modflow2005_lgr/mflgr.html.) 

Mehl, S.W., and Hill, M.C., 2007, MODFLOW-2005, The U.S. Geological Survey modular 

ground-water model—Documentation of the Multiple-Refined-Areas capability of Local Grid 

Refinement (LGR) and the Boundary Flow and Head (BFH) Package: U.S. Geological Survey 

Techniques and Methods, book 6, chap. A21, 13 p. (Also available at 

http://pubs.usgs.gov/tm/2007/06A21/.) 

Mehl, S.W., and Hill, M.C., 2010, MODFLOW-LGR—Modifications to the Streamflow-Routing 

Package (SFR2) to route streamflow through locally refined grids: U.S. Geological Survey 

Techniques and Methods, book 6, chap. A34, 15 p. (Also available at 

http://water.usgs.gov/nrp/gwsoftware/modflow2005_lgr/tm6a34.pdf.) 

Poeter, E.P., Hill, M.C., Banta, E.R., Mehl, Steffen, and Christensen, Steen, 2005, UCODE_2005 

and six other computer codes for universal sensitivity analysis, calibration, and uncertainty 

evaluation constructed using the JUPITER API: U.S. Geological Survey Techniques and 

Methods, book 6, chap. A11, 283 p. (Also available at 

http://pubs.er.usgs.gov/usgspubs/tm/tm6A11.) 

Wilson, J.D., and Naff, R.L., 2004, MODFLOW-2000, The U.S. Geological Survey modular 

ground-water model—GMG linear equation solver package documentation: U.S. Geological 

Survey Open-File Report 2004–1261, 47 p., available only online at 

http://pubs.water.usgs.gov/ofr2004-1261. 

Winston, R.B., 2000, Graphical User Interface for MODFLOW, version 4: U.S. Geological Survey 

Open-File Report 00–315, 27 p. (Also available at 

http://water.usgs.gov/nrp/gwsoftware/mfgui4/modflow-gui.html.) 

Yager, R.M., 2004, Effects of model sensitivity and nonlinearity on nonlinear regression of ground 

water flow: Ground Water, v. 42, no. 3, p. 390–400. 
12 

Appendix 1: Programmer Documentation for the Partition 

Stress Boundaries Capability

This appendix documents programming aspects of the Partition Stress Boundaries (PSB) 

capability of MODFLOW-CDSS and MODFLOW-LGR-CDSS. Much of the discussion presented 

here assumes that the reader is familiar with chapter 9 in Harbaugh (2005), which provides 

programmer documentation of MODFLOW-2005, and with Local Grid Refinement (LGR, Mehl 

and Hill, 2005, 2007, 2010). Source code for the PSB capability is in file psb1.f90, which is 

included in the distribution file available for download from the URL listed in the Preface of this 

report. 

The PSB capability takes advantage of the Fortran modules, derived types, and module 

arrays on which LGR is based. In MODFLOW-2005 (Harbaugh, 2005) and MODFLOW-LGR

(Mehl and Hill, 2005, 2007, 2010), each of the stress packages defines an array of elements of a 

derived type designed to hold all variable and array data needed for the package. When LGR is 

used, each derived-type element in the array contains data corresponding to either the parent grid or 

one of the child grids. The PSB capability uses these derived-type arrays, but when PSB is used, 

each element in the array corresponds to one partition instead of one grid. When PSB and LGR are 

used in the same simulation, each element in the array corresponds to one partition in either the 

parent grid or one of the child grids. Multiple partitions can be defined for any of the grids. PSB 

keeps track of the assignment of partitions to grids according to the contents of each name file.

When either MODFLOW-CDSS or MODFLOW-LGR-CDSS is invoked, the name file (or 

each name file, when MODFLOW-LGR-CDSS is used) is read by PSB. If multiple input files for 

any supported stress package are listed, PSB is activated and takes over processing of that package. 

PSB stores the input file name and unit number for each partition listed in the name file and assigns 

the IUNIT element for that package as zero. From then on, all subroutine calls for that package are 

handled by PSB. The source code for the stress packages is unchanged except that the TEXT 

variables of the Budget-Procedure subroutines are defined as public module variables. PSB makes 

all calls to subroutines of packages for which partitions have been defined. Prior to calling the 

subroutines of the Budget Procedure, PSB assigns TEXT as the user-specified (or default) identifier

for each partition. Otherwise, all calculations and assignments required to simulate the stress 

boundaries and observations are handled by the stress-package subroutines as programmed in 

MODFLOW-2005 and documented by Harbaugh (2005), Banta (2000), or Harbaugh and Hill 

(2009). 
13 

For all stress packages, PSB stores data needed to keep track of partitions in each grid in an 

array named PARTITIONS. PARTITIONS is an array of elements of derived type PARTITION. 

Each structure of type PARTITION stores information about one partition. Derived type 

PARTITION is defined as follows: 

TYPE PARTITION

 CHARACTER(LEN=4) :: PACKAGE 

 CHARACTER(LEN=16) :: ID

 INTEGER :: UNIT 

 INTEGER :: PKGINDEX 

END TYPE PARTITION

where:

PACKAGE is the three- or four-letter file type used in the name file to activate a package. 

PACKAGE may be any of “DRN,” “DRT,” “EVT,” “ETS,” “GHB,” “RCH,” “RIV,”

“WEL,” “DROB,” “GBOB,” or “RVOB.” See table 1 for packages and file types,

ID is the partition identifier, as assigned by the user in the name file or by default,

UNIT is the unit number assigned to the partition in the name file, and

PKGINDEX is an integer whose value points to the element in the derived-type module array

belonging to the package identified by PACKAGE. For example, if PACKAGE is “RIV” 

and PKGINDEX equals 2, data for the partition referenced by the structure of type 

PARTITION are stored in element 2 of the GWFRIVDAT array of the River Package.

The module that implements the PSB capability (the “PSBMODULE” module) defines an array of

elements of derived type GWFPSBDAT. Each element in this array holds a PARTITIONS array 

and several scalar variables needed for one grid. This organization allows PSB to maintain correct 

correspondence between partitions and grids. Note that in a given package module, all partitions in 

all grids are stored in the module array (for example, the GWFRIVDAT array in the River 

Package). The assignment of partitions to grids is encapsulated in the GWFPSBDAT arrays and 

the PKGINDEX components of elements in the PARTITIONS arrays.

The PSB capability is implemented by eight subroutines called from the main program unit 

of either MODFLOW-CDSS or MODFLOW-LGR-CDSS. PSB subroutines associated with 
14 

MODFLOW procedures (for example, the Allocate and Read Procedure, the Read and Prepare 

Procedure, and so on) are called along with calls to the packages’ subroutines of that procedure. 

The PSB subroutines called from the main program units are summarized in table 1-1. 

Table 1-1. Subroutines of the Partition Stress Boundaries capability.

Subroutine 

name

Description

PSB1SETUP Determine need for partitions in each package, for all grids. If any package is 

partitioned in any grid, allocate and initialize the PARTITIONS arrays with sufficient 

space to handle that package in all grids.

PSB1AR Write indication that PSB is active for current grid and table of partitions to listing 

file. Call Allocate and Read Procedure (AR) subroutines for all partitions in current 

grid. Set IUNIT element to 0 for any package that is to be handled by PSB.

GWF2PSB1RP Call Read and Prepare Procedure (RP) subroutines of the Groundwater-Flow Process 

for all partitions in current grid.

GWF2PSB1FM Call Formulate Procedure (FM) subroutines for all partitions in current grid.

GWF2PSB1BD For each partition in the current grid, assign TEXT module variable as the ID 

component for the partition, then call the Budget Procedure (BD) subroutine 

appropriate for the partition.

OBS2PSB1SE Call Simulated Equivalents Procedure (SE) subroutines for observations associated 

with partitions in current grid.

OBS2PSB1OT Call Output Procedure (OT) subroutines for observations associated with partitions 

in current grid.

PSB1DA Call Deallocate Procedure (DA) subroutines for all partitions in current grid. 

Deallocate memory allocated by the PSB module for the current grid.
15 

Appendix 2: Partition Stress Boundaries Example

An example demonstrating the use of the Partition Stress Boundaries (PSB) capability is 

included in the distribution file available at the URL listed in the Preface of this report. Figure 2-1 

is a map view of the hypothetical groundwater system simulated in the example. The model 

domain represents a two-layer aquifer system in a square area 18,000 meters on a side. The site 

encompasses three rivers, a hillside that is the source of a small influx of groundwater, two wells, 

and an irrigated corn field. Recharge from precipitation is simulated over the entire area. 

Additional recharge comes from excess irrigation water applied to the corn field. An initial steadystate stress period simulates conditions prior to withdrawal of groundwater from the wells. Four 

transient-state stress periods simulate response of the system to constant pumping from the wells

over 283 days. The input files for this example, which contain additional details of this 

hypothetical system, are in the test-run\psb directory of the MODFLOW-CDSS distribution. 

The name file for this example is shown in figure 2-2. Note that the name file lists two 

input files of type RCH (Recharge Package), one representing recharge from precipitation and one 

representing recharge due to excess irrigation water. Two files of type WEL (Well Package) are 

listed, one for each well. Three files of type RIV (River Package), one for each river, are listed. 

Also note that the entries of type RVOB (River-Package observations) include the partition 

identifier of the River-Package partition that defines the river cells to which the observations 

specified in each RVOB file apply. Each of the RCH, WEL, and RIV input files is constructed 

according to instructions provided in Harbaugh (2005); no special entries are required in these files 

to use PSB. 

Selected output of the listing file, showing the table of stress-boundary partitions and a 

volumetric water-budget table, is shown in figure 2-3. Volumetric water-budget data for all time 

steps, saved to a binary cell-by-cell flow file and extracted using GW_Chart (Winston, 2000), 

illustrate (fig. 2-4) that the various partitioned components of the volumetric water budget are 

individually tracked and readily distinguished for interpretation. 
16 

Figure 2-1. Model grid and features for the Partition Stress Boundaries example.

1

18

1 18

COLUMN

R

O

W

River 1

River 2

R

vi er 3

Well 1

Well 2

Hillside

Corn field
17 

# Name file for test case psb

# 

# Output files

list 12 psb.lst

data 13 psb._simhds

data 14 psb._simriv

# 

# Global input files

dis 31 psb.dis

zone 32 psb.zon

mult 33 psb.mlt

# 

# Flow process input files

bas6 41 psb.bas

lpf 42 psb.lpf

pcg 44 psb.pcg

oc 45 psb.oc

ghb 46 psb.ghb

# 

# Partitioned stress-boundary packages

rch 48 psb.rch RCH_Precip

rch 49 psb.rchcorn "RCH: Corn irrig"

wel 43 psb.wel

wel 50 psb.wel2

riv 51 psb.riv1 "River 1"

riv 52 psb.riv2 "River 2"

riv 53 psb.riv3 "River 3"

# 

# Obs process input files

hob 22 psb.ohd

rvob 23 psb.orv "River 3"

rvob 24 psb2.orv "River 2"

Figure 2-2. Name file for the Partition Stress Boundaries example.
18 

...

PSB -- PARTITION STRESS BOUNDARIES CAPABILITY, VERSION 1.0, 04/07/2011

PSB has been activated by the appearance in the name file of multiple

repetitions of input files for supported stress-boundary packages.

Stress packages and partitions implemented by PSB:

PKG UNIT PARTITION ID INPUT FILE

---- ---- ---------------- ------------------------

RCH 48 RCH_Precip psb.rch

RCH 49 RCH: Corn irrig psb.rchcorn

WEL 43 PSB-WEL Part 1 psb.wel

WEL 50 PSB-WEL Part 2 psb.wel2

RIV 51 River 1 psb.riv1

RIV 52 River 2 psb.riv2

RIV 53 River 3 psb.riv3

RVOB 23 River 3 psb.orv

RVOB 24 River 2 psb2.orv

...

 VOLUMETRIC BUDGET FOR ENTIRE MODEL AT END OF TIME STEP 9 IN STRESS PERIOD 5

 ------------------------------------------------------------------------------

 CUMULATIVE VOLUMES L**3 RATES FOR THIS TIME STEP L**3/T

 ------------------ ------------------------

 IN: IN:

 --- ---

 STORAGE = 13423991.0000 STORAGE = 4.3753E-02

 CONSTANT HEAD = 0.0000 CONSTANT HEAD = 0.0000

 HEAD DEP BOUNDS = 20045.3887 HEAD DEP BOUNDS = 8.5285E-04

 RCH_Precip = 118832824.0000 RCH_Precip = 4.8600

 RCH: Corn irrig = 27912326.0000 RCH: Corn irrig = 1.1416

 PSB-WEL Part 1 = 0.0000 PSB-WEL Part 1 = 0.0000

 PSB-WEL Part 2 = 0.0000 PSB-WEL Part 2 = 0.0000

 River 1 = 0.0000 River 1 = 0.0000

 River 2 = 4185328.5000 River 2 = 0.2615

 River 3 = 0.0000 River 3 = 0.0000

 TOTAL IN = 164374512.0000 TOTAL IN = 6.3076

 OUT: OUT:

 ---- ----

 STORAGE = 0.0000 STORAGE = 0.0000

 CONSTANT HEAD = 0.0000 CONSTANT HEAD = 0.0000

 HEAD DEP BOUNDS = 0.0000 HEAD DEP BOUNDS = 0.0000

 RCH_Precip = 0.0000 RCH_Precip = 0.0000

 RCH: Corn irrig = 0.0000 RCH: Corn irrig = 0.0000

 PSB-WEL Part 1 = 53792640.0000 PSB-WEL Part 1 = 2.2000

 PSB-WEL Part 2 = 48902400.0000 PSB-WEL Part 2 = 2.0000

 River 1 = 21412040.0000 River 1 = 0.7303

 River 2 = 6907229.0000 River 2 = 0.1655

 River 3 = 33360638.0000 River 3 = 1.2119

 TOTAL OUT = 164374944.0000 TOTAL OUT = 6.3077

 IN - OUT = -432.0000 IN - OUT = -5.3883E-05

PERCENT DISCREPANCY = 0.00 PERCENT DISCREPANCY = 0.00

...

Figure 2-3. Selected output for the Partition Stress Boundaries example.
19 

Figure 2-4. Volumetric flow rates for water-budget components of the Partition Stress Boundaries example.

0

1

2

3

4

5

0 5 10 15 20 25

FLOW RATE, IN CUBIC METERS PER SECOND

SIMULATION TIME, IN MILLIONS OF SECONDS

Inflow: STORAGE

Inflow: HEAD DEP BOUNDS

Inflow: RCH_Precip

Inflow: RCH: Corn irrig

Inflow: River 2

Outflow: PSB-WEL Part 1

Outflow: PSB-WEL Part 2

Outflow: River 1

Outflow: River 2

Outflow: River 3

EXPLANATION

Publishing support provided by: 

Denver Publishing Service Center

For more information concerning this publication, contact:

Director, USGS Colorado Water Science Center

Box 25046, Mail Stop 415

Denver, CO 80225

(303) 236-4882

Or visit the Colorado Water Science Center Web site at:

http://co.water.usgs.gov/