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 7bf3d256d39..ba43e99c9b4 100644
--- a/raster/r.sim/r.sim.water/r.sim.water.html
+++ b/raster/r.sim/r.sim.water/r.sim.water.html
@@ -219,6 +219,52 @@ Run summary
-t -p format=json
+In Python with grass.script:
+
+
+import grass.script as gs
+
+summary = gs.parse_command(
+ "r.sim.water",
+ elevation="elevation",
+ depth="depth",
+ discharge="discharge",
+ rain_value=50,
+ man_value=0.05,
+ nwalkers=100000,
+ duration=20,
+ output_step=10,
+ random_seed=3,
+ flags="tp",
+ format="json",
+)
+print(summary["walkers_remaining"], summary["outputs"][-1]["depth"])
+
+from grass.tools import Tools
+
+tools = Tools()
+summary = tools.r_sim_water(
+ elevation="elevation",
+ depth="depth",
+ discharge="discharge",
+ rain_value=50,
+ man_value=0.05,
+ nwalkers=100000,
+ duration=20,
+ output_step=10,
+ random_seed=3,
+ flags="tp",
+ format="json",
+)
+print(summary["walkers_remaining"], summary["outputs"][-1]["depth"])
+
{
"walkers_requested": 100000,
@@ -258,63 +304,140 @@ Run summary
}
EXAMPLE
+
+This example uses the
+SIMWE sample dataset
+of the NC State University Sediment and Erosion Control Research and
+Education Facility, a 52 ha area in Raleigh, North Carolina, USA, at 1 m
+resolution. It contains a lidar-based elevation map, a land cover map
+and orthophoto bands.
+
-Reading the summary in Python:
+Set the computational region to the elevation map and derive the
+Manning's n raster map from the land cover classes with
+r.recode. Buildings (class 1), paved
+roads (2) and compacted roads and parking lots (3) get low roughness
+values, while herbaceous cover such as fields and lawns (4) and forest (5)
+get high values suitable for shallow overland flow. Water (6) gets a low
+value. See the
+r.manning
+addon for an explanation of Manning's n and reference values for common
+land cover classifications.
+
+
+g.region raster=elevation
+r.recode input=landcover output=mannings rules=- <<EOF
+1:1:0.012
+2:2:0.014
+3:3:0.025
+4:4:0.24
+5:5:0.35
+6:6:0.04
+EOF
+
import grass.script as gs
-summary = gs.parse_command(
- "r.sim.water",
- elevation="elevation",
- depth="depth",
- discharge="discharge",
- flags="p",
- format="json",
+gs.run_command("g.region", raster="elevation")
+manning = {
+ 1: 0.012, # buildings
+ 2: 0.014, # paved roads
+ 3: 0.025, # compacted roads and parking lots
+ 4: 0.24, # herbaceous cover
+ 5: 0.35, # forest
+ 6: 0.04, # water
+}
+rules = "\n".join(f"{k}:{k}:{v}" for k, v in manning.items())
+gs.write_command(
+ "r.recode", input="landcover", output="mannings", rules="-", stdin=rules
)
-print(summary["walkers_remaining"], summary["outputs"][-1]["depth"])
EXAMPLE
+In Python with grass.tools:
+
+
+from io import StringIO
+
+from grass.tools import Tools
+
+tools = Tools()
+tools.g_region(raster="elevation")
+manning = {
+ 1: 0.012, # buildings
+ 2: 0.014, # paved roads
+ 3: 0.025, # compacted roads and parking lots
+ 4: 0.24, # herbaceous cover
+ 5: 0.35, # forest
+ 6: 0.04, # water
+}
+rules = "\n".join(f"{k}:{k}:{v}" for k, v in manning.items())
+tools.r_recode(input="landcover", output="mannings", rules=StringIO(rules))
+
+
+
+
+ Figure: Manning's n derived from land cover with low values for
+ buildings and roads and high values for fields and forest.
+
+
+Simulate 30 minutes of overland flow with a uniform rainfall excess of
+20 mm/hr. The random seed makes the run reproducible.
-# set computational region
-g.region raster=elev_lid792_1m -p
+r.sim.water elevation=elevation man=mannings rain_value=20 depth=depth \
+ duration=30 random_seed=1
+
+gs.run_command(
+ "r.sim.water",
+ elevation="elevation",
+ man="mannings",
+ rain_value=20,
+ depth="depth",
+ duration=30,
+ random_seed=1,
+)
-# increase the computational region by 350 meters
-g.region e=e+350
-# initiate the rendering
-d.mon start=cairo output=r_sim_water_water_depth.png
-# render raster, legend, etc.
-d.rast map=water_depth_1m
-d.legend raster=water_depth_1m title="Water depth [m]" label_step=0.10 font=sans at=20,80,70,75
-d.barscale at=67,10 length=250 segment=5 font=sans
-d.northarrow at=90,25
-# finish the rendering
-d.mon stop=cairo
+tools.r_sim_water(
+ elevation="elevation",
+ man="mannings",
+ rain_value=20,
+ depth="depth",
+ duration=30,
+ random_seed=1,
+)
-
-
- Figure: Simulated water depth map in the rural area of
- the North Carolina sample dataset.
+
+
+ Figure: Simulated water depth in meters after 30 minutes of rainfall
+ shown over shaded relief.
+
+
+
+
+
+ Figure: Water depth of at least 0.1 m shown over the orthophoto, with
+ flow concentrated in ditches and channels and ponding in depressions.