Module rng 

Reproducible random numbers.

The generator is xoshiro256** (Blackman & Vigna, 2018) seeded through SplitMix64: fast, statistically excellent for simulation, and identical across platforms, so that a stream drawn here is the same as one drawn from the same seed by another implementation of the generator (a learned receiver trained in Python, say).

Monte Carlo campaigns never share a generator between trials: stream derives an independent generator from (base_seed, experiment, condition, trial), so a trial is reproducible on its own, whatever the number of threads and the order in which the trials run (see the crate comnum-sim).

Mathematics

• Rng::uniform returns (next_u64() >> 11) · 2⁻⁵³ ∈ [0, 1);
• Rng::gaussian is the Box–Muller transform √(-2 ln(1-u₁)) cos(2π u₂) (the sine branch is dropped, so that one call consumes exactly two uniforms);
• Rng::complex_gaussian is circular with E|z|² = 1;
• Rng::gamma is the method of Marsaglia & Tsang (2000), a rejection from a transformed Gaussian;
• stream: seed = sm(sm(sm(base ⊕ fnv1a(experiment)) ⊕ condition) ⊕ trial) with sm one SplitMix64 step; member: seed ⊕ index · φ, the members of a family of deterministic sequences shared by a transmitter and its receiver.

Examples

use comnum_core::rng::{stream, Rng};
let mut a = Rng::new(42);
let mut b = Rng::new(42);
assert_eq!(a.next_u64(), b.next_u64());
// two trials of the same condition get independent streams
let x = stream(1, "ber", 3, 0).uniform();
let y = stream(1, "ber", 3, 1).uniform();
assert_ne!(x, y);
assert_eq!(x, stream(1, "ber", 3, 0).uniform());

References

1. D. Blackman and S. Vigna, “Scrambled linear pseudorandom number generators,” ACM Trans. Math. Softw., 47(4), 2021 (arXiv:1805.01407, 2018).
2. G. Marsaglia and W. W. Tsang, “A simple method for generating gamma variables,” ACM Trans. Math. Softw., 26(3), 363–372, 2000.

Structs

Rng

The xoshiro256** generator (256 bits of state).

Functions

batch_rng

An independent, reproducible generator for one batch of frames.

fnv1a64

FNV-1a 64-bit hash of a byte string (hashes the experiment names of stream).

member

The generator of the member index of a family of deterministic sequences drawn from seed (the pilots of the REs of a grid, the phase sequences of SLM): Rng::new(seed ⊕ index · φ), $\varphi$ the 64-bit golden ratio of SplitMix64. Unlike stream it is a plain function of the two numbers, which the transmitter and the receiver share.

stream

An independent generator for (base_seed, experiment, condition, trial).

Type Aliases

SimRng

The generator every random block receives (&mut SimRng).