Repository for Ideas & Research
Open Source GIS, Hydrologic Modeling, Optimization

r.topmodel for GRASS 6

See r.topmodel for GRASS 7.

Beven et al. (1995) wrote “TOPMODEL is not a hydrological modelling package. It is rather a set of conceptual tools that can be used to reproduce the hydrological behaviour of catchments in a distributed or semi-distributed way, in particular the dynamics of surface or subsurface contributing areas.”

Huidae Cho developed r.topmodel and r.topidx, the TOPMODEL modules for GRASS GIS, for his Master’s thesis in 2000 (Cho, 2000) based on the original TOPMODEL source code (TMOD9502.FOR) and the following implementations have been developed based on his source code (Buytaert, 2009; Conrad, 2003):

1   Data requirements

There are many possible combinations of input data accepted by r.topmodel. First, like many other hydrologic models, it requires a depressionless elevation map. A depressionless elevation map can be directly supplied or automatically generated by r.topmodel with the following sets of input options:

  • Input/Output Set 1
    • Input
      • elevation: Elevation map with depressions. It doesn’t have to be clipped to the watershed mask.
      • basin: Watershed mask
      • nidxclass: Number of topographic index classes
      • parameters: Model parameters file
      • input: Model input file
    • Output
      • depressionless: Depressionless elevation map
      • direction: Flow direction map
      • belevation: Elevation map clipped to the watershed mask, with depressions
      • topidx: Topographic index map
      • idxstats: Topographic index statistics file
      • output: Model output file
  • Input/Output Set 2
    • Input
      • elevation: Depressionless elevation map
      • basin: Watershed mask
      • nidxclass: Number of topographic index classes
      • parameters: Model parameters file
      • input: Model input file
    • Output
      • belevation: Depressionless elevation map clipped to the watershed mask
      • topidx: Topographic index map
      • idxstats: Topographic index statistics file
      • output: Model output file
    • The depressionless option should not be used to specify a depressionless DEM input because it’s used only for the name for an intermediate output which is created from the elevation map. If one has a filled elevation map, the elevation option is used to specify the map instead of depressionless.
  • Input/Output Set 3
    • Flag: -i
    • Input
      • nidxclass: Number of topographic index classes
      • idxstats: Topographic index statistics file
      • parameters: Model parameters file
      • input: Model input file
    • Output
      • output: Model output file

Input/output set 1 is usually used for the first time simulation because the user may not have various raster maps used for TOPMODEL yet. Input/output set 2 is good for those who already have filled elevation maps because it skips the step of creating the depressionless raster which may be the same as the one the user already has.

During the first simulation, r.topmodel generates one or two rasters and a statistics file, and these will be the same for next runs of the model. In this case, input/output set 3 allows the user to skip all raster map generation to save time.

2   Parameters file

The format of the parameters file is as follows (the descriptions of all parameters are commented):

# Subcatchment name
Subcatchment 1

################################################################################
# A [m^2]: Total subcatchment area
3.31697E+07

################################################################################
# qs0 [m/h]:    Initial subsurface flow per unit area
#                 "The first streamflow input is assumed to represent
#                 only the subsurface flow contribution in the watershed."
#                                                               - Liaw (1988)
# lnTe [ln(m^2/h)]: Areal average of ln(T0) = ln(Te)
# m [m]:        Scaling parameter
# Sr0 [m]:      Initial root zone storage deficit 
# Srmax [m]:    Maximum root zone storage deficit
# td [h]:       Unsaturated zone time delay per unit storage deficit
#                 if greater than 0.
#  OR
# -alpha:       Effective vertical hydraulic gradient if not greater than 0.
#                 For example, -10 means alpha = 10.
# vch [m/h]:    Main channel routing velocity
# vr [m/h]:     Internal subcatchment routing velocity

#     qs0      lnTe         m       Sr0     Srmax  td/alpha       vch        vr
 0.000075        4.    0.0125    0.0025     0.041       60.    20000.    10000.

################################################################################
# infex:        Calculate infiltration excess if not zero (integer)
# K0 [m/h]:     Surface hydraulic conductivity
# psi [m]:      Wetting front suction 
# dtheta:       Water content change across the wetting front

#   infex         K       psi    dtheta
        0        2.       0.1       0.1

################################################################################
# nch:		Number of distance increments
    6

################################################################################
# d [m]:        Distance from catchment
#                 The first value should be the mainstream distance from
#                 the subcatchment outlet to the catchment outlet.
# Ad_r:         Cumulative area ratio of subcatchment (0.0 to 1.0)
#                 The first and last values should be 0 and 1, respectively.

#   d  Ad_r
    0   0.0
 1000   0.2
 2000   0.4
 3000   0.6
 4000   0.8
 5000   1.0

3   Input file

For unit consistency over all input parameters, lengths are in meters and times are in hours except for rainfall and potential evapotranspiration time series, which are in time steps (dt).

The input file contains weather data like rainfall and potential evapotranspiration. Its format is like the following (a comment line starts with #):

# ntimesteps: Number of time steps
# dt [h]:     Time step

# ntimesteps    dt
365             24

################################################################################
# R [m/dt]:  Rainfall
# Ep [m/dt]: Potential evapotranspiration

# R             Ep
0.000033        0.000000
0.000053        0.011938
0.004821        0.000000
.
.
.

ntimesteps (365 in the example) is the number of R (rainfall) and Ep (potential evapotranspiration) values, so the above input file simulates 1 year: 365 time steps * 24 hours/time step (ntimesteps * dt).

4   Comparison of data files with the original TOPMODEL

4.1   Topmod.run

The original TOPMODEL (TMOD9502) requires one meta input file (topmod.run) and three data files. Topmod.run specifies three input files and the output file:

Title of the simulation
inputs.dat
subcat.dat
params.dat
topmod.out

4.2   Inputs.dat

The format of inputs.dat is almost the same as that of the input file of r.topmodel except for observed flows:

NSTEP DT
R PE QOBS
.
.
.
TMOD9502r.topmodelDescription
NSTEPntimestep (input file)number of time steps
DTdt (input file)time step
RR (input file)rainfall
PEEp (input file)evapotranspiration
QOBSQobs optionobserved flow

4.3   Subcat.dat

Subcat.dat contains information about the topographic index of the watershed:

NSC IMAP IOUT
SUBCAT
NAC AREA
AC ST
.
.
.
NCH
ACH D . . .
MAPFILE
TMOD9502r.topmodelDescription
NSConly one subcatchment is supportednumber of subcatchments
IMAPnot implemented in TMOD9502
IOUTlevel of output
SUBCATsubcatchment name (parameters file)subcatchment name
NACnidxclass optionnumber of topographic index classes
AREAA (parameters file)subcatchment area, TMOD9502: proportion of total area, r.topmodel: total area (note that r.topmodel supports only one subcatchment)
AC2nd column in the topidxstats filedistribution of area with topographic index, TMOD9502: sum to 1, r.topmodel: sum to total number of cells in the raster map
ST1st column in the topidxstats filetopographic index value
NCHnch (parameters file)number of channels
ACHAd_r (parameters file)cumulative distribution of area with distance D or d from outlet
Dd (parameters file)distance from subcatchment outlet
MAPFILEnot implemented in TMOD9502

4.4   Params.dat

Params.dat contains various information about the initial status of the model:

SUBCAT
SZM T0 TD CHV RV SRMAX Q0 SR0 INFEX XK0 HF DTH
TMOD9502r.topmodelDescription
SUBCATSubcatchment name (parameters file)subcatchment name
SZMm (parameters file)scaling parameter
T0lnTe (parameters file)areal average of the soil surface transmissivity
TDtd (parameters file)unsaturated zone time delay per unit storage deficit
CHVvch (parameters file)main channel routing velocity
RVvr (parameters file)internal subcatchment routing velocity
SRMAXSrmax (parameters file)maximum root zone storage deficit
Q0qs0 (parameters file)initial subsurface flow per unit area
SR0Sr0 (parameters file)initial root zone storage deficit
INFEXinfex (parameters file)calculate infiltration excess if not zero
XK0K0 (parameters file)surface hydraulic conductivity
HFpsi (parameters file)wetting front suction
DTHdtheta (parameters file)water content change across the wetting front

4.5   Topmod.out

Topmod.out contains the result of a simulation.

TMOD9502r.topmodelDescription
q(it)qttotal flow per unit area (m/timestep)
quzqvvertical flux (m/timestep)
qqssubsurface flow per unit area (m/timestep)
sbarS_meanmean saturation deficit in the watershed (m)
qofqosaturation overland flow per unit area (m/timestep)
Qttotal flow (m<sup>3</sup>/timestep)

5   Example

r.topmodel_ex.zip

This example will give you a better idea of how to prepare input data. The zip file contains r.topmodel_ex/tmod9502 and r.topmodel_ex/r.topmodel directories. Basically, the two models are the same except that the former is for TMOD9502 and the latter is for r.topmodel.

6   Manual pages

7   References

Beven, K., Lamb, R., Quinn, P., Romanowicz, R., Freer, J., 1995. TOPMODEL. In: Singh, V.P. (Ed.), Computer Models of Watershed Hydrology. Water Resources Publications, pp. 627-668.

Buytaert, W., 2009. TOPMODEL. https://source.ggy.bris.ac.uk/wiki/Topmodel, accessed in October 2013.

Cho, H., 2000. GIS Hydrological Modeling System by Using Programming Interface of GRASS. Master’s Thesis, Department of Civil Engineering, Kyungpook National University, Korea.

Conrad, O., 2003. System for Automated Geoscientific Analyses Module Library: sim_hydrology, topmodel.cpp. http://sourceforge.net/apps/trac/saga-gis/browser/trunk/saga-gis/src/modules_simulation/hydrology/sim_hydrology/topmodel.cpp, accessed in October 2013.

Liaw, S.C., 1988. Streamflow Simulation Using a Physically Based Hydrologic Model in Humid Forested Watersheds. Dissertation, Colorado State University, CO. p163.