[wenzeslaus]

r.surf.random draws its values from a caller-owned random number state instead of the shared generator, with each row as one unit of an exact random number layout. The maps for a given seed are identical to earlier versions, and the seed is read with the standard function for the seed option.

This brings little new besides the unified seed handling, a warning for regions with more cells than one seed holds, and the use of the new API as an example. However, the cost is small, a few lines to manage the state. It is a first step towards making r.surf.random parallel.

Details (AI generated)

The change

• Each row is a unit of an exact layout of one value per cell, placed with G_random_state_for_unit() before the row is filled. The float map draws with G_random_double(). The integer map draws with G_random_uint32(), which returns what (unsigned int)G_mrand48() gave. Both maps are therefore byte-identical to earlier versions for a given seed.
• A region with more cells than one seed holds gets a warning, as the rows then repeat earlier rows plus a constant.
• The seed is read with G_random_seed_from_option(), so a seed which is not wholly an integer or is outside -2147483648 to 4294967295 is an error naming the option, before the output exists. It was truncated with strtol() before. Without the option a seed is generated with G_random_generate_seed(), as before.

Tests

A test checks that a seed beyond each end of the range and a seed with trailing text are refused and that no map is created. The pinned-value tests of the tool already on main pass with the change.

Verification

Float and integer maps for 8 seeds across the whole range were identical to those of the binary before this change.

Suggested squash commit message

r.surf.random: Draw from an exact random number layout

r.surf.random now draws from a random number state of its own instead
of the generator shared by the whole program. Each row is a unit of an
exact random number layout with one value per cell, so the maps for a
given seed stay the same as in earlier versions. The integer map uses
G_random_uint32(), which returns what (unsigned int)G_mrand48() gave.
This is a first step towards filling the rows in parallel.

A warning is given when the region has more cells than one seed holds.
The seed is read with G_random_seed_from_option(), so a seed out of
range or with trailing text is an error instead of being truncated.

Written with the help of Claude Code.

The code and this description were written with Claude Code (Claude Fable 5.1 and Claude Opus 5.5) and reviewed by the author of the PR.