Skip to content

r.timeofconcentration

Computes per-cell time of concentration (Tc) using the Kirpich equation from longest upstream flow-path length and path-average slope.

r.timeofconcentration elevation=name direction=name streams=name time_concentration=name [outlets=name] [slope_min=float] [length_min=float] [vertical_units=string] [factor=float] [length=name] [drop=name] [sbar=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.timeofconcentration elevation=name direction=name streams=name time_concentration=name

grass.script.run_command("r.timeofconcentration", elevation, direction, streams, time_concentration, outlets=None, slope_min=1e-4, length_min=10, vertical_units="meters", factor=None, length=None, drop=None, sbar=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.timeofconcentration", elevation="name", direction="name", streams="name", time_concentration="name")

grass.tools.Tools.r_timeofconcentration(elevation, direction, streams, time_concentration, outlets=None, slope_min=1e-4, length_min=10, vertical_units="meters", factor=None, length=None, drop=None, sbar=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_timeofconcentration(elevation="name", direction="name", streams="name", time_concentration="name")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

Parameters

elevation=name [required]
    Name of input elevation raster map [m]
direction=name [required]
    Name of input flow direction raster map (from r.watershed or r.stream.extract)
streams=name [required]
    Name of input stream raster map consistent with 'direction' (from r.watershed or r.stream.extract)
time_concentration=name [required]
    Name for output time of concentration raster map [hours]
outlets=name
    Name of optional input outlets raster map; when set, Tc is reported only at these cells
slope_min=float
    Minimum path-average slope (unitless) to avoid division by zero on flats
    Default: 1e-4
length_min=float
    Minimum upstream flow-path length to report Tc [m]
    Default: 10
vertical_units=string
    Vertical units of elevation raster (converted to meters internally)
    Allowed values: meters, feet, factor
    Default: meters
factor=float
    Conversion factor to meters when vertical_units=factor (ensure factor * units = meters)
length=name
    Name for optional output longest upstream flow-path length raster map L [m]
drop=name
    Name for optional output flow-path elevation drop raster map delta_z (>= 0) [m]
sbar=name
    Name for optional output path-average slope raster map S_bar = max(delta_z / L, slope_min) [unitless]
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

elevation : str, required
    Name of input elevation raster map [m]
    Used as: input, raster, name
direction : str, required
    Name of input flow direction raster map (from r.watershed or r.stream.extract)
    Used as: input, raster, name
streams : str, required
    Name of input stream raster map consistent with 'direction' (from r.watershed or r.stream.extract)
    Used as: input, raster, name
time_concentration : str, required
    Name for output time of concentration raster map [hours]
    Used as: output, raster, name
outlets : str, optional
    Name of optional input outlets raster map; when set, Tc is reported only at these cells
    Used as: input, raster, name
slope_min : float, optional
    Minimum path-average slope (unitless) to avoid division by zero on flats
    Default: 1e-4
length_min : float, optional
    Minimum upstream flow-path length to report Tc [m]
    Default: 10
vertical_units : str, optional
    Vertical units of elevation raster (converted to meters internally)
    Allowed values: meters, feet, factor
    Default: meters
factor : float, optional
    Conversion factor to meters when vertical_units=factor (ensure factor * units = meters)
length : str, optional
    Name for optional output longest upstream flow-path length raster map L [m]
    Used as: output, raster, name
drop : str, optional
    Name for optional output flow-path elevation drop raster map delta_z (>= 0) [m]
    Used as: output, raster, name
sbar : str, optional
    Name for optional output path-average slope raster map S_bar = max(delta_z / L, slope_min) [unitless]
    Used as: output, raster, name
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

elevation : str | np.ndarray, required
    Name of input elevation raster map [m]
    Used as: input, raster, name
direction : str | np.ndarray, required
    Name of input flow direction raster map (from r.watershed or r.stream.extract)
    Used as: input, raster, name
streams : str | np.ndarray, required
    Name of input stream raster map consistent with 'direction' (from r.watershed or r.stream.extract)
    Used as: input, raster, name
time_concentration : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Name for output time of concentration raster map [hours]
    Used as: output, raster, name
outlets : str | np.ndarray, optional
    Name of optional input outlets raster map; when set, Tc is reported only at these cells
    Used as: input, raster, name
slope_min : float, optional
    Minimum path-average slope (unitless) to avoid division by zero on flats
    Default: 1e-4
length_min : float, optional
    Minimum upstream flow-path length to report Tc [m]
    Default: 10
vertical_units : str, optional
    Vertical units of elevation raster (converted to meters internally)
    Allowed values: meters, feet, factor
    Default: meters
factor : float, optional
    Conversion factor to meters when vertical_units=factor (ensure factor * units = meters)
length : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Name for optional output longest upstream flow-path length raster map L [m]
    Used as: output, raster, name
drop : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Name for optional output flow-path elevation drop raster map delta_z (>= 0) [m]
    Used as: output, raster, name
sbar : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
    Name for optional output path-average slope raster map S_bar = max(delta_z / L, slope_min) [unitless]
    Used as: output, raster, name
overwrite : bool, optional
    Allow output files to overwrite existing files
    Default: None
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned. If an array type (e.g., np.ndarray) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

Raises:

grass.tools.ToolError: When the tool ended with an error.

DESCRIPTION

r.timeofconcentration generates a raster map of time of concentration (Tc) [h] for each cell, using the Kirpich equation based on the longest upstream flow-path length and path-average slope. This method, rooted in hydrologic practice, estimates how long it takes water to travel from the farthest point in a watershed to a given cell, aiding in runoff and flood analysis. The tool leverages elevation and flow direction data, optionally deriving streams if not provided, and supports diagnostic outputs like flow length and slope. All measurements use metric units ([m], [h]).

It simplifies water travel time estimation for high-level watershed planning: water flows downhill along paths defined by terrain, and Tc reflects the slowest route’s duration, influenced by distance and slope steepness. This is key for understanding how quickly runoff reaches streams or outlets.

Inputs

elevation: Raster of elevation [m]. Required input to derive terrain slopes and flow paths.

direction: Flow-direction raster (GRASS-coded; from r.watershed or r.stream.extract). Required to trace upstream flow paths; defines the drainage network for accumulation.

streams: Stream raster and must be consistent with direction (i.e., produced from the same run of r.watershed or from r.stream.extract on the same DEM).

outlets: Optional raster of outlet points; Tc is computed only at these cells (NULL elsewhere), respecting the current mask/region.

slope_min: Minimum path-average slope [unitless] ($10^{-4}$ default). Prevents division by zero on flat areas by setting a floor value.

length_min: Minimum upstream flow-path length [m] ($10$ default). Ensures Tc is reported only where flow paths are significant.

vertical_units: optional parameter that defines the vertical units of the elevation raster. It accepts three values: meters, feet, or factor, and defaults to meters. When vertical_units=meters, no conversion is applied. When vertical_units=feet, elevation drops are multiplied by 1/3.28084 to convert them to meters. When vertical_units=factor, the module multiplies elevation drops by the user-supplied factor.

factor: Required only when vertical_units=factor. It must convert the user’s vertical unit to meters (factor × <your vertical unit> = meters), and the user is responsible for providing the correct factor.

Outputs

output: A raster map of time of concentration per cell [h], computed using the Kirpich equation:

$$ T_c \;=\; \frac{K \cdot L^a \cdot S_{\text{avg}}^b}{60} $$

where $L$ is upstream flow-path length [m], $S_{\text{avg}}$ is path-average slope [unitless], $K = 0.01947$, $a = 0.77$, $b = -0.385$ are Kirpich constants, and the result is converted from minutes to hours by dividing by 60. Tc is NULL if L < length_min or outlets are undefined.

length: Optional output raster of longest upstream flow-path length per cell [m], derived from r.stream.distance.

drop: Optional output raster of flow-path elevation drop per cell [m] ($\geq 0$), computed as the maximum elevation difference.

sbar: Optional raster of path-average slope per cell [unitless], calculated as $S_{\text{avg}} = \max(\frac{\Delta z}{L}, \text{slope}_\text{{min}})$, where $\Delta z$ is the drop and $L$ is the length.

Notes

  • CRS-aware distance r.stream.distance returns lengths in meters, even if the CRS is geographic or projected (meters or feet).
  • Static Tc Tc is a steady-state estimate; no temporal routing or storage is modeled.

EXAMPLE

These examples use the North Carolina sample dataset.

Calculate time of concentration using r.watershed and r.timeofconcentration:

# set the region
g.region -p raster=elevation

# calculate positive flow accumulation and drainage directions using r.watershed
r.watershed -sa elevation=elevation drainage=fdr stream=str threshold=10

# compute the time of concentration
r.timeofconcentration elevation=elevation direction=fdr streams=str tc=tc_nc

# use length_min parameter for coarser tc on important streams only
r.timeofconcentration elevation=elevation direction=fdr streams=str tc=tc_nc_250 length_min=250

# if the vertical units of the DEM are in feet
r.timeofconcentration elevation=elevation vunits=feet dir=fdr str=str tc=tc

# if the vertical units of the DEM are in units other than meters or feet (e.g., cm)
r.timeofconcentration elevation=elevation vunits=factor factor=0.01 dir=fdr str=str tc=tc

r_timeofconcentration example Figure: Output from r.timeofconcentration with length_min=250 on NC dataset zoomed near the watershed outlet

REFERENCES

  1. Kirpich, Z. P. (1940). Time of concentration of small agricultural watersheds. Civil Eng., 10(6), 362.
  2. United States Department of Agriculture, Natural Resources Conservation Service. (2008). National Engineering Handbook, Part 630 Hydrology: Chapter 15 – Time of Concentration (210-VI-NEH)

SEE ALSO

r.watershed, r.stream.distance

AUTHORS

Abdullah Azzam (CLAWRIM, Department of Civil and Environmental Engineering, New Mexico State University)

SOURCE CODE

Available at: r.timeofconcentration source code (history)
Latest change: Monday Nov 03 13:16:05 2025 in commit 5f894b6