osmose.engine.rng

Per-species deterministic RNG factory.

Reproducibility scope (Phase 3 — RNG documentation):

fixed=True gives Python-side reproducible outputs only. Running the same config twice with the same seed under the Python engine produces bit-equal results. It does NOT produce results bit-equal to the Java engine. NumPy’s default_rng uses PCG64; the Java engine uses MT19937 (legacy java.util.Random). The streams diverge at the first draw.

Cross-engine agreement is documented as “within 1 OoM” per species: 14/14 EEC, but only 7/8 Bay of Biscay (Hake is a pre-existing exception; see docs/parity-roadmap.md). Byte-equivalent outputs across engines are impossible without reimplementing the MT19937 stream in NumPy — out of scope for this port. If bit-exact reproducibility against Java is required, set OsmoseCalibrationProblem(use_java_engine=True) and run the Java subprocess path.

Even within the Python engine, a given RNG stream is not guaranteed stable across commits: the bioenergetics reproduction path’s draw sequence changed at 77c9c94 (C3 Stage-1 Task 5) when the rng.integers parent-cell draw was removed because eggs became unlocated. No bioen-enabled output is bit-comparable across 39c43a2..77c9c94 — a fixed seed reproduces a given commit, not a given config across commits. Don’t diff a Stage-2 bioen run against a pre-77c9c94 baseline and read the mismatch as a regression.

Functions

build_rng(seed, n_species, fixed)

Build per-species RNG generators.