[GRASS-git] [OSGeo/grass] ff0865: libgis: Document reproducible random numbers for p...

[Vaclav Petras]

  Branch: refs/heads/main
  Home:   https://github.com/OSGeo/grass
  Commit: ff08652a0d0df0f24c24fa881d74775ec7beb4f8
      https://github.com/OSGeo/grass/commit/ff08652a0d0df0f24c24fa881d74775ec7beb4f8
  Author: Vaclav Petras <wenzeslaus at gmail.com>
  Date:   2026-10-07 (Wed, 07 Oct 2026)

  Changed paths:
    M doc/development/style_guide.md
    M include/Make/Doxyfile_arch_html.in
    M include/Make/Doxyfile_arch_latex.in
    A lib/gis/README.md
    M lib/gis/gislib.dox
    A lib/gis/random_streams.dox.md
    A lib/gis/random_streams.svg
    A lib/gis/random_streams_figures.py
    A lib/gis/random_streams_layouts.svg
    A lib/gis/random_streams_parts.svg
    A lib/gis/random_streams_seeds.svg
    A lib/gis/random_streams_strides.svg
    A lib/gis/random_streams_twins.svg

  Log Message:
  -----------
  libgis: Document reproducible random numbers for parallel tools (#8004)

Add the page gislib_random_streams, written in Markdown as
lib/gis/random_streams.dox.md and rendered by Doxygen as a subpage of
the library page. It defines eight terms once (generator, seed, state,
span, layout, unit, stride, batch), describes a single sequence, the
three layouts and batches, shows how a tool gets its seed and the usage
patterns with code (a single sequence, rows of a raster, items drawn
over time, ensembles), gives the capacity, explains the quality of the
values (a table of the issues, how the library avoids each and what
remains, the generator and the span, the relations by distance with
their expected occurrence for a round total of draws, what odd strides
and odd distances between batches fix and where the relation remains,
relations between seeds), and shows how to migrate from the shared
generator in a table of the calls before and after. Six figures draw the
ring with the span as the quarter after wherever the seed falls, the
constant-shift twins, the layouts, what an even number of parts would
give, the values of units at an even and an odd stride, and the values
of consecutive seeds next to those of batches. The page speaks of rows
of a raster and of items drawn over time rather than of particular
tools, so that it does not drift when tools change. The examples use
single-line comments and the formulas the multiplication sign, so that
the page renders as written and lints as Markdown. The figures are
written by lib/gis/random_streams_figures.py, which also prints the
numbers quoted on the page; a README in the directory points to it.

Add *.dox.md to the file patterns of both Doxygen configuration
templates and say in the style guide that library pages
may be Markdown.

Written with the help of Claude Code.



To unsubscribe from these emails, change your notification settings at https://github.com/OSGeo/grass/settings/notifications