r.topmodel(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

🌊 r.topmodel 🌊

okay so bestie, welcome to the GRASS GIS User's Manual page for r.topmodel(1) — yes the (1) means it's a user command, we love a section-1 icon 💅. Buckle up, this one's a whole hydrologic model and she is serving.

✨ NAME ✨

r.topmodel — Simulates TOPMODEL which is a physically based hydrologic model.

like, she runs a whole watershed for you. no big deal. 💧

🏷️ KEYWORDS 🏷️

raster, hydrology, model

iykyk 🌈

🚀 SYNOPSIS 🚀

r.topmodel
r.topmodel --help
r.topmodel [-p] parameters=name topidxstats=name input=name output=name
[timestep=integer]   [topidxclass=integer]   [topidx=name]
[ntopidxclasses=integer]   [outtopidxstats=name]   [--overwrite]
[--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • -p — Preprocess only and stop after generating outtopidxstats. she does the prep and dips 🫶
  • --overwrite — Allow output files to overwrite existing files. dangerous-ish energy, but she said yes 💀
  • --help — Print usage summary
  • --verbose — Verbose module output. she will tell you everything 😭
  • --quiet — Quiet module output
  • --ui — Force launching GUI dialog

🌸 Parameters 🌸

  • parameters=name [required] — Name of input TOPMODEL parameters file
  • topidxstats=name [required] — Name of input topographic index statistics file
  • input=name [required] — Name of input rainfall and potential evapotranspiration data file
  • output=name [required] — Name for output file
  • timestep=integer — Time step. Generate output for this time step
  • topidxclass=integer — Topographic index class. Generate output for this topographic index class
  • topidx=name — Name of input topographic index raster map. Must be clipped to the catchment boundary. Used for generating outtopidxstats
  • ntopidxclasses=integer — Number of topographic index classes. Used for generating outtopidxstats. Default: 30
  • outtopidxstats=name — Name for output topographic index statistics file. Requires topidx and ntopidxclasses

💅 DESCRIPTION 💅

r.topmodel simulates TOPMODEL which is a physically based hydrologic model.

that's the whole pitch, and honestly? it ate. 🔥

🧚 Parameters description 🧚

🌟 parameters

This file contains TOPMODEL parameters that describe the study area. Any lines starting with a # sign or empty lines are ignored (so go off with the commentary, she's not reading it).

# 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)
0.000075
# lnTe [ln(m^2/h)]: Areal average of the soil surface transmissivity
4.
# m [m]: Parameter controlling the decline rate of transmissivity
# See Beven and Kirkby (1979)
0.0125
# Sr0 [m]: Initial root zone storage deficit
0.0025
# Srmax [m]: Maximum root zone storage deficit
0.041
# 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.
60.
# vch [m/h]: Main channel routing velocity
20000.
# vr [m/h]: Internal subcatchment routing velocity
10000.
################################################################################
# infex: Calculate infiltration excess if not zero (integer)
0
# K0 [m/h]: Surface hydraulic conductivity
2.
# psi [m]: Wetting front suction
0.1
# dtheta: Water content change across the wetting front
0.1
################################################################################
# d [m]: Distance from the catchment outlet
#         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
heads up bestie: qs0 is literally quoting Liaw (1988) in the comments, so we keep the quote, periodt. ✨

🌧️ input

This file contains observed weather data.

# dt [h]: Time step
24
################################################################################
# R [m/dt]:  Rainfall
# Ep [m/dt]: Potential evapotranspiration
# R             Ep
0.000033        0.000000
0.000053        0.011938
0.004821        0.000000
.
.
.

rainfall and potential evapotranspiration, side by side, living their best life 🌈

⏱️ timestep

If a time step is specified, output will be generated for the specific time step in addition to the summary and total flows at the outlet. This parameter can be combined with topidxclass to specify a time step and topographic index class at the same time. If no topidxclass is given, output will be generated for all the topographic index classes.

so it's not either/or, it's and-and. we love a both situation 💅

🏔️ toptopidxclass

If a topographic index class is specified, output will be generated for the given topographic index class. This parameter can be combined with timestep. If no timestep is given, output will be generated for all the time steps.

(yeah she's spelled toptopidxclass in the manual, we don't make the rules, we just vibe with them 🙈)

🗺️ topidx, ntoptopidxclasses, outtoptidxstats

The topidx map can optionally be used for creating a new topographic index statistics file. This map has to be already clipped to the catchment boundary. The entire range of topographic index values will be divided into ntoptopidxclasses and the area ratio of each class will be reported in the outtoptidxstats file. These three parameters can be omitted unless a new topidxstats file needs to be created.

tl;dr: only reach for these three if you actually need a fresh stats file, otherwise she doesn't need them 🫶

📚 REFERENCES 📚

  • Beven, K. J., 1984. Infiltration into a class of vertically non-uniform soils. Hydrological Sciences Journal 29 (4), 425-434.
  • Beven, K. J., Kirkby, M. J., 1979. A physically based, variable contributing area model of basin hydrology. Hydrological Sciences Bulletin 24 (1), 43-69.
  • Beven K. J., R. Lamb, P. Quinn, R. Romanowicz, and J. Freer, 1995. TOPMODEL, in V.P. Singh (Ed.). Computer Models of Watershed Hydrology. Water Resources Publications.
  • Cho, H., 2000. GIS Hydrological Modeling System by Using Programming Interface of GRASS. Master’s Thesis, Department of Civil Engineering, Kyungpook National University, South Korea.
  • Liaw, S. C., 1988. Streamflow Simulation Using a Physically Based Hydrologic Model in Humid Forested Watersheds. Dissertation, Colorado State University, CO. p163.
  • Morel-Seytoux, H. J., Khanji, J., 1974. Derivation of an equation of infiltration. Water Resources Research 10 (4), 795-800.

the reading list is stacked, bestie did her homework 📖✨

👀 SEE ALSO 👀

r.fill.dir, r.mapcalc, r.topidx

How to run r.topmodel

👑 AUTHORS 👑

Huidae Cho, Hydro Laboratory, Kyungpook National University, South Korea

Based on TMOD9502.FOR by Keith Beven.

absolute legends, no cap 🫡

🔗 SOURCE CODE 🔗

Available at: r.topmodel source code (history)

Accessed: Saturday Jan 17 05:41:04 2026

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

okay that's the whole page, you're basically a hydrologist now 🌈💖 this was r.topmodel(1) from the GRASS GIS 8.4.2 Reference Manual, sourced and versioned and dated Saturday Jan 17 05:41:04 2026, © 2003-2025 GRASS Development Team. go run your watershed, queen 👑💅✨

📦 where this page comes from