The Groundwater Modeling Tool for GRASS;

a tutorial
Jaime J. Carrera-Hernandez
January 2005 DRAFT version

McGill University
Department of Civil Engineering and Applied Mechanics
jaime.carrera@mail.mcgill.ca

Abstract
This tutorial shows how to develop groundwater flow models using GRASS
and MODFLOW. This is done through the Groundwater Modeling Tool for
GRASS (GMTG) or r.gmtg module which works under GRASS. This mod-
ule can be used to run stady state and transient simulations on multilayer
aquifers. The current MODFLOW packages supported by r.gmtg are those
used to simulate wells (extraction and injection), rivers, recharge and drains.

1 Introduction
This is a brief tutorial on how to develop groundwater flow models using GRASS
module r.gmtg. The user should be familiar with different modules of GRASS
such as r.reclass, r.mapcalc. For further reference on GRASS you can read the on-
line tutorials or the GRASS book by Neteler and Mitasova (2004). The problems
developed in this tutorial are taken from Chiang (2001), who developed the Pro-
cessing MODFLOW for Windows (PMWIN) software. These examples are used
to compare the results obtained using a well known MODFLOW processor with
those obtained using GMTG. This module is an improved version of the one de-
scribed by Carrera-Hernandez and Gaskin (2004) and current work is being done
to use other MODFLOW packages.

1
1.1 Description of tutorial
The examples developed in this tutorial will help you to gain a general knowl-
edge on how to use GRASS and GMT to develop groundwater flow models. The
tutorial will explain how to:

1. Create a GRASS region.

2. Import ASCII files (e.g. Digital Elevation Models and sites files) using the
module r.in.ascii

3. Reclassify existing categories from raster maps using r.reclass

4. Use map algebra with r.mapcalc

2 Module description
The r.gmt module uses GRASS as a preprocessor and postprocessor for MOD-
FLOW. It uses raster maps as input for MODFLOW simulations and then imports
the results to different raster maps with a prefix specified by the user which are
explained in table 1.
r.gmt simulation=value units=value layers=value aqtype=value[,value,. . . ] stress=value
length=value[,value,...] steps=value[,value,...] [tsmult=name[,name,. . . ]] region=name[,name,. . . ]
heads=name[,name,...] [Sy=name[,name,. . . ]] [T=name[,name,. . . ]] [K=name[,name,. . . ]]
[bottom=name[,name,. . . ]] [vcond=name[,name,. . . ]] [top=name[,name,. . . ]] [Syb=name[,name,. . . ]]
[recharge=name[,name,. . . ]] [wells=name[,name,. . . ]] [river_heads=name] [river_cond=name]
[river_elev=name] [drain=name[,name,. . . ]] drawdownin=name headsin=name

3 Requirements
If you are running GRASS under Linux you should not have any problems when
attempting to use GMT; as GMT links GRASS with MODFLOW you need to have
MODFLOW installed on your system. You need to download the source code
available from GRASS TWIKI site http://grass.gdf-hannover.de/twiki/
bin/view/GRASS/JaimeCarrera. From this site you will also need to download
the programs rddown and rheads; these files are required to import MODFLOWs
output into GRASS. All data related to this tutorial is available from the same site.

2
 Table 1: Parameters needed to run a simulation using r.gmtg
Parameter Description Value
simulation Type of simulation 0 = Transient
1 = Steady state
units Time units 1 = Seconds
2 = minutes
3 = hours
4 = days
5 = years
layers Number of layers in the model int number
aqtype Type of aquifer 0 = Confined
1 = Unconfined
2 = Variable with
constant T
3 = Variable with
variable T
stress Number of stress periods int number
length Length of each stress period int number
steps Number of time steps for each stress period int number
tsmult Time step multiplier for each stress period float number
region Name of raster map with active cells string
heads Name of raster map with initial heads string
Sy Name of existing raster map(s) with primary storage co- string
efficient values
T Name of existing raster map(s) with Transmissivity. RE- string
QUIRED for CONFINED aquifers or VARIABLE con-
finment aquifers with CONSTANT T
K Name(s) of existing raster map(s) with Horizontal Con- string
ductivity. Required for UNCONFINED aquifers and
VARIABLE confinment aquifers with VARIABLE T
bottom Name of an existing raster map with aquifer bottom. Re- string
quired for unconfined and variable aquifers with variable
T
vcond Name of an existing raster map with Vertical conduc- string
tance
top Name of an existing raster map with Top of aquifer string
Syb Name of an existing raster map with Secondary Storage string
Values
recharge Name of an existing raster map with recharge values string
wells name of sites file(s) containing WELL data string
river heads Name of raster map with stage values for reaches string
river cond Name of raster map containing 3 conductance values for string
reaches
river elev Name of the raster map containing river-bed elevation string
values
drain Name of site map(s) containing drain data string
drawdowninName of raster map for DRAWDOWN simulation values string
headsin Name of raster map for HEAD simulation values string
4 Developing groundwater flow models
This section shows how to use GRASS and GMT to develop groundwater flow
models. However, it is important to stress that this tool is better when using real
world data and to develop groundwater flow models with a conceptual approach.
This tutorial only explains how to use GMT and GRASS to develop groundwa-
ter flow models and the examples are quite simple. The book by Anderson and
Woessner (1992) is a very good reference for groundwater modeling; to learn
more about MODFLOW it is strongly suggested to read its documentation (Mc-
Donald and Harbaugh, 1988).

4.1 Example 1
The first tutorial has two parts:

1. A steady state simulation without pumping is used to determine the spatial

distribution of heads in the model domain.

2. A transient model is used to simulate the effect of pumping in a wet season

while at the dry season there is no pumping at all. The heads obtained in
the steady state simulation are used as the initial heads for the transient
simulation.

4.1.1 Steady state simulation

This first example shows how to develop a groundwater flow model using the
r.gmtg module. An unconfined aquifer has a hydraulic conductivity of 160 m/day
and a recharge of 7.5 104 m/day. The elevations of the aquifer top and bottom
are 25 m and 0 m respectively. Additionaly, a total of nine wells are pumping
water from the aquifer at a rate of 3888 m3 /day, as shown in figure 1.

Creating the region to model: The first step consists in creating the region; if
you already know how to set up regions with GRASS you can skip this section.
First create a directory on which you will have all data and then change to it, then
copy or download the data files into this directory.
[jaime@civpc-08 jaime] mkdir tutorial
[jaime@civpc-08 jaime] cd tutorial
[jaime@civpc-08 tutorial]

4
Figure 1: Model domain for problem 1

5
 Figure 2: GRASS initial window Figure 3: Available regions in current di-
rectory

Figure 4: Required data to set-up a region in GRASS

This step is recommended because all MODFLOW files will be created on

this directory; to avoid overwriting of files from different models, r.gmt should be
invoked from the projects directory.
Start GRASS by typing grass5 in the command line and create the region
tutorial1 as shown in figure 2 and presss CTRL-ENTER. The next screen will
show the existing regions in the current database as figure 3 shows. Type y and
ENTER as you want to create a new region for which you need to know four items
as illustrated in figure 4. After this you need to type in y and the regions settings
as exemplified in figure 5.
After the region has been created, the next step consists in importing the data
that will be used in this example. The data is available as and ASCII file named

6
(a) Coordinate system for new region (b) Description of new region

(c) Extents of new region (d) Created region

Figure 5: Creating a region in GRASS

7
 Figure 6: Raster map imported with r.in.ascii

basemap.map. To import it use the r.in.ascii module and name the resultant map
basemap. If this map is displayed, it should be similar to Figure 6.
GRASS:tutorial > r.in.ascii input=basemap.dat output=basemap
GRASS:tutorial > d.start x0
GRASS:tutorial > d.rast basemap

We do not know the values of the map that was just imported. To find out the
number of categories in a raster map as well as some extra information on it, the
r.info command can be used:
GRASS:/MVB/MODFLOW > r.info basemap

The module r.info shows basic information about a raster map: The lim-
its,resolution and projection; in addition the data range is also displayed. For
this map the minimum value is -1 while the maximum is 2. To find out which
areas correspond to each category you need to diplay the raster map and then use
the module r.what.
We need to assign a value of 0 to those cells that are inactive; in order to do
this, the category values of basemap are reclassified into a new raster file which
will be called boundaries. To create the new map, reclassify the category value 2
into 0 and keep the values of the other two categories.

8
GRASS:> r.reclass input=basemap output=boundaries

Enter the rule or help for the format description:

> -1 = -1
> 1 = 1
> 2 = 0
> end
GRASS:>

We will also create a map with an uniform value of 1; this map will be used to
create the remainder maps for the groundwater model, as the following maps are
still needed:

Initial Heads

Hydraulic Conductivity

Recharge values

Aquifer bottom

The basemap raster map is reclassified to map area with only one category (value
1):

GRASS:> r.reclass input=basemap output=area

Enter the rule or help for the format description:

> * = 1
> end
GRASS:>

The other raster maps are now created using r.mapcalc as follows:
GRASS: > r.mapcalc H.conductivity=area*160
100%
GRASS: > r.mapcalc recharge=area*.00025
100%
GRASS: > r.mapcalc initial.heads=area*15
100%
GRASS: > r.mapcalc bottom=area*0
100%
GRASS: >

9
 The southern boundary is a specified flux boundary of 0.0672 m3 /day/m.In
order to account for this flux a well will be used at each cell with a flow of 0.0672
200 m which equals 13.4 m3 /day. To create a well file an ASCII file is imported
into GRASS using s.in.ascii. Open a text editor such as emacs and type in the
values of table 2 without the header and leaving a space between each value or
use the data available on the web site. Save this file as a plain text with emacs and
now import it using r.in.ascii:
GRASS: > s.in.ascii sites=cst.flux input=cst.flux d=3
GRASS: >

Now all required data to run the groundwater flow model have been set up.
Before running the simulation we need to check if all required data is available:
GRASS: > r.gmt simulation=1 units=4 layers=1 aqtype=1 stress=1
length=1 steps=1 tsmult=1 region=boundaries heads=initial.heads
K=H.conductivity bottom=bottom recharge=recharge wells=cst.flux
drawdownin=dd headsin=hd

The simulated head has been saved on file hd.lay1.stp1.tst1 where hd is the
name entered for the option headsin of GMT. The remainder parts of the file name
are generated automatically to facilitate the task of reading the results of each
simulation: hd.lay1.stp1.tst1 means that this map shows the head at layer 1, for
stress period (stp) 1 at the first time step (tst). Now we can create a vector map
to show drawdown values at increments of 0.5 m. To create this map the module
r.contour is used as follows:
GRASS:/tutorial > r.contour input=hd.lay1.stp1.tst1
output=ss.heads step=0.5 minlevel=15 maxlevel=20
Reading data.
Percent complete: 100%
FPRange of data: min = 15.000000 max = 19.270000
Minimum level will be 15.000000
Maximum level will be 19.000000
Continue?(y/n) [y] y

Now the head values for the simulation as well as the contours at every 0.5 m
can be displayed simultaneously to get a more representative map:
GRASS:/tutorial > d.mon x0
using default visual which is TrueColor
ncolors: 16777216

10
Table 2: Coordinates of wells for specified flux boundary

East North Layer Flow Description

100 100 1 13.4 Cflux
300 100 1 13.4 Cflux
500 100 1 13.4 Cflux
700 100 1 13.4 Cflux
900 100 1 13.4 Cflux
1100 100 1 13.4 Cflux
1300 100 1 13.4 Cflux
1500 100 1 13.4 Cflux
1700 100 1 13.4 Cflux
1900 100 1 13.4 Cflux
2100 100 1 13.4 Cflux
2300 100 1 13.4 Cflux
2500 100 1 13.4 Cflux
2700 100 1 13.4 Cflux
2900 100 1 13.4 Cflux
3100 100 1 13.4 Cflux
3300 100 1 13.4 Cflux
3500 100 1 13.4 Cflux
3700 100 1 13.4 Cflux
3900 100 1 13.4 Cflux
4100 100 1 13.4 Cflux
4300 100 1 13.4 Cflux
4500 100 1 13.4 Cflux
4700 100 1 13.4 Cflux
4900 100 1 13.4 Cflux

11
 Figure 7: Resulting heads for steady-state simulation

Graphics driver [x1] started

GRASS:/tutorial > d.rast hd.lay1.stp1.tst1
GRASS:/tutorial > d.grid size=200
GRASS:/tutorial > d.vect ss.heads color=black
GRASS:/tutorial > d.legend -m map=hd.lay1.stp1.tst1
FP map found - switching gradient legend on

Buttons:
Left: Establish a corner
Right: Accept box for legend

The resulting image should be similar to Figure 7:

12
4.1.2 Transient simulation
The result of the steady state simulation was a map showing the head distribution
on the model domain; this head will be used as the initial head for the transient
simulation. Transient simulations require more data than steady-state simulations.
Among these data are: Specific yield (Sy ) as well as extraction and recharge rates
for each stress period. For this problem the following data are provided:

1. The Specific Yield of the aquifer is estimated to be Sy =0.06 m/day

2. Recharge occurs during the wet season which lasts four months at a uniform
rate of 7.5 104 m/day.

3. Water is extracted from nine wells at a rate of 3888 m3 /day during the dry
season.
The coordinates of the nine extraction wells are in table 3 which have to be added
to the constant flux boundary wells. Any site file that is created to be used as a
well file for MODFLOW should have the following format:
East North Layer (-)Flow Id

The negative sign in flow is used to indicate that the flow is being extracted
from the aquifer; that is why for the Constant Flow boundary flow rates are posi-
tive, while extraction rates are negative.

Table 3: Coordinates of extraction wells

East North Layer P. rate ID

2300 6300 1 -3888 W-1
3700 6300 1 -3888 W-2
4700 6300 1 -3888 W-3
1700 4700 1 -3888 W-4
3300 4700 1 -3888 W-5
4300 4700 1 -3888 W-6
1700 1300 1 -3888 W-7
2700 1300 1 -3888 W-8
3700 1300 1 -3888 W-9

13
 Because we are using wells to simulate the constant head boundary, when
water is extracted from the aquifer both the extraction wells and the constant flux
boundary wells have to be in one file, so we need to paste these two files and create
one file. This file has to be imported into GRASS. It is important to tell grass that
the file has three dimensions (northing, easting and layer number):
GRASS:tutorial > s.in.ascii sites=wells input=wells d=3
GRASS:tutorial >
There are two seasons (stress periods) in this simulation: wet and dry, thus the
simulation will be run for 2 stress periods. The dry season has a length of 240
days (8 months of the year) with a recharge rate of 0 m/day, while the wet season
lasts the remainder 4 months (120 days) with a recharge rate of 0.00075 m/day.
For the first stress period a total of 12 time steps will be used while for the second
stress period only 6 time steps are required. As this is a transient simulation a
raster map with the Specific Yield (Sy ) is needed as well as the recharge maps for
each stress period. These maps are created using r.mapcalc:
GRASS:/MVB/MODFLOW > r.mapcalc Sy=0.06*area
100%
GRASS:/MVB/MODFLOW > r.mapcalc rch.1=0*area
100%
GRASS:/MVB/MODFLOW > r.mapcalc rch.2=0.00075*area
100%
GRASS:/MVB/MODFLOW >
The input for this simulation is:
GRASS:tutorial> r.gmt simulation=0 units=4 layers=1 aqtype=1
stress=2 length=240,120 steps=12,6 tsmult=1,1 region=boundaries
heads=hd.lay1.stp1.tst1 K=H.conductivity Sy=Sy bottom=bottom
recharge=rch.1,rch.2 wells=wells,cst.flux drawdownin=ddtr headsin=hdtr
The program will import a total of 36 raster maps: For both heads and draw-
down the output is 12 maps for stress period number one and 6 maps for stress
period two. The output of the simulation for time step 12 of stress period one
should be similar to figure 8:

4.1.3 Remarks for example 1

In this example both a steady-state and transient simulation of groundwater flow
was undertaken. It is important to know that more data are required for transient
simulations, especially if more than one stress period is used:

14
 (a) Heads for stress period 1 timestep 12

15

(b) Heads for stress period 2, timestep 6

Figure 8: Resulting heads for transient simulation.

 Transient simulations: Specific yield values (Sy ) are needed

Recharge in multiple stress periods: If recharge occurs at one stress period,

the remainder stress periods have zero recharge; this value has to be used
in the simulation which means that for i stress periods, i recharge maps are
needed.

Wells in multiple stress periods: The same principle described in the pre-
vious item applies to wells. A well sites map is required for every stress
period of the simulation.

16
 Figure 9: Modeling area for problem 2

4.2 Example 2: Three dimensional modeling

This exercise is also taken from Chiang (2001) and consists of a river which flows
in a valley that is bounded by granite impermeable formations both at north and
south as illustrated in figure 9.
The aquifer system consists of an unconfined upper aquifer with Kh = 5 m/day
and Kv = 0.5 m/day, for which the hydraulic heads at the upstream and down-
stream boundaries consist of fixed-head boundaries which are known and avail-
able as an ASCII data file. Beneath this unit is a confined aquifer of variable
thickness with Kh = 2 m/day and Kv = 1 m/day. These two aquifers are separated
by a silty layer 2 meters thick with Kh = 0.5 m/day and Ky = 0.05 m/day. The
confined aquifer is being exploited by three wells at a rate of 500 m3 /day which
are located as shown in figure 9 and whose coordinates are in table 4. Create a
text file and import it into GRASS using s.in.ascii

17
 Table 4: Coordinates of extraction wells

East North Layer P. rate ID

1728 1728 3 -500 Well-1
2880 3264 3 -500 Well-2
4032 1925 3 -500 Well-3

4.3 Creating the region

The first step consists in creating a directory on which all data will be stored and
from which the r.gmtg module will be used, which can be tutorial2. Following the
steps outlined in section 4.1.1 a region with the following boundaries is created:
North: 5000, east: 0, west: 6750, south: 0; a resolution of 193 m will be used for
a total of 26 rows and 35 columns. All data required for this example are available
as ASCII files and need to be imported using the r.in.ascii module.

4.4 Required data

The model to be developed in this example is a three-layer steady-state simulation
in which water is extracted by three wells from the confined aquifer (third layer in
the model); the interaction of the river with the unconfined aquifer also has to be
considered. Because this is a multi-layer simulation the following data are needed
(note the differences between this example and example 1):
1. Horizontal hydraulic conductivity for all layers
2. Vertical hydraulic conductivity
3. Top of aquifers
4. Bottom of aquifers
5. Location of wells and extraction rates
6. Vertical Conductance
7. River data: Location, elevation, conductance and stage
Download the ASCII file basemap2 for this example and using r.mapcalc de-
velop the following maps: Kh , Kv , top.1, top.2, top.3, and bottom.3.

18
 Figure 10: Vertical conductance variables

4.4.1 Vertical conductance

Whenever three dimensional modeling is attempted with MODFLOW, the VCOND
array needs to be determined and is computed according to figure 10 and equation
1.
2
VCONT(i, j,k+1/2) = (1)
Vk
(Kz )i, j,k + (KV
z)
k+1
i, j,k+1

Vertical conductance can be computed using r.mapcalc; however, when deal-

ing with an unconfined aquifer (as is the case for this example), an expected
value of heads has to be used. In this case you can use the initial heads provided
(ini.heads) or import the VCOND maps from the website.

4.4.2 River data

In order to include a river in the simulation MODFLOW requires its location,
bed elevation, stage (head) and conductance. The r.gmtg module requires three
different maps: One for river stage values, one for riverbed elevation and one for
conductance values. The conductance is computed according to equation 2.
K L W
CRIV = (2)
M
19
Where: CRIV = Hydraulic conductance of the riverbed [L2 /T] K= Hydraulic con-
ductivity of the riverdeb sediment [L/T] L= Length of the river within a cell [L]
W = Width of the river within a cell [L] M= Thickness of the riverbed [L]
The conductance values can be computed using map algebra; however the data
used in this example is available as ASCII files which need to be imported.

4.4.3 running the simulation

Considering that you have downloaded all the files for the simulation, the required
maps are created as follows:

GRASS:/tutorial2 >r.in.ascii input=basemap2 output=active

GRASS:/tutorial2 >r.in.ascii input=top.1.dat output=top.1
GRASS:/tutorial2 >r.in.ascii input=top.2.dat output=top.2
GRASS:/tutorial2 >r.in.ascii input=top.3.dat output=top.3
GRASS:/tutorial2 >r.in.ascii input=vcond.1.dat output=vcond.1
GRASS:/tutorial2 >r.in.ascii input=vcond.2.dat output=vcond.2
GRASS:/tutorial2 >r.in.ascii input=river.bed.dat output=river.bed
GRASS:/tutorial2 >r.in.ascii input=river.cond.dat output=river.cond
GRASS:/tutorial2 >r.in.ascii input=river.head.dat output=river.head
GRASS:/tutorial2 >r.in.ascii input=initial.heads.dat output=initial.heads
GRASS:/tutorial2 >s.in.ascii sites=wells input=wells2.dat d=3
GRASS:/tutorial2 > r.reclass input=basemap output=active

Enter the rule or help for the format description:

> -1 = -1
> 1 = 1
> 2 = 0
> end
GRASS:/tutorial2 > r.reclass input=basemap output=area

Enter the rule or help for the format description:

> * = 1
> end
GRASS:/tutorial2 > r.mapcalc hk.1=5*area
100%
GRASS:/tutorial2 > r.mapcalc hk.2=0.5*area
100%
GRASS:/tutorial2 > r.mapcalc hk.3=2*area

20
100%
GRASS:/tutorial2 > r.mapcalc hk.1=5*area
100%
GRASS:/tutorial2 > r.gmtg simulation=1 units=4 layers=3 aqtype=1,3,3
stress=1 length=1 steps=1 tsmult=1 region=active,active,active
heads=initial.heads,initial.heads,initial.heads K=hk.1,hk.2,hk.3
bottom=top.2,top.3,bot.3 top=top.2,top.3 vcond=vcond.1,vcond.2 wells=wells
river_heads=river.head river_cond=river.cond river_elev=river.bed
headsin=hdtest drawdownin=ddtest

Now display the heads map for the first layer, which should be a map similar
figure 11.

5 Concluding remarks
In this tutorial the usage of the module r.gmtg has been explained. This mod-
ule currently supports the following MODFLOW optional packages: river, wells,
recharge and drains. The drain package requires a sites map for every stress period
and the following data:

Easting Northing Layer Elevation Conductance ID

21
Figure 11: Head distribution in the first layer of example 2

22
References
Anderson, M. P. and Woessner, W. W. (1992). Groundwater flow modelling.

Carrera-Hernandez, J. J. and Gaskin, J. S. (2004). Gmt: A groundwater mod-

eling tool for integrated water management. In FEM-MODFLOW and more,
Proceedings of the Conference held at Karlovy Vary, Czech Republic.

Chiang, W. H. (2001). 3-D groundwater modeling with PMWIN. Springer Verlag.

McDonald, M. G. and Harbaugh, A. W. (1988). A modular, three dimensional fi-

nite difference groundwater flow model. USGS Techniques of Water Resources
Investigation Report.

Neteler, M. and Mitasova, H. (2004). Open Source GIS: A GRASS GIS approach.
The Kluwer international series in engineering and computer science. 2nd edi-
tion edition.

A Well file for stress period one of transient simula-

tion
2300 6300 1 -3888 "W-1"
3700 6300 1 -3888 "W-2"
4700 6300 1 -3888 "W-3"
1700 4700 1 -3888 "W-4"
3300 4700 1 -3888 "W-5"
4300 4700 1 -3888 "W-6"
1700 1300 1 -3888 "W-7"
2700 1300 1 -3888 "W-8"
3700 1300 1 -3888 "W-9"
100 100 1 13.4 "Cflux"
300 100 1 13.4 "Cflux"
500 100 1 13.4 "Cflux"
700 100 1 13.4 "Cflux"
900 100 1 13.4 "Cflux"
1100 100 1 13.4 "Cflux"
1300 100 1 13.4 "Cflux"

23
1500 100 1 13.4 "Cflux"
1700 100 1 13.4 "Cflux"
1900 100 1 13.4 "Cflux"
2100 100 1 13.4 "Cflux"
2300 100 1 13.4 "Cflux"
2500 100 1 13.4 "Cflux"
2700 100 1 13.4 "Cflux"
2900 100 1 13.4 "Cflux"
3100 100 1 13.4 "Cflux"
3300 100 1 13.4 "Cflux"
3500 100 1 13.4 "Cflux"
3700 100 1 13.4 "Cflux"
3900 100 1 13.4 "Cflux"
4100 100 1 13.4 "Cflux"
4300 100 1 13.4 "Cflux"
4500 100 1 13.4 "Cflux"
4700 100 1 13.4 "Cflux"
4900 100 1 13.4 "Cflux"

24