Principle:Farama Foundation Gymnasium Reproducible Seeding
| Knowledge Sources | |
|---|---|
| Domains | Reinforcement_Learning, Reproducibility |
| Last Updated | 2026-02-15 03:00 GMT |
Overview
Seeded random number generator creation provides deterministic and reproducible environment behavior for reliable experimental evaluation.
Description
Reproducible seeding provides a standardized mechanism for creating seeded random number generators (RNGs) that ensure deterministic environment behavior across runs. Reproducibility is a cornerstone of scientific experimentation in reinforcement learning: without it, results cannot be verified, ablation studies lack meaning, and debugging becomes intractable. The seeding utility creates NumPy random number generators backed by the PCG64 bit generator, which provides excellent statistical properties and reproducibility guarantees.
The seeding function accepts an optional integer seed and returns both a NumPy Generator object and the actual seed value used (which is useful when no seed is provided and a random one is generated). The function validates that the seed is a non-negative integer, uses NumPy's SeedSequence for proper seed expansion, and instantiates the PCG64 bit generator for high-quality pseudo-random number generation. The returned generator is then stored as the environment's np_random attribute and used for all stochastic operations within the environment.
Reproducible seeding is integrated into the environment lifecycle through the reset method. When reset is called with a seed parameter, a new RNG is created from that seed, ensuring that the subsequent episode follows a deterministic trajectory (given the same sequence of actions). This design allows researchers to run identical experiments by specifying the same seed, compare algorithm performance under controlled conditions, and reproduce specific failure cases for debugging.
Usage
Use the seeding utility when implementing custom environments to create the random number generator. Always pass the seed through the reset method rather than creating RNGs directly. Use fixed seeds for reproducible experiments and benchmarking. Omit the seed (or pass None) when random initialization is desired (for example, during deployment or diverse data collection). Always report the seeds used in experimental results to enable reproduction.
Theoretical Basis
The seeding mechanism is built on NumPy's modern random number generation infrastructure:
def np_random(seed=None):
"""Create a seeded NumPy RNG using PCG64."""
if seed is not None:
assert isinstance(seed, int) and seed >= 0
seed_seq = np.random.SeedSequence(seed)
np_seed = seed_seq.entropy
rng = np.random.Generator(np.random.PCG64(seed_seq))
return rng, np_seed
The PCG64 (Permuted Congruential Generator) produces 64-bit pseudo-random numbers with a period of and excellent statistical properties. The state transition is:
where is a fixed multiplier and is the increment (derived from the stream/sequence).
The output function applies a permutation to prevent linear artifacts:
The SeedSequence object provides proper seed expansion, converting a single integer seed into the multiple values needed to initialize the bit generator. This avoids the common pitfall of using seeds that map to correlated RNG states.
The reproducibility guarantee is:
Failed to parse (syntax error): {\displaystyle \forall s \in \mathbb{Z}_{\geq 0}: \text{np\_random}(s) = \text{np\_random}(s)}
That is, the same seed always produces the same generator state, and therefore the same sequence of random numbers, regardless of when or where the function is called.