Struct RngEngine 

pub struct RngEngine { /* private fields */ }

A seeded, dual-path random number generator.

Constructed via RngEngine::new. The gpu Cargo feature enables the GPU path; if CUDA is not available at runtime the constructor transparently falls back to the CPU path.

Thread safety

On the CPU path (default), RngEngine is both Send and Sync — the state is a pair of u64 integers and carries no shared references.

On the GPU path (feature = "gpu"), RngEngine is Send but NOT Sync. A CUDA stream cannot be shared across threads; the PhantomData<*const ()> field enforces that statically.

Implementations

impl RngEngine

pub fn new(kind: RngEngineKind, seed: u64) -> Result<Self, RngError>

Constructs a new RNG engine of the requested kind and seed.

When the gpu feature is enabled and a CUDA device is reachable at runtime, the GPU path is chosen; otherwise the CPU path is used.

Errors

Currently infallible on the CPU path. Returns RngError::GpuError if CUDA initialisation fails and there is no CPU fallback compiled in.

pub fn kind(&self) -> RngEngineKind

Returns the engine kind that was requested at construction.

pub fn is_gpu(&self) -> bool

Returns true when the active path is the GPU.

pub fn uniform_f32(&mut self, out: &mut [f32]) -> Result<(), RngError>

Fills out with independent uniform samples drawn from [0.0, 1.0).

Errors

• RngError::EmptyBuffer — out is empty.
• RngError::GpuError — CUDA operation failed (GPU path only).

pub fn normal_f32( &mut self, out: &mut [f32], mean: f32, std_dev: f32, ) -> Result<(), RngError>

Fills out with independent normal samples from N(mean, std_dev²).

Uses Box-Muller on the CPU path and the engine’s native Gaussian kernel on the GPU path.

Errors

• RngError::EmptyBuffer — out is empty.
• RngError::InvalidParam — std_dev < 0 or not finite.
• RngError::GpuError — CUDA failure (GPU path).

pub fn bernoulli(&mut self, out: &mut [u8], p: f32) -> Result<(), RngError>

Fills out with Bernoulli(p) samples: each element is 1u8 with probability p and 0u8 otherwise.

Errors

• RngError::EmptyBuffer — out is empty.
• RngError::InvalidParam — p is not in [0.0, 1.0].
• RngError::GpuError — CUDA failure (GPU path).

pub fn uniform_f64(&mut self, out: &mut [f64]) -> Result<(), RngError>

Fills out with independent uniform samples drawn from [0.0, 1.0) with 52-bit mantissa precision.

Each value is constructed from a 64-bit PCG output using the IEEE 754 exponent-field trick: the top 52 bits are inserted into the mantissa of a double with exponent bias 1023 (∈ [1.0, 2.0)), then 1.0 is subtracted to shift to [0.0, 1.0).

Errors

• RngError::EmptyBuffer — out is empty.

pub fn normal_f64( &mut self, out: &mut [f64], mean: f64, std_dev: f64, ) -> Result<(), RngError>

Fills out with independent normal samples from N(mean, std_dev²) with double precision.

Uses Box-Muller on the CPU path. Each pair of output values consumes two uniform_f64 draws; an odd-length buffer consumes one additional pair (discarding the second normal from the last Box-Muller step).

Errors

• RngError::EmptyBuffer — out is empty.
• RngError::InvalidParam — std_dev < 0 or not finite, or mean is not finite.

pub fn fill_uniform_chunked<F: FnMut(&[f32])>( &mut self, total: usize, chunk_size: usize, consumer: &mut F, ) -> Result<(), RngError>

Generates total f32 uniform samples and delivers them in chunks of at most chunk_size elements, calling consumer once per chunk.

The final chunk may be smaller than chunk_size when total is not a multiple of chunk_size.

Determinism

Given the same seed and the same total, the complete sequence of generated values is identical regardless of chunk_size. The chunk size only affects how many values are presented per callback.

Errors

• RngError::EmptyBuffer — total == 0 or chunk_size == 0.

pub fn fill_uniform_chunked_f64<F: FnMut(&[f64])>( &mut self, total: usize, chunk_size: usize, consumer: &mut F, ) -> Result<(), RngError>

Generates total f64 uniform samples and delivers them in chunks of at most chunk_size elements, calling consumer once per chunk.

The final chunk may be smaller than chunk_size when total is not a multiple of chunk_size.

Determinism

Given the same seed and the same total, the complete sequence of generated values is identical regardless of chunk_size.

Errors

• RngError::EmptyBuffer — total == 0 or chunk_size == 0.

pub fn fill_normal_chunked<F: FnMut(&[f32])>( &mut self, total: usize, chunk_size: usize, mean: f32, std_dev: f32, consumer: &mut F, ) -> Result<(), RngError>

Generates total f32 normal samples from N(mean, std_dev²) and delivers them in chunks of at most chunk_size elements, calling consumer once per chunk.

The final chunk may be smaller than chunk_size.

Determinism

Given the same seed and the same total, the full sequence is identical regardless of chunk_size. Note: because Box-Muller consumes values in pairs, chunk boundaries that split a pair internally will advance the stream by a full pair — the global sequence is determined by total, not chunk boundaries.

Errors

• RngError::EmptyBuffer — total == 0 or chunk_size == 0.
• RngError::InvalidParam — std_dev < 0 or not finite, or mean is not finite.

Trait Implementations

impl Send for RngEngine