r.sim.sediment
Sediment transport and erosion/deposition simulation using path sampling method (SIMWE).
r.sim.sediment [-sp] elevation=name water_depth=name [dx=name] [dy=name] detachment_coeff=name transport_coeff=name shear_stress=name [man=name] [man_value=float] [observation=name] [transport_capacity=name] [tlimit_erosion_deposition=name] [sediment_concentration=name] [sediment_flux=name] [erosion_deposition=name] [logfile=name] [walkers_output=name] [nwalkers=integer] [duration=integer] [mintimestep=float] [output_step=integer] [diffusion_coeff=float] [random_seed=integer] [nprocs=integer] format=name [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.sim.sediment elevation=name water_depth=name detachment_coeff=name transport_coeff=name shear_stress=name format=plain
grass.tools.Tools.r_sim_sediment(elevation, water_depth, dx=None, dy=None, detachment_coeff, transport_coeff, shear_stress, man=None, man_value=0.1, observation=None, transport_capacity=None, tlimit_erosion_deposition=None, sediment_concentration=None, sediment_flux=None, erosion_deposition=None, logfile=None, walkers_output=None, nwalkers=None, duration=10, mintimestep=0.0, output_step=2, diffusion_coeff=0.8, random_seed=None, nprocs=1, format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.r_sim_sediment(elevation="name", water_depth="name", detachment_coeff="name", transport_coeff="name", shear_stress="name", format="json")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
grass.script.parse_command("r.sim.sediment", elevation, water_depth, dx=None, dy=None, detachment_coeff, transport_coeff, shear_stress, man=None, man_value=0.1, observation=None, transport_capacity=None, tlimit_erosion_deposition=None, sediment_concentration=None, sediment_flux=None, erosion_deposition=None, logfile=None, walkers_output=None, nwalkers=None, duration=10, mintimestep=0.0, output_step=2, diffusion_coeff=0.8, random_seed=None, nprocs=1, format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.parse_command("r.sim.sediment", elevation="name", water_depth="name", detachment_coeff="name", transport_coeff="name", shear_stress="name", format="json")
Parameters
elevation=name [required]
Name of input elevation raster map
water_depth=name [required]
Name of water depth raster map [m]
dx=name
Name of x-derivatives raster map [m/m]
Computed from elevation map if not given
dy=name
Name of y-derivatives raster map [m/m]
Computed from elevation map if not given
detachment_coeff=name [required]
Name of detachment capacity coefficient raster map [s/m]
transport_coeff=name [required]
Name of transport capacity coefficient raster map [s]
shear_stress=name [required]
Name of critical shear stress raster map [Pa]
man=name
Name of Manning's n raster map
man_value=float
Manning's n unique value
Default: 0.1
observation=name
Name of sampling locations vector points map
Or data source for direct OGR access
transport_capacity=name
Name for output transport capacity raster map [kg/ms]
tlimit_erosion_deposition=name
Name for output transport limited erosion-deposition raster map [kg/m2s]
sediment_concentration=name
Name for output sediment concentration raster map [particle/m3]
sediment_flux=name
Name for output sediment flux raster map [kg/ms]
erosion_deposition=name
Name for output erosion-deposition raster map [kg/m2s]
logfile=name
Name for sampling points output text file. For each observation vector point the time series of sediment transport is stored.
walkers_output=name
Base name of the output walkers vector points map
nwalkers=integer
Number of walkers
duration=integer
Duration of the simulated water flow [minutes]
Default: 10
mintimestep=float
Minimum time step for the simulation [seconds]
A larger minimum time step substantially reduces processing time, but at the cost of accuracy
Default: 0.0
output_step=integer
Time interval for creating output maps [minutes]
Default: 2
diffusion_coeff=float
Water diffusion constant
Default: 0.8
random_seed=integer
Seed for random number generator
The same seed can be used to obtain same results or random seed can be generated by other means.
nprocs=integer
Number of threads which will be used for parallel computation.
Default: 1
format=name [required]
Output format
Allowed values: plain, json
Default: plain
plain: Plain text output
json: JSON (JavaScript Object Notation)
-s
Generate random seed
Automatically generates random seed for random number generator (use when you don't want to provide the seed option)
-p
Print run summary to standard output
--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 | np.ndarray, required
Name of input elevation raster map
Used as: input, raster, name
water_depth : str | np.ndarray, required
Name of water depth raster map [m]
Used as: input, raster, name
dx : str | np.ndarray, optional
Name of x-derivatives raster map [m/m]
Computed from elevation map if not given
Used as: input, raster, name
dy : str | np.ndarray, optional
Name of y-derivatives raster map [m/m]
Computed from elevation map if not given
Used as: input, raster, name
detachment_coeff : str | np.ndarray, required
Name of detachment capacity coefficient raster map [s/m]
Used as: input, raster, name
transport_coeff : str | np.ndarray, required
Name of transport capacity coefficient raster map [s]
Used as: input, raster, name
shear_stress : str | np.ndarray, required
Name of critical shear stress raster map [Pa]
Used as: input, raster, name
man : str | np.ndarray, optional
Name of Manning's n raster map
Used as: input, raster, name
man_value : float, optional
Manning's n unique value
Default: 0.1
observation : str, optional
Name of sampling locations vector points map
Or data source for direct OGR access
Used as: input, vector, name
transport_capacity : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Name for output transport capacity raster map [kg/ms]
Used as: output, raster, name
tlimit_erosion_deposition : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Name for output transport limited erosion-deposition raster map [kg/m2s]
Used as: output, raster, name
sediment_concentration : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Name for output sediment concentration raster map [particle/m3]
Used as: output, raster, name
sediment_flux : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Name for output sediment flux raster map [kg/ms]
Used as: output, raster, name
erosion_deposition : str | type(np.ndarray) | type(np.array) | type(gs.array.array), optional
Name for output erosion-deposition raster map [kg/m2s]
Used as: output, raster, name
logfile : str, optional
Name for sampling points output text file. For each observation vector point the time series of sediment transport is stored.
Used as: output, file, name
walkers_output : str, optional
Base name of the output walkers vector points map
Used as: output, vector, name
nwalkers : int, optional
Number of walkers
duration : int, optional
Duration of the simulated water flow [minutes]
Default: 10
mintimestep : float, optional
Minimum time step for the simulation [seconds]
A larger minimum time step substantially reduces processing time, but at the cost of accuracy
Default: 0.0
output_step : int, optional
Time interval for creating output maps [minutes]
Default: 2
diffusion_coeff : float, optional
Water diffusion constant
Default: 0.8
random_seed : int, optional
Seed for random number generator
The same seed can be used to obtain same results or random seed can be generated by other means.
nprocs : int, optional
Number of threads which will be used for parallel computation.
Default: 1
format : str, required
Output format
Used as: name
Allowed values: plain, json
plain: Plain text output
json: JSON (JavaScript Object Notation)
Default: plain
flags : str, optional
Allowed values: s, p
s
Generate random seed
Automatically generates random seed for random number generator (use when you don't want to provide the seed option)
p
Print run summary to standard output
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.
elevation : str, required
Name of input elevation raster map
Used as: input, raster, name
water_depth : str, required
Name of water depth raster map [m]
Used as: input, raster, name
dx : str, optional
Name of x-derivatives raster map [m/m]
Computed from elevation map if not given
Used as: input, raster, name
dy : str, optional
Name of y-derivatives raster map [m/m]
Computed from elevation map if not given
Used as: input, raster, name
detachment_coeff : str, required
Name of detachment capacity coefficient raster map [s/m]
Used as: input, raster, name
transport_coeff : str, required
Name of transport capacity coefficient raster map [s]
Used as: input, raster, name
shear_stress : str, required
Name of critical shear stress raster map [Pa]
Used as: input, raster, name
man : str, optional
Name of Manning's n raster map
Used as: input, raster, name
man_value : float, optional
Manning's n unique value
Default: 0.1
observation : str, optional
Name of sampling locations vector points map
Or data source for direct OGR access
Used as: input, vector, name
transport_capacity : str, optional
Name for output transport capacity raster map [kg/ms]
Used as: output, raster, name
tlimit_erosion_deposition : str, optional
Name for output transport limited erosion-deposition raster map [kg/m2s]
Used as: output, raster, name
sediment_concentration : str, optional
Name for output sediment concentration raster map [particle/m3]
Used as: output, raster, name
sediment_flux : str, optional
Name for output sediment flux raster map [kg/ms]
Used as: output, raster, name
erosion_deposition : str, optional
Name for output erosion-deposition raster map [kg/m2s]
Used as: output, raster, name
logfile : str, optional
Name for sampling points output text file. For each observation vector point the time series of sediment transport is stored.
Used as: output, file, name
walkers_output : str, optional
Base name of the output walkers vector points map
Used as: output, vector, name
nwalkers : int, optional
Number of walkers
duration : int, optional
Duration of the simulated water flow [minutes]
Default: 10
mintimestep : float, optional
Minimum time step for the simulation [seconds]
A larger minimum time step substantially reduces processing time, but at the cost of accuracy
Default: 0.0
output_step : int, optional
Time interval for creating output maps [minutes]
Default: 2
diffusion_coeff : float, optional
Water diffusion constant
Default: 0.8
random_seed : int, optional
Seed for random number generator
The same seed can be used to obtain same results or random seed can be generated by other means.
nprocs : int, optional
Number of threads which will be used for parallel computation.
Default: 1
format : str, required
Output format
Used as: name
Allowed values: plain, json
plain: Plain text output
json: JSON (JavaScript Object Notation)
Default: plain
flags : str, optional
Allowed values: s, p
s
Generate random seed
Automatically generates random seed for random number generator (use when you don't want to provide the seed option)
p
Print run summary to standard output
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.sim.sediment is a landscape scale, simulation model of soil erosion, sediment transport and deposition caused by flowing water designed for spatially variable terrain, soil, cover and rainfall excess conditions. The soil erosion model is based on the theory used in the USDA WEPP hillslope erosion model, but it has been generalized to 2D flow. The solution is based on the concept of duality between fields and particles and the underlying equations are solved by Green's function Monte Carlo method, to provide robustness necessary for spatially variable conditions and high resolutions (Mitas and Mitasova 1998). Key inputs of the model include the following raster maps: elevation (elevation [m]), flow gradient given by the first-order partial derivatives of elevation field (dx and dy raster maps are optional), overland flow water depth (water_depth [m]), detachment capacity coefficient (detachment_coeff [s/m]), transport capacity coefficient (transport_coeff [s]), critical shear stress (shear_stress [Pa]) and surface roughness coefficient called Manning's n (man raster map). Partial derivatives can be computed by v.surf.rst or r.slope.aspect module. The data are automatically converted from feet to metric system using database/projection information, so the elevation always should be in meters. The water depth file can be computed using r.sim.water module. Other parameters must be determined using field measurements or reference literature (see suggested values in Notes and References).
Output includes transport capacity raster map transport_capacity in [kg/ms], transport capacity limited erosion/deposition raster map tlimit_erosion_deposition [kg/m^2s] that are output almost immediately and can be viewed while the simulation continues. Sediment flow rate raster map sediment_flux [kg/ms], and net erosion/deposition raster map [kg/m^2s] can take longer time depending on time step and simulation time. Simulation time is controlled by duration [minutes] parameter. If the resulting erosion/deposition map is noisy, higher number of walkers, given by nwalkers should be used.
Increasing the number of threads with nprocs does not really speed up the simulation.
NOTES
Run summary
With the -p flag, a summary of the run is printed to standard output
after the maps are written. The format option selects plain text
(one key: value pair per line) or JSON. Without -p, nothing is
printed to standard output regardless of format. The values are also
stored in the history of the sediment_flux raster map under the same
keys (see r.info).
The keys are the same as for r.sim.water with these differences:
| Key | Meaning | Unit |
|---|---|---|
time_step_sediment |
Time step limit derived from the sediment transport parameters, null when no cell exceeds the critical shear stress |
s |
velocity_max |
Maximum flow velocity over the defined cells | m/s |
sigma_max |
Maximum first order reaction coefficient (detachment to transport capacity ratio) over the defined cells | 1/m |
mean_source_rate |
Mean sediment source (detachment) rate | kg/m^2s |
mean_infiltration |
Not reported | |
transport_capacity, tlimit_erosion_deposition |
Names of these maps, which are written once before the simulation starts, or null when not requested |
|
outputs |
A single entry with the simulated_time (s), timestamp and walkers_remaining at the time of writing, and the names of the sediment_concentration, sediment_flux, erosion_deposition and walkers maps, or null for maps which were not requested |
Summary of a run in JSON:
r.sim.sediment elevation=elevation water_depth=water_depth detachment_coeff=detachment \
transport_coeff=transport shear_stress=shear_stress man_value=1 \
sediment_flux=flux erosion_deposition=erdep transport_capacity=tc \
duration=1 random_seed=1 -p format=json
{
"walkers_requested": 60,
"walkers_generated": 78,
"walkers_remaining": 43,
"duration": 60,
"simulated_time": 54.891343113611583,
"time_step": 5.4891343113611581,
"time_step_sediment": 70.517234241515013,
"iterations_planned": 10,
"iterations_completed": 10,
"stopped_early": false,
"mean_velocity": 0.1821780891624834,
"velocity_max": 0.21544346900318839,
"sigma_max": 0.052657639041437901,
"mean_mannings_n": 1,
"mean_source_rate": 0.56025284041612944,
"threads": 1,
"transport_capacity": "tc",
"tlimit_erosion_deposition": null,
"outputs": [
{
"simulated_time": 54.891343113611583,
"timestamp": "1 minutes",
"walkers_remaining": 43,
"sediment_concentration": null,
"sediment_flux": "flux",
"erosion_deposition": "erdep",
"walkers": null
}
]
}
REFERENCES
Mitasova, H., Thaxton, C., Hofierka, J., McLaughlin, R., Moore, A., Mitas L., 2004, Path sampling method for modeling overland water flow, sediment transport and short term terrain evolution in Open Source GIS. In: C.T. Miller, M.W. Farthing, V.G. Gray, G.F. Pinder eds., Proceedings of the XVth International Conference on Computational Methods in Water Resources (CMWR XV), June 13-17 2004, Chapel Hill, NC, USA, Elsevier, pp. 1479-1490.
Mitasova H, Mitas, L., 2000, Modeling spatial processes in multiscale framework: exploring duality between particles and fields, plenary talk at GIScience2000 conference, Savannah, GA.
Mitas, L., and Mitasova, H., 1998, Distributed soil erosion simulation for effective erosion prevention. Water Resources Research, 34(3), 505-516.
Mitasova, H., Mitas, L., 2001, Multiscale soil erosion simulations for land use management, In: Landscape erosion and landscape evolution modeling, Harmon R. and Doe W. eds., Kluwer Academic/Plenum Publishers, pp. 321-347.
Neteler, M. and Mitasova, H., 2008, Open Source GIS: A GRASS GIS Approach. Third Edition. The International Series in Engineering and Computer Science: Volume 773. Springer New York Inc, p. 406.
SEE ALSO
v.surf.rst, r.slope.aspect, r.sim.water
AUTHORS
Helena Mitasova, Lubos Mitas
North Carolina State University
hmitaso@unity.ncsu.edu
Jaroslav Hofierka
GeoModel, s.r.o. Bratislava, Slovakia
Chris Thaxton
North Carolina State University
csthaxto@unity.ncsu.edu
SOURCE CODE
Available at: r.sim.sediment source code
(history)
Latest change: Wednesday Sep 30 09:38:16 2026 in commit 678916f