Aquaveo MODFLOW

The Aquaveo versions of MODFLOW that are posted on this website and shipped with the GMS and Arc Hydro Groundwater software contain modifications/additions made by Aquaveo staff to make using MODFLOW easier. All changes to the MODFLOW code have been clearly marked with a "!aq" comment. In addition to changes made in the FORTRAN source code, Aquaveo MODFLOW comprises a large C++ library of code called MODFLOWLIB. Many of the changes in the FORTRAN code make calls into MODFLOWLIB. The following is a list of the categories of significant features/changes to the MODFLOW code:

License

A copy of the license for Aquaveo MODFLOW can be found here.

MODFLOW with HDF5

The Aquaveo version of MODFLOW has been modified to link to the HDF5 file format library. This allows for large portions of the MODFLOW input to be stored in an HDF5 file. A journal article on MODFLOW with HDF5 has been published here.

The HDF5 file format is a cross platform binary format for storing scientific data. Click here to learn more about HDF5. One advantage of using HDF5 is that the data is stored in binary format so the disk reads and writes are much faster than with ASCII files. You can view the data stored in an HDF5 file by using HDFView.

Another advantage of using the HDF5 libary with MODFLOW package data and array data is that HDF5 will compress the data. For example, if you have a transient simulation using the river package the typical line in a river package file would look like this:

[K] [I] [J] [STAGE] [CONDUCTANCE] [ELEVATION]
1 3 4 10.2 5.8 9.5

Then during the next stress period typically the stage would change. The line in the file would look like this:

1 3 4 10.8 5.8 9.5

So we repeated all of the data except that 10.2 changed to 10.8. With compression those repeated values do not take up much space on disk so that the resulting file is smaller.

In one example a river file that was 437 MB was saved to HDF5 format with a compression level of 1 and the resulting file was 14 MB. In another example, a model with drain (253 MB text file) and general head (141 MB text file) boundary conditions was saved to an HDF5 file with a file size of 8 MB.

MODFLOW code modifications for HDF5 support

Support for HDF5 was added to most MODFLOW packages by modifying three subroutines in ult6.f: U2DREL, U2DINT, and ULSTRD. U2DREL and U2DINT were modified so that if the key word HDF5 was encountered when attempting to read an array then an external procedure is called to read in the data. We have added support for the following:

HDF5 CONSTNT IPRN "FNAME" "pathInFile" nDim start1 nToRead1 start2 nToRead2 start3 nToRead3 example: "HDF5 1.0 0 "input.h5" "Recharge/07. Property" 3 0 1 0 132 0 1"
Explanation of variables
HDF5 a card to indicate that this is read from an HDF5 file
CNSTNT the multiplier for the array
IPRN print flag for the output control for MODFLOW
"FNAME" the HDF5 file where the array is stored
"pathInFile" path to the dataset in the HDF5 file
nDim number of dimensions that the dataset has (this is 1, 2, 3)
start1 the index (NOTE: these are 0 based not 1) for the starting point to read the dataset in the first dimension
nToRead1 the number of values to read in the first dimension
start2 the index for the starting point to read the dataset in the second dimension
nToRead2 the number of values to read in the second dimension
start3 the index for the starting point to read the dataset in the third dimension
nToRead3 the number of values to read in the third dimension

This type of formatting will work for any HDF5 dataset that has 3 dimensions or less and the dataset can be a 4 byte float or an 8 byte double. The other available format that can be used with the HDF5 key word for the array reading utilities is the following:

HDF5 CONSTANT CNSTNT example: HDF5 CONSTANT 3.0

This type of formating will assign a constant value to the array. This type of formatting may seem unnecessary. However, the constant identifier can be useful when using parameters to define arrays. Parameters will be explained in another section. ULSTRD was also modified to read data from an HDF5 file. This format is specific to the types of HDF5 files that GMS creates.

GMS_HDF5_01 "FNAME" "pathInFile" SP
Explanation of variables
GMS_HDF5_01 a card to indicate that this is read from an HDF5 file
"FNAME" the HDF5 file where the array is stored
"pathInFile" path to the group in the HDF5 file where all of the data for the boundary condition is stored
SP stress period number

Here is an example of a regular modflow drain file and a drain file with the HDF5 modifications.

Comparison of MODFLOW Drain files
Traditional Drain file Drain file with HDF5
3 40 AUX IFACE AUX CONDFACT AUX CELLGRP
3 0
1 3 2 19.0 10.0 6 1.0 -1
1 4 3 19.0 10.0 4 1.0 -1
1 5 4 19.0 10.0 5 1.0 -1
3 0
1 3 2 18.9 11.0 6 1.0 -1
1 4 3 18.9 11.0 4 1.0 -1
1 5 4 18.9 11.0 5 1.0 -1
3 0
1 3 2 19.0 10.0 6 1.0 -1
1 4 3 19.0 10.0 4 1.0 -1
1 5 4 19.0 10.0 5 1.0 -1
#GMS_HDF5_01
3 40 AUX IFACE AUX CONDFACT AUX CELLGRP
3         0         0
GMS_HDF5_01 "sg_t_pest_65.h5" "Drain" 1
3         0         0
GMS_HDF5_01 "sg_t_pest_65.h5" "Drain" 2
3         0         0
GMS_HDF5_01 "sg_t_pest_65.h5" "Drain" 3

The STR, SFR, MNW1, and MNW2 packages required more custom programming to read from HDF5 files since these packages deviated from the design of the other list based packages (ie RIV, DRN...) and the respective source files have been marked with the !aq comment to indicate the changes.

Parameters

MODFLOW 2000 introduced the concept of parameters as native input to MODFLOW. Parameters are created in GMS by assigning a "key" value (usually a negative number) to a MODFLOW input. When MODFLOW is running and calls our external routine to read in the HDF5 a check is made in the data that is read from the HDF5 file. If one of the parameter "key" values is found in the data then the parameter value is substituted into the array or list. By adopting this approach it was much easier to support transient parameters and very large sets of pilot points. Also, adopting this approach allows GMS users to use parameters with the BCF package. This feature is not available with the MODFLOW PES process.

Pilot Points

In older versions of GMS, pilot points were supported by using the multiplier arrays in MODFLOW. Beginning with version 6.5 the pilot point interpolation takes place with in our external routine that is called by MODFLOW. For example, if MODFLOW calls our routine to read an HK array and that array has parameter key values that are associated with a parameter that is defined using pilot points then our routine will perform the pilot point interpolation and substitute the appropriate value. This includes any log interpolation that the user has specified.

Exporting Native Text

Another option available in Aquaveo MODFLOW is exporting native MODFLOW text files with documentation. The following table shows an example DIS package file. The first file listed is a typical DIS file while the second file listed has been exported to include the package documentation.

Comparison of MODFLOW DIS files
Traditional DIS file
    2   10   15    2    4    0  
 1 0
CONSTANT   5.000000E+02  
CONSTANT   5.000000E+02  
CONSTANT   1.500000E+02  
CONSTANT   5.000000E+01  
CONSTANT   0.000000E+00  
CONSTANT  -5.000000E+01  
 1.000E+00         1 1.000E+00  SS  
 1.000E+00         1 1.000E+00  SS 
Exported DIS file with documentation
     2     10     15      2      4      0      #  1. NLAY NROW NCOL NPER ITMUNI LENUNI 
1 0                                            #  2. LAYCBD(NLAY)
CONSTANT 500.0                                 #  3. DELR(NCOL)
CONSTANT 500.0                                 #  4. DELC(NROW)
CONSTANT 150.0                                 #  5. Top(NCOL,NROW)     LAY 1
CONSTANT 50.0                                  #  6. BOTM(NCOL,NROW)    LAY 1
CONSTANT 0.0                                   #  6. BOTM(NCOL,NROW)    LAY 1 Confining Bed
CONSTANT -50.0                                 #  6. BOTM(NCOL,NROW)    LAY 2
1.0 1 1.0 Ss                                   #  7. PERLEN NSTP TSMULT Ss/tr    PERIOD 1
1.0 1 1.0 Ss                                   #  7. PERLEN NSTP TSMULT Ss/tr    PERIOD 2

The comments on the right side of the file with documentation list the line number (MODFLOW data set number) for the particular input along with the variables on that line. For example, in the DIS file the first line or data set has 6 inputs beginning with NLAY and ending with LENUNI. If you were to go search the MODFLOW documentation for the DIS file you would see these variables listed under data set 1. You can see the MODFLOW 2000 documentation for the DIS package by clicking here. MODFLOW will output these native text files with documentation by using the following command line arguments:

modflow.exe input.nam -exportText_ArraysInternal output.nam

This command line will create a new set of MODFLOW input files with that same prefix of "output" and each package will have a standard extension matching the package name (DIS to .dis, LPF to .lpf...). Also, all arrays will be stored internally in the MODFLOW package files. Two other command line options are available for exporting text. The next option is -export_Text. With this option all arrays will be written to external text files. The name of the text file reflects the package and variable that are stored in the file. For example, if my output files are called "output" then an external text file for the IBOUND for layer 1 would be called output_array_BAS_IBOUND_1.txt. Notice that "output_array" is followed by "BAS". This refers to the BAS or Basic package in MODFLOW. "BAS" is then followed by "IBOUND" referring to the IBOUND variable in the BAS package. The last part of the file name is "1" referring to the layer that this variable applies to. Here is another example: the recharge array for stress period 3 would be output_array_RCH_RECH_3.txt. The following is an example of a BAS file that references external arrays.

MODFLOW BAS File with External Arrays
FREE                                                         #  1. Options
OPEN/CLOSE bcf_par_2k_array_BAS_IBOUND_1.txt 1 (FREE) -1     #  2. IBOUND(NCOL,NROW) LAY 1
OPEN/CLOSE bcf_par_2k_array_BAS_IBOUND_2.txt 1 (FREE) -1     #  2. IBOUND(NCOL,NROW) LAY 2
OPEN/CLOSE bcf_par_2k_array_BAS_IBOUND_3.txt 1 (FREE) -1     #  2. IBOUND(NCOL,NROW) LAY 3
OPEN/CLOSE bcf_par_2k_array_BAS_IBOUND_4.txt 1 (FREE) -1     #  2. IBOUND(NCOL,NROW) LAY 4
-999.0                                                       #  3. HNOFLO
OPEN/CLOSE bcf_par_2k_array_BAS_STRT_1.txt 1.0 (FREE) -1     #  4. STRT(NCOL,NROW)   LAY 1
OPEN/CLOSE bcf_par_2k_array_BAS_STRT_2.txt 1.0 (FREE) -1     #  4. STRT(NCOL,NROW)   LAY 2
OPEN/CLOSE bcf_par_2k_array_BAS_STRT_3.txt 1.0 (FREE) -1     #  4. STRT(NCOL,NROW)   LAY 3
OPEN/CLOSE bcf_par_2k_array_BAS_STRT_4.txt 1.0 (FREE) -1     #  4. STRT(NCOL,NROW)   LAY 4

The last option for exporting text is -exportText_ArraysInFolder. With this option all arrays will be external and will be named as described previously. In addition, all external array files will be placed in a new directory called "arrays". This makes for fewer files to view in the directory where the name file is located.

Exporting GMS HDF5

Aquaveo MODFLOW also has a feature to export MODFLOW simulations in the the GMS HDF5 format. This format is a particular group of data sets within an HDF5 file that GMS uses to interact with MODFLOW models. There are two options for creating simulations in the GMS HDF5 format: one for compressed HDF5 and one for uncompressed HDF5. The command line for compressed HDF5 is as follows:

modflow.exe input.nam -exportGmsCompressedH5 output.mfn
This command will create a set of MODFLOW inputs that reference data sets in the "output.h5" file that is created after running this command line. The following is an example of a RIV file that references an HDF5 file.

MODFLOW RIV File with HDF5 File
#GMS_HDF5_01
10 40
        10         0         0
GMS_HDF5_01 "bcf2ss.h5" "River" 1
        -1         0         0

The command line for creating an uncompressed HDF5 file is as follows:

modflow.exe input.nam -exportGmsH5 output.mfn

Exporting SQLite database

Another option available in Aquaveo MODFLOW is the ability to export a MODFLOW simulation to an SQLite database. SQLite is a public domain software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine. Click here to learn more about SQLite. The SQLite database is written to follow the MODFLOW Data Model. The data model consists of a set of tables for archiving a MODFLOW simulation. Click here to learn more about the MODFLOW Data Model. The command line for creating a MODFLOW simulation in an SQLite database is as follows:

modflow.exe input.nam -exportSQLite output.db

This command line will create a new SQLite database named "output.db".

Testing Builds

Each distributed version of MODFLOW has a test suite. The purpose of the test suite is to make sure that code changes do not result in unwanted changes to the MODFLOW output. The test suite is available as a separate download here. A python script is used to read an xml file that contains all of the information needed to test a particular version of MODFLOW. Included in the xml file is a list of the compiled binaries (32bit, 64bit, single/double precision, etc...) to be tested as well as a list of the input files for those binaries to run. The output produced by the compiled binaries is compared to baseline outputs and any differences are reported as failed tests. The final output from the python testing script is an xml file in NUNIT format. This file will list all of the testing suites, tests, and final results.

Miscellaneous issues

  • Certain packages are not yet supported by the exporting features of Aquaveo MODFLOW: ADV2, BFH, DAF, DAFG, HYDMOD, IBS, KDEP, LVDA, RES, SWT, and SWI. Support will be added to a future version.
  • Changes to parameters when exporting text
    • STR and SFR packages require that all boundary conditions be defined using parameters or none. In GMS, our key value parameter approach is more flexible than this so when GMS MODFLOW file are exported to text new STR and SFR parameters are created.
    • List based parameters (DRN, RIV...) are more restrictive than the key value approach used in GMS so when list based parameters are exported to text new parameters and new parameter instances may be created.