Skip to main content

BitGenerator

ferray_random::bitgen

Trait BitGenerator 

Source 
pub trait BitGenerator: Send {
    // Required methods
    fn next_u64(&mut self) -> u64;
    fn seed_from_u64(seed: u64) -> Self
       where Self: Sized;
    fn jump(&mut self) -> Option<()>;
    fn stream(seed: u64, stream_id: u64) -> Option<Self>
       where Self: Sized;

    // Provided methods
    fn next_f64(&mut self) -> f64 { ... }
    fn next_f32(&mut self) -> f32 { ... }
    fn fill_bytes(&mut self, dest: &mut [u8]) { ... }
    fn state_bytes(&self) -> Result<Vec<u8>, FerrayError> { ... }
    fn set_state_bytes(&mut self, bytes: &[u8]) -> Result<(), FerrayError> { ... }
    fn next_u64_bounded(&mut self, bound: u64) -> u64 { ... }
}
Expand description

Trait for pluggable pseudo-random number generators.

All BitGenerators are Send (can be transferred between threads) but NOT Sync (they are stateful and require &mut self).

Concrete implementations: Pcg64, Pcg64Dxsm, Philox, Xoshiro256StarStar, MT19937, Sfc64.

Required Methods§

Source

fn next_u64(&mut self) -> u64

Generate the next 64-bit unsigned integer.

Source

fn seed_from_u64(seed: u64) -> Self
where Self: Sized,

Create a new generator seeded from a single u64.

Source

fn jump(&mut self) -> Option<()>

Advance the generator state by a large step (2^128 for Xoshiro256**).

Returns Some(()) if jump is supported, None otherwise. After calling jump, the generator’s state has advanced as if 2^128 calls to next_u64 had been made.

Source

fn stream(seed: u64, stream_id: u64) -> Option<Self>
where Self: Sized,

Create a new generator from a seed and a stream ID.

Returns Some(Self) if the generator supports stream-based parallelism (e.g., Philox), None otherwise.

Provided Methods§

Source

fn next_f64(&mut self) -> f64

Generate a uniformly distributed f64 in [0, 1).

Uses the upper 53 bits of next_u64() for full double precision.

Source

fn next_f32(&mut self) -> f32

Generate a uniformly distributed f32 in [0, 1).

Source

fn fill_bytes(&mut self, dest: &mut [u8])

Fill a byte slice with random bytes.

Source

fn state_bytes(&self) -> Result<Vec<u8>, FerrayError>

Serialize the full internal state of this generator to a little-endian byte vector. Pair with [set_state_bytes] to restore.

Default impl returns an error — concrete generators that support serialization override both methods. Used to checkpoint reproducible experiments (#453), the rough Rust equivalent of numpy’s Generator.bit_generator.state / __getstate__ / __setstate__.

§Errors

FerrayError::InvalidValue if the generator does not implement state serialization.

Source

fn set_state_bytes(&mut self, bytes: &[u8]) -> Result<(), FerrayError>

Restore the generator’s state from previously-serialized bytes produced by [state_bytes].

§Errors

FerrayError::InvalidValue if the byte length doesn’t match the expected state size, or if the embedded state is invalid (e.g. all-zero state for Xoshiro256**).

Source

fn next_u64_bounded(&mut self, bound: u64) -> u64

Generate a u64 in the range [0, bound) using rejection sampling.

Implementors§