C ONTRIBUTED RESEARCH ARTICLE 1

The Case for NetCDF as a Groundwater

Model Output Format Using R: Example
Using USGS MODFLOW
by Kapo Coulibaly, David Barnes, Michael Barnes

Abstract USGS MODFLOW is a widely used groundwater flow modeling code. Model results vi-
sualization and analysis are commonly done with third-party GUI packages. The output format
of MODFLOW is a FORTRAN binary file that may vary depending on the compiler and the plat-
form used. The binary results file lacks metadata on the model dimensions and geographic location.
NetCDF (Network Common Data Form), on the other hand, is a standardized and sharable geospatial
format that can be visualized with numerous free and commercial packages including R. It is also
possible to embed useful grid discretization in the NetCDF, which are absent from the binary results.
Using NetCDF as a model output format enables modelers and non-modelers to easily share and
analyze model results using readily available softwares (R, GRASS GIS, ArcGIS, etc.). R was used to
generate a NetCDF file from a MODFLOW binary output and example analyses and visualizations
were implemented.

Introduction
Groundwater flow models are becoming increasingly popular and are a very important component of
water resources management. Numerous groundwater models are implemented every year to help
with decision making and overall understanding of the groundwater system. However, barriers to
interpreting and sharing model results include binary compatibility issues, and the absence of infor-
mation on the model grid/geospatial location in the binary output format. Upon model completion
a report is generally produced and model files are archived. Archived model files get used only by
groundwater modelers who have enough knowledge to understand groundwater modeling and know
how to manipulate model files. Converting groundwater model results into a geospatial data format
easily read by free and available softwares would make it easier for non-modelers and decision makers
to access and analyze groundwater model results. Unidata’s Network Common Data Form (NetCDF)
is a set of software libraries and machine-independent data formats that support the creation, access,
and sharing of array-oriented scientific data. It is also a community standard for sharing scientific
data (UNIDATA, 2015). As such, it is an ideal platform to share and distribute groundwater model
results. This paper will present a set of R routines to convert groundwater model results into NetCDF,
specifically the USGS MODFLOW code (Harbaugh, Arlen W., 2005) outputs. Examples of how these
results can be viewed will also be shown.

MODFLOW Overview and File Structure

Background

USGS MODFLOW (Harbaugh, Arlen W., 2005) is a finite difference groundwater modeling code. The
real world model domain is discretized into rectangular cells to form a grid. Information for the cells’
dimensions, coordinates (local coordinate system), and properties are converted into MODFLOW file
format (ASCII FORTRAN formatted or free format) and read by MODFLOW for computation. Grids
are usually multidimensional (i.e. they have row, column, and layer components indexed as i, j, and k,
respectively). They can also be discretized in time as groundwater levels and fluxes change over time.
Results for each grid cell are output in the grid that was initially defined.

File Structure

MODFLOW is modular and each module (called package) has a specific input file format. The
model is made up of several mandatory packages necessary to define the model grid and set up the
groundwater flow equations. Optional packages are used to represent additional physical processes.
Detailed descriptions of the individual packages’ file format is available online at http://water.
usgs.gov/ogw/modflow/MODFLOW-2005-Guide (US Geological Survey, 2016). MODFLOW generates
various output files as well, both in plain ASCII text format and FORTRAN binaries files. Outputs
include water balance, groundwater elevation, cell-to-cell flow rates, and water level changes. The

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859

C ONTRIBUTED RESEARCH ARTICLE 2

discretization file and the binary heads file (calculated groundwater level results file),relevant to
generating NetCDF results, are described in further detail herein.

Discretization File

The discretization file contains the model grid informations. Namely, the number of rows, columns,
and layers. It also contains the time discretization (i. e. the length of the modeling period and the
length of the individual time steps). A subdset of the runtime time steps maybe saved to the result
file. As a result, only the grid information will be read from the discretization file. The time steps
information will be read from the output file. A detailed description of the discretization file can
be viewed here: http://water.usgs.gov/ogw/modflow/MODFLOW-2005-Guide (US Geological Survey,
2016).

Modflow Heads Binary Output File

The binary heads file (groundwater levels) is a FORTRAN binary file containing arrays of groundwater
levels in each model cell as they change over time. The arrays are grouped by time steps or stress
periods. A header containing the stress period, elapsed time, the current timestep, and the grid
dimension is first read, followed by the array of heads (groundwater levels) for all layers. This process
is repeated until all time steps and/or stress periods are read. A detailed description of the MODFLOW
binary heads format is available here: http://water.usgs.gov/ogw/modflow/MODFLOW-2005-Guide/
(US Geological Survey, 2016) and in the MODFLOW 88 manual (McDonald, M.G. and Harbaugh, A.W.
, 1988).

Model Results Conversion to NetCDF

The R package ncdf4 (David, Pierce, 2015) was used to convert the MODFLOW heads’ binary files to
NetCDF.

Grid Definition and NetCDF Creation

Conversion from MODFLOW binary to NetCDF will be carried out on a simple model with 50 rows, 50
columns, 2 layers, and 14 stress periods. The first 3 stress periods are 10 days long each; the remaining
stress periods are monthly. A well located in row 24, column 24, and layer 1 is pumping 20,000 ft3 /d.

Grid information Extraction

First, the MODFLOW discretization file was read to create the grid. A detailed parsing of the
discretization file is beyond the scope of this publication; hence, the R code here will be tailored to the
DIS file being read. A few R code snippets are shown next.

# Reading dicretization file

dis.lst<-readLines("model_gv.dis")

# Displaying first 10 lines of the discretization file

head(dis.lst,10)

#> [1] "# MODFLOW2000 Discretization File"

#> [2] " 2 50 50 14 4 0"
#> [3] " 0 0"
#> [4] " 0 100.0000(10E12.4) 0 DELTA-X or C"
#> [5] " 0 100.0000(10E12.4) 0 DELTA-Y or R"
#> [6] " 0 100.0000(10e12.4) -1 TOP of Model"
#> [7] " 0 50.00000(10e12.4) -1 BOTTOM of Layer 1"
#> [8] " 00.0000e+00(10e12.4) -1 BOTTOM of Layer 2"
#> [9] " 10.000000 1 1.200000 SS"
#> [10] " 10.000000 1 1.200000 TR"

The first line is a comment. The first 4 integers shown on line 2 represent the number of layers,
rows, columns, and stress periods. The remaining 2 are codes for the model time and length units.
Lines 4 and 5 give the grid spacing along the columns and rows, respectively. The first integer on each

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859

C ONTRIBUTED RESEARCH ARTICLE 3

of these lines being 0 indicates that the grid spacing is constant, and the number that follows is the
size of the grid spacing. The grid size is extracted first.
# Grid size extraction
grid.info <- scan(textConnection(dis.lst[2]))
grid.info
#> [1] 2 50 50 14 4 0
# To make the code readable let's assign a variable name for each parameter
n.lay <- grid.info[1]
n.row <- grid.info[2]
n.col <- grid.info[3]
n.str <- grid.info[4]

NetCDF Framework

Utilizing this grid information, a NetCDF file can be created using the R package ncdf4 (David, Pierce,
2015). The grid spacing, located in lines 4 and 5 above is 100 ft in both the x and y directions. Knowing
the number of rows, columns, and the grid spacing, the coordinates along the x and y axes can be
computed and the NetCDF file created. The steps used are outlined in the R code below.Real world
coordinate of the local model origin and rotation angle can also be used to generate a georeferenced
Netcdf.
# Loading required library
library(ncdf4)

# grid spacing in the x and y direction

dx<-rep(100,n.col)
dy<-rep(100,n.row)

# Create x-coordinates assuming the lower left corner is the origin

xcoord<-vector()
ycoord<-vector()

# Cell center coordinates computation

xcoord[1]<-dx[1]/2
for (i in 2:length(dx)) {
xcoord[i]<-xcoord[i-1]+dx[i-1]/2 + dx[i]/2
}
head(xcoord)
#> [1] 50 150 250 350 450 550
ycoord[1]<-dy[1]/2
for (i in 2:length(dy)) {
ycoord[i]<-ycoord[i-1]+dy[i-1]/2 + dy[i]/2
}
head(ycoord)
#> [1] 50 150 250 350 450 550
# NetCDF dimensions definition
time.dim <- ncdim_def("time",units="days",vals=1:n.str)
x.dim <- ncdim_def("x",units="ft",vals=xcoord)
y.dim <- ncdim_def("y",units="ft",vals=ycoord)
lay.dim<-ncdim_def("layer",units="layer",vals=1:n.lay)

# Define missing value

missval=-999

# Create NetCDF variable

mflow.var<- ncvar_def("heads",units="ft",dim=list(x.dim,y.dim,lay.dim,time.dim),
prec="float",missval=missval)

# Create NetCDF file

new<-nc_create(filename = "model.nc", mflow.var)

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859

C ONTRIBUTED RESEARCH ARTICLE 4

The NetCDF variables have been dimensioned and created. Now, MODFLOW results will be read
from the binary file and used to populate the NetCDF file.

Writing MODFLOW binary to a NetCDF file

A generic R code snippet used to read the MODFLOW heads’ binary file is shown below. The binary
file is read following the description outlined in previous sections. The data are written to the NetCDF
file as they are read.

# Open binary file

zz <- file("model_gv.hds", "rb")

for (k in 1:n.str) {
for (i in 1:n.lay) {
readBin(zz,what="integer",n=2,size=4)->N1 # time step and stress period number
readBin(zz,what="double",n=2,size=4)->N2 # time in current stress period and elapsed time
readChar(zz,nchars=16,useBytes=TRUE)->txt1 # name of parameter stored in the binary file
readBin(zz,what="integer",n=3,size=4)->N3 # number of rows, columns, and layer
tnber<-N3[1]*N3[2] # number of values in the array
readBin(zz,what="double",n=tnber,size=4)->N4 # Reading array of heads
N4<-matrix(N4,ncol=N3[2],byrow=FALSE) # Converting vector to matrix
N4<-N4[,N3[2]:1] # Correcting for row major layout
ncvar_put(new,varid="heads",vals=N4,
start=c(1,1,i,k),count=c(-1,-1,1,1)) #Writing water levels (heads) to file
ncvar_put(new,varid="time",vals=N2[2],
start=c(k),count=c(1)) # writing elapsed time to NetCDF time dimension

}
nc_close(new)

NetCDF Visualization and Analysis

Once the NetCDF file is created, it can be used to visualize results for any layer at any stress period
or time step. NetCDF file can be visualized with GIS softwares (GRASS , ArcGIS, QGIS, SAGA-
GIS etc.) and numerous other softwares.A list of software which can be used to visualize and
manipulate NetCDF file is published by Unidata here: http://www.unidata.ucar.edu/software/
netcdf/software.html. While groundwater modeling reports typically only present selected results
for review, the NetCDF file can be used to archive and distribute complete geographically referenced
model results.

Groundwater Level Map

Groundwater level contour maps can be easily generated with R using the newly created NetCDF file.

# Open NetCDF file

nc.f<-nc_open("model.nc")

# Extract coordinates
x<-ncvar_get(nc.f,varid="x")
y<-ncvar_get(nc.f,varid="y")

# extract 4 stress periods for layer 1

head1<-ncvar_get(nc.f,varid="heads",start=c(1,1,1,1),count=c(-1,-1,1,1)) # Stress period 1
head2<-ncvar_get(nc.f,varid="heads",start=c(1,1,1,3),count=c(-1,-1,1,1)) # Stress period 3
head3<-ncvar_get(nc.f,varid="heads",start=c(1,1,1,9),count=c(-1,-1,1,1)) # Stress period 9
head4<-ncvar_get(nc.f,varid="heads",start=c(1,1,1,14),count=c(-1,-1,1,1)) # Stress period 14
par(mfrow=c(2,2),cex=1,lwd=2)

contour(x,y,head1,main="Stress period 1 heads contour (ft)",xlab="X (ft)", ylab="Y (ft)")

contour(x,y,head2,main="Stress period 3 heads contour (ft)",xlab="X (ft)", ylab="Y (ft)")

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859

C ONTRIBUTED RESEARCH ARTICLE 5

contour(x,y,head3,main="Stress period 9 heads contour (ft)",xlab="X (ft)", ylab="Y (ft)")

contour(x,y,head4,main="Stress period 14 heads contour (ft)",xlab="X (ft)", ylab="Y (ft)")

Groundwater Timeseries

Analyzing water level changes over time at a given location is also particularly useful. For instance,
simulated future water levels at a groundwater well can be plotted. Also, groundwater model results
can be compared with past water level measurements. As an example, groundwater levels at row 20,
column 18, and layer 2 were extracted and plotted.

# Time extraction
heads.t<-ncvar_get(nc.f,varid="time")

# Extracting groundwater levels timeseries

heads.ts<-ncvar_get(nc.f,varid="heads",start=c(18,20,2,1),count=c(1,1,1,-1))

par(mfrow=c(1,1),cex=1.5)

# Plotting timeseries.
plot(heads.t,heads.ts,main="Groundwater Timeseries",
xlab="Time (days)",ylab="Groundwater levels (ft)",ty="l",col="blue")

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859

C ONTRIBUTED RESEARCH ARTICLE 6

Summary
USGS MODFLOW groundwater model results were sucessfully converted to NetCDF using R. The
NetCDF format can increase the accessibility of model results to non-modelers and decision makers.
Model results in NetCDF format contain grid information (local or georeferenced) with model results
in one stand-alone file with metadata. The process presented here can be easily extended to include
the groundwater solute and contaminant modeling code MT3D. Also, MODFLOW input parameters
can be converted to NetCDF by following the same procedure, making it easier to review groundwater
models without needing specialized groundwater pre- and post-processing softwares. With a few R
commands and a basic knowledge of the R package ncdf4, one can easily open and analyze relatively
complex groundwater modeling results. The same can also be achieved with various freely available
and commercial softwares. Implementing an R package to carry out the conversion steps would
help streamline the process, allowing groundwater modelers to easily archive their model results in
NetCDF format and make them more sharable.

Bibliography
David, Pierce. ncdf4: Interface to Unidata netCDF (Version 4 or Earlier) Format Data Files, 2015. URL
https://CRAN.R-project.org/package=ncdf4. R package version 1.15. [p2, 3]

Harbaugh, Arlen W. MODFLOW-2005, The U.S. Geological Survey Modular Ground-Water Model-the
Ground-Water Flow Process. Techniques and Methods. United States Geological Survey, Reston, Virginia,
2005. [p1]

McDonald, M.G. and Harbaugh, A.W. . A modular three-dimensional finite-difference ground-water flow
model. United States Geological Survey, Reston, Virginia, 1988. [p2]

UNIDATA. NetCDF Factsheet, 2015. URL WWW.UNIDATA.UCAR.EDU. NetCDF version 4. [p1]

US Geological Survey. Online Guide to MODFLOW-2005. United States Geological Survey, Reston,
Virginia, 2016. URL http://water.usgs.gov/ogw/modflow/MODFLOW-2005-Guide/. [p1, 2]

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859

C ONTRIBUTED RESEARCH ARTICLE 7

Kapo Coulibaly
Geoscience Support Services Inc
620 Arrow Highway
La Verne, CA 92750
USA
kcoulibaly@geoscience-water.com

David Barnes
WSP Parsons
1567 Hayley Ln Ste 202
Fort Myers, Fl 33907
USA
David.Barnes@pbworld.com

Michael Barnes
University of Maryland Baltimore County
1000 Hilltop Circle Baltimore, MD 21250
Baltimore, MD 21250
USA
mlbarnes@umbc.edu

The R Journal Vol. XX/YY, AAAA ISSN 2073-4859