[wenzeslaus]

Adds a benchmark script for r.sim.water with different numbers of threads and its figures in a Performance section of the documentation. The figures show the scaling with the per-walker random number states (#7980, now merged).

It also extends the nprocs plot of grass.benchmark to show the range of the runs for all metrics and to make higher resolution figures.

Details (AI generated)

The script, figures and this description were made with Claude Code and reviewed by the author of the PR.

Benchmark script

raster/r.sim/r.sim.water/benchmark/benchmark_r_sim_water_nprocs.py runs r.sim.water with nprocs 1 to 16, 3 repeats each in shuffled order (grass.benchmark.benchmark_nprocs), on the elevation raster of the SECREF North Carolina dataset (secref_northcarolina_usa_epsg6542) at 4 m, 2 m and 1 m resolution of the same extent. Coarser than 1 m, the elevation is the average of the 1 m cells (r.resamp.stats); dx and dy come from r.slope.aspect -e; r.sim.water otherwise runs with its defaults and random_seed=1. It plots time, speedup and efficiency with grass.benchmark.nprocs_plot() at 1200 x 900 pixels. It saves the results as JSON and can redo the plots from that file without rerunning (python benchmark_r_sim_water_nprocs.py r_sim_water_benchmark.json). Resolutions, maximum threads and repeats are constants at the top.

Run in a temporary mapset of the dataset:

grass --tmp-mapset ~/grassdata/secref_northcarolina_usa_epsg6542 \
    --exec python benchmark_r_sim_water_nprocs.py

grass.benchmark

The subpackage is experimental; its documentation now says that it is changed together with the benchmarks which need more from it.

• nprocs_plot() shaded the range of the runs in gray and only for time. It now shades it in each line's color for time, speedup and efficiency: for time between the fastest and the slowest run, for speedup over the ratios of every serial run to every run with the given nprocs, and for efficiency that divided by nprocs. With only a few runs per nprocs, the range of the runs is shown rather than a confidence interval.
• New figsize and dpi parameters, used here for 1200 x 900 pixel figures.
• Results without all_times are plotted again instead of failing (the docstring called it optional), the figure is closed after saving, and the default title for time, which was compared with "times", is set.
• The range computation is a function of its own, nprocs_ranges(), tested in the new python/grass/benchmark/tests/grass_benchmark_plots_test.py (9 tests, under 1 s): the ranges for each metric, the serial runs at the smallest nprocs, results without all_times, and the size of the saved image. The existing gunittest suites of the subpackage pass.

Figures

The three figures in the documentation come from a run with main including #7980 and the 48-bit multiplication helper of #8013 (c26f5dd), 26 minutes on an Intel Xeon W-2295 (18 cores, 36 logical CPUs) shared with other work (1-minute load average 4 to 6). An earlier run with #7980 at 7c0d776, before it was merged, gave times within about 2 %.

The figures are 1200 x 900 pixels, twice the 600 pixel width of the documentation, so that they stay sharp on high density screens; the HTML page shows them at 600 x 450 and links to the full image. Quantized and compressed as the style guide asks (pngquant 128 colors instead of pngnq, then optipng -o5), 23 to 35 kB each.

resolution	cells	1 thread	best
4 m	33k	0.96 s	0.17 s (15 threads)
2 m	131k	12.4 s	1.50 s (15 threads)
1 m	525k	113.1 s	12.2 s (16 threads)

More threads than 16 were tried separately (3 repeats of 16, 28 and 32 threads in shuffled order): 28 threads took about as long as 16 (1 m: 13.6 s against 14.8 s; 4 m: 0.28 s against 0.19 s) and 32 threads clearly longer (1 m: 19.6 s; 4 m: 2.4 s). The CPU has 18 physical cores and the machine was shared (load average 8 before the run, 30 during it), so beyond 16 the figures would mostly show the load, not r.sim.water; the script stops at 16.

Before #7980, more threads made r.sim.water slower (4 m: 1.3 s with 1 thread, 2.7 s with 4), because all threads shared one random number generator.

Suggested squash commit message

r.sim.water: Add a benchmark for the number of threads

Measure r.sim.water with nprocs from 1 to 16 on the elevation of the
SECREF North Carolina dataset at 4 m, 2 m and 1 m resolution, using
grass.benchmark as the benchmarks of other tools do. The script plots
time, speedup and efficiency and saves the results as JSON, from which
it can redo the plots.

In grass.benchmark, nprocs_plot() shades the range of the runs in each
line's color for time, speedup and efficiency instead of a gray band for
time only (for speedup over the ratios of every serial run to every
parallel run), takes figsize and dpi, plots results without all_times,
and sets the default title for time. The range is computed by
nprocs_ranges(), which has pytest tests. The documentation of the
experimental subpackage says that it is changed together with the
benchmarks which need more from it.

Add the figures to the documentation in a Performance section, as the
other parallel tools have, at twice the 600 pixel width, shown at 600
pixels in the HTML page. They were made with the per-walker random
number states of OSGeo/grass#7980.

Written with the help of Claude Code.