Philox-4x32-10 counter-based pseudo-random number generator.
Owns a (seed, counter) pair plus a mutex guarding both fields.
Each call to next_uint32x4 produces four independent 32-bit
uniforms and increments the counter by one; the (seed, counter) tuple
uniquely identifies every emitted block, which is what makes the
stream reproducible across process invocations.
See Also
default_generator — global Generator used when ops are
called without an explicit generator= kwarg.
Attributes
seed_uint64_tset_seed (or the constructor). Read-only after construction except through set_seed.counter_uint64_t0 by set_seed. May be overridden directly via set_counter for checkpoint restore.mu_std::mutexseed_ and counter_ so concurrent samplers observe a consistent state.Notes
Invariants enforced by the implementation:
counter_is monotonically increasing within a seed epoch.(seed_, counter_)uniquely identifies each produced block, making the sequence fully reproducible.mu_must be held by all mutating accessors when the generator is shared across threads.
Sampling calls are not thread-safe on their own — wrap them in a
std::lock_guard<std::mutex> over mutex when sharing.
Examples
Reproducible draws across two runs: Generator g(42);
uint32_t out[4];
g.next_uint32x4(out);
// second run, same seed → identical out[0..3]Constructors
1Methods
7Returns the current counter value.
Returns
uint64_tThe number of Philox blocks consumed since the last set_seed (modulo any direct set_counter override).
Notes
Useful when serialising RNG state for a checkpoint: capture
(seed(), counter()) and restore via set_seed +
set_counter on reload.
Returns the internal mutex so callers can hold it across batched sampling calls.
Returns
std::mutex&Reference to the mutex guarding seed_ and counter_.
Notes
Exposed so the Python binding can wrap a whole vector draw under one lock acquisition rather than re-locking on every uniform.
Generates four independent 32-bit uniforms using Philox-4x32-10 on the current (counter_, seed_) state, then increments counter_ by one.
See Also
next_uniform_float — single-float variant.
Parameters
outuint32_t[4]uint32_t values. The caller owns the memory.Notes
Not thread-safe on its own. When shared across threads, acquire
mutex (or use a std::lock_guard) before calling.
Generates a single uniform float in [0, 1) from the upper 24 bits of one Philox output word.
Returns
floatUniformly distributed value in [0, 1).
Notes
Internally derives one uint32_t from
next_uint32x4, drops the lower 8 bits for uniformity in
the IEEE-754 float mantissa, and divides by 2^{24}.
The three unused 32-bit words from the Philox block are
discarded; callers that need higher throughput should batch
through next_uint32x4.
Not thread-safe — see next_uint32x4.
Returns the seed value last set via the constructor or set_seed.
Returns
uint64_tCurrent seed. Not synchronised with concurrent set_seed calls — wrap in a lock if a consistent snapshot is required.
Directly overrides the counter — used to restore a saved RNG state from a checkpoint.
Parameters
cuint64_tcounter_ atomically with respect to other field accesses guarded by mu_.Notes
Normal use should call set_seed first to fix the seed,
then set_counter to restore the position within that
seed epoch. This pair reproduces any previously observed state
exactly.
Sets the seed and resets the counter to zero, restarting the sequence from a fresh deterministic origin.
Parameters
seeduint64_tmu_).Notes
The standard re-seed-then-resample idiom for checkpointing.
After this call the next four uniforms depend only on seed,
independent of any previous use of the generator.