From 68a97158265c26f6f29decb31c829810dccafc1d Mon Sep 17 00:00:00 2001 From: Vaclav Petras Date: Mon, 28 Sep 2026 22:30:02 -0400 Subject: [PATCH] r.sim.water: Document flow_control as trapping probability The manual and the option description called flow_control a permeability ratio, the probability of particles to pass through a structure, but the code traps a particle (reverses its velocity and scales it to 10%) when a uniform random number is at or below the cell value, so higher values increase depth. The comparison, the name of the trap array, the skip for cells with value 0, and the documentation text are all unchanged since the first commit in the repository (db49180dd7, 2008, then under raster/simwe/), where the option was still named traps, so the code is not a later regression and is self-consistent only under the trapping reading. Correct the documentation rather than the code to keep results unchanged for existing users. r.sim.sediment does not expose this parameter. The history analysis and the wording were done with AI assistance (Claude Code). --- raster/r.sim/r.sim.water/main.c | 2 +- raster/r.sim/r.sim.water/r.sim.water.html | 9 +++++---- raster/r.sim/r.sim.water/r.sim.water.md | 10 ++++++---- 3 files changed, 12 insertions(+), 9 deletions(-) diff --git a/raster/r.sim/r.sim.water/main.c b/raster/r.sim/r.sim.water/main.c index 4272922f354..98c96c2f411 100644 --- a/raster/r.sim/r.sim.water/main.c +++ b/raster/r.sim/r.sim.water/main.c @@ -181,7 +181,7 @@ int main(int argc, char *argv[]) parm.traps->key = "flow_control"; parm.traps->required = NO; parm.traps->description = - _("Name of flow controls raster map (permeability ratio 0-1)"); + _("Name of flow controls raster map (trapping probability 0-1)"); parm.traps->guisection = _("Input"); parm.observation = G_define_standard_option(G_OPT_V_INPUT); diff --git a/raster/r.sim/r.sim.water/r.sim.water.html b/raster/r.sim/r.sim.water/r.sim.water.html index bfb25e1e740..6e967bfe70d 100644 --- a/raster/r.sim/r.sim.water/r.sim.water.html +++ b/raster/r.sim/r.sim.water/r.sim.water.html @@ -66,10 +66,11 @@

DESCRIPTION

infil or a single value infil_value in [mm/hr] that control the rate of infiltration for the already flowing water, effectively reducing the flow depth and discharge. -Overland flow can be further controlled by permeable check dams or similar type of structures, -the user can provide a map of these structures and their permeability ratio -in the map flow_control that defines the probability of particles to pass -through the structure (the values will be 0-1). +Overland flow can be further controlled by permeable check dams or similar types of structures. +The user can provide a map of these structures as flow_control with values 0-1 +that give the probability of a particle being trapped by the structure at each time step. +A trapped particle is moved slightly back instead of forward, so a higher value means lower +permeability, holding back more water and increasing the flow depth at the structure.

Output includes a water depth raster map depth in [m], and a water discharge diff --git a/raster/r.sim/r.sim.water/r.sim.water.md b/raster/r.sim/r.sim.water/r.sim.water.md index 8980e643ba7..37775d38121 100644 --- a/raster/r.sim/r.sim.water/r.sim.water.md +++ b/raster/r.sim/r.sim.water/r.sim.water.md @@ -58,10 +58,12 @@ overland flow infiltration rate map **infil** or a single value **infil_value** in \[mm/hr\] that control the rate of infiltration for the already flowing water, effectively reducing the flow depth and discharge. Overland flow can be further controlled by permeable check -dams or similar type of structures, the user can provide a map of these -structures and their permeability ratio in the map **flow_control** that -defines the probability of particles to pass through the structure (the -values will be 0-1). +dams or similar types of structures. The user can provide a map of +these structures as **flow_control** with values 0-1 that give the +probability of a particle being trapped by the structure at each time +step. A trapped particle is moved slightly back instead of forward, so +a higher value means lower permeability, holding back more water and +increasing the flow depth at the structure. Output includes a water depth raster map **depth** in \[m\], and a water discharge raster map **discharge** in \[m3/s\]. The **error** raster map