[wenzeslaus]

The manual and the option description of r.sim.water describe flow_control as a permeability ratio, the probability of particles passing through a structure, while the code traps a particle when a random number is at or below the cell value, so a higher value holds back more water. This changes the documentation and the option text to say trapping probability. The code and the results are unchanged. The test test_flow_control_increases_depth merged in #7968 asserts the behavior the new text describes.

Details (AI generated)

Evidence that the documentation, not the code, is wrong: the comparison in simlib/hydro.c, the name of the trap array, the skip for cells with value 0, and the documentation sentence are all unchanged since the first commit in this repository (2008, then under raster/simwe/), when the option was still named traps. Under the permeability reading a value of 0 would be an impermeable wall, yet the code skips such cells as no structure, so the code is self-consistent only as a trapping probability. r.sim.sediment does not expose the parameter, and nothing else in the repository references it.

Verification on a 1x5 slope with seed 42, rain 100 mm/h, Manning's n 0.1 and 2 minutes: total depth 2.66 mm without flow control, 3.12 mm with a uniform value of 0.3, and 3.92 mm with 0.8, which matches the new text. The pytest suite merged in #7968 asserts the same direction in test_flow_control_increases_depth.

Translations: the changed string in main.c makes the existing translations of the old option description stale until the next Weblate template sync; the po files are managed through Weblate and are not touched here.

Suggested squash-merge commit message:

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 test test_flow_control_increases_depth added in #7968
asserts the behavior the new text describes.

The history analysis and the wording were done with AI assistance
(Claude Code).

The history analysis, the wording and this description were done with Claude Code (Opus and Fable) and reviewed by me.