r.richdem.flowaccumulation

Calculate flow accumulation using RichDEM

Command linePython (grass.tools)Python (grass.script)

r.richdem.flowaccumulation input=name output=name [method=string] [exponent=float] [weights=name] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.richdem.flowaccumulation input=name output=name

grass.tools.Tools.r_richdem_flowaccumulation(input, output, method="D8", exponent=None, weights=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.r_richdem_flowaccumulation(input="name", output="name")

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

grass.script.run_command("r.richdem.flowaccumulation", input, output, method="D8", exponent=None, weights=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("r.richdem.flowaccumulation", input="name", output="name")

Parameters

Command linePython (grass.tools)Python (grass.script)

input=name [required]
    Input elevation raster
output=name [required]
    Output flow accumulation raster
method=string
    Flow accumulation method
    Allowed values: D8, D4, Dinf, Tarboton, Quinn, Holmgren, Freeman, Rho8, Rho4, FairfieldLeymarieD8, FairfieldLeymarieD4, OCallaghanD8, OCallaghanD4
    Default: D8
exponent=float
    Exponent for Holmgren or Freeman methods
weights=name
    Optional flow accumulation weights raster
--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

input : str | np.ndarray, required
    Input elevation raster
    Used as: input, raster, name
output : str | type(np.ndarray) | type(np.array) | type(gs.array.array), required
    Output flow accumulation raster
    Used as: output, raster, name
method : str, optional
    Flow accumulation method
    Allowed values: D8, D4, Dinf, Tarboton, Quinn, Holmgren, Freeman, Rho8, Rho4, FairfieldLeymarieD8, FairfieldLeymarieD4, OCallaghanD8, OCallaghanD4
    Default: D8
exponent : float, optional
    Exponent for Holmgren or Freeman methods
weights : str | np.ndarray, optional
    Optional flow accumulation weights raster
    Used as: input, 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.

input : str, required
    Input elevation raster
    Used as: input, raster, name
output : str, required
    Output flow accumulation raster
    Used as: output, raster, name
method : str, optional
    Flow accumulation method
    Allowed values: D8, D4, Dinf, Tarboton, Quinn, Holmgren, Freeman, Rho8, Rho4, FairfieldLeymarieD8, FairfieldLeymarieD4, OCallaghanD8, OCallaghanD4
    Default: D8
exponent : float, optional
    Exponent for Holmgren or Freeman methods
weights : str, optional
    Optional flow accumulation weights raster
    Used as: input, 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

DESCRIPTION

r.richdem.flowaccumulation calculates the contributing (upslope) area for each cell in a DEM using one of several flow routing algorithms. The accumulation value at each cell equals the total number of cells---or total weighted flow---draining through it.

Flow accumulation is a fundamental quantity in terrain analysis: large values identify channels and valley bottoms, while the spatial pattern of accumulation describes the drainage network. The input DEM should be hydrologically conditioned (depressions filled or breached) before running this module.

NOTES

Flow routing methods

r.richdem.flowaccumulation supports both single-flow-direction (SFD) and multiple-flow-direction (MFD) algorithms:

Single flow direction (SFD) --- each cell drains entirely to one neighbor:

D8 / OCallaghanD8 --- steepest descent among 8 neighbors. Classic algorithm for hydrological applications (O'Callaghan and Mark, 1984).
D4 / OCallaghanD4 --- steepest descent among 4 cardinal neighbors only.
Rho8 / FairfieldLeymarieD8 --- stochastic D8: the downhill neighbor is selected probabilistically in proportion to slope, reducing the parallel-flow artifact of D8 (Fairfield and Leymarie, 1991).
Rho4 / FairfieldLeymarieD4 --- stochastic D4.

Multiple flow direction (MFD) --- flow is distributed across multiple downhill neighbors:

Dinf / Tarboton --- flow is apportioned between the two neighbors bracketing the steepest downhill direction (Tarboton, 1997). Reduces flow concentration artifacts compared to D8.
Quinn --- flow distributed to all lower neighbors weighted by slope; equivalent to Holmgren with exponent = 1 (Quinn et al., 1991).
Holmgren --- flow distributed to all lower neighbors weighted by slope raised to an exponent (requires exponent parameter). Larger exponents produce more concentrated flow similar to D8; exponent = 1 is equivalent to Quinn (Holmgren, 1994).
Freeman --- similar to Holmgren; distributes flow using slope raised to an exponent (requires exponent parameter) (Freeman, 1991).

Weighted accumulation

The optional weights map specifies the amount of flow generated by each cell. If omitted, each cell contributes 1 unit. Weights can represent precipitation, effective rainfall, or any other spatially variable runoff source.

Pre-processing

Depressions and flat areas cause incorrect or undefined flow directions. Apply r.richdem.filldepressions (with optional -e flag) or r.richdem.breachdepressions followed by r.richdem.resolveflats before computing flow accumulation.

REQUIREMENTS

This module requires the RichDEM Python package, which is not a standard GRASS GIS dependency and must be installed separately:

pip install richdem

If pip install richdem fails (the package requires a C++ compiler), build from source:

git clone https://github.com/r-barnes/richdem.git
cd richdem/wrappers/pyrichdem
pip install -e .

Ensure that RichDEM is installed into the same Python environment used by GRASS GIS.

EXAMPLES

Compute D8 flow accumulation on a pre-filled DEM:

r.richdem.filldepressions input=dem output=dem_filled
r.richdem.flowaccumulation input=dem_filled output=accum_d8

Use D-infinity flow routing:

r.richdem.flowaccumulation input=dem_filled output=accum_dinf method=Dinf

Use the Holmgren algorithm with exponent 4 (moderately convergent):

r.richdem.flowaccumulation input=dem_filled output=accum_holmgren method=Holmgren exponent=4

Weight flow accumulation by a precipitation raster:

r.richdem.flowaccumulation input=dem_filled output=discharge method=D8 weights=precip_mm

REFERENCES

O'Callaghan, J.F., Mark, D.M. (1984). The extraction of drainage networks from digital elevation data. Computer Vision, Graphics, and Image Processing Vol 28(3), pp 323--344. DOI: 10.1016/S0734-189X(84)80011-0
Fairfield, J., Leymarie, P. (1991). Drainage networks from grid digital elevation models. Water Resources Research Vol 27(5), pp 709--717. DOI: 10.1029/90WR02658
Freeman, T.G. (1991). Calculating catchment area with divergent flow based on a regular grid. Computers & Geosciences Vol 17(3), pp 413--422. DOI: 10.1016/0098-3004(91)90048-I
Quinn, P., Beven, K., Chevallier, P., Planchon, O. (1991). The prediction of hillslope flow paths for distributed hydrological modelling using digital terrain models. Hydrological Processes Vol 5(1), pp 59--79. DOI: 10.1002/hyp.3360050106
Holmgren, P. (1994). Multiple flow direction algorithms for runoff modelling in grid based elevation models: An empirical evaluation. Hydrological Processes Vol 8(4), pp 327--334. DOI: 10.1002/hyp.3360080405
Tarboton, D.G. (1997). A new method for the determination of flow directions and upslope areas in grid digital elevation models. Water Resources Research Vol 33(2), pp 309--319. DOI: 10.1029/96WR03137
Barnes, R. (2016). RichDEM: Terrain Analysis Software. URL: http://github.com/r-barnes/richdem

AUTHORS

Richard Barnes (RichDEM library)

GRASS GIS bindings: Andrew D. Wickert, with assistance from Claude Sonnet 4.6

SOURCE CODE

Available at: r.richdem.flowaccumulation source code (history)
Latest change: Saturday May 30 11:40:25 2026 in commit 6b92b36

r.richdem.flowaccumulation

Parameters

DESCRIPTION

NOTES

Flow routing methods

Weighted accumulation

Pre-processing

REQUIREMENTS

EXAMPLES

REFERENCES

SEE ALSO

AUTHORS

SOURCE CODE