Struct Generator 

pub struct Generator<B: BitGenerator = Xoshiro256StarStar> { /* private fields */ }

The main random number generator, wrapping a pluggable BitGenerator.

Generator takes &mut self for all sampling methods — it is stateful and NOT Sync. Thread-safety is handled by spawning independent generators via spawn or using the parallel generation API.

Example

use ferray_random::{default_rng_seeded, Generator};

let mut rng = default_rng_seeded(42);
let values = rng.random(10).unwrap();
assert_eq!(values.shape(), &[10]);

Implementations

impl<B: BitGenerator> Generator<B>

pub fn binomial( &mut self, n: u64, p: f64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of binomial-distributed variates.

Each value is the number of successes in n Bernoulli trials with success probability p.

Arguments

• n - Number of trials.
• p - Probability of success per trial, must be in [0, 1].
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue for invalid parameters.

pub fn negative_binomial( &mut self, n: f64, p: f64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of negative binomial distributed variates.

The number of failures before n successes with success probability p. Uses the gamma-Poisson mixture.

Arguments

• n - Number of successes (positive).
• p - Probability of success, must be in (0, 1].
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue for invalid parameters.

pub fn poisson( &mut self, lam: f64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of Poisson-distributed variates.

Arguments

• lam - Expected number of events (lambda), must be non-negative.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if lam < 0 or size is zero.

pub fn geometric( &mut self, p: f64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of geometric-distributed variates.

The number of trials until the first success (1-based).

Arguments

• p - Probability of success, must be in (0, 1].
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if p not in (0, 1] or size is zero.

pub fn hypergeometric( &mut self, ngood: u64, nbad: u64, nsample: u64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of hypergeometric-distributed variates.

Models drawing nsample items without replacement from a population containing ngood success states and nbad failure states.

Arguments

• ngood - Number of success states in the population.
• nbad - Number of failure states in the population.
• nsample - Number of items drawn.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if nsample > ngood + nbad or size is zero.

pub fn logseries( &mut self, p: f64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of logarithmic series distributed variates.

Arguments

• p - Shape parameter, must be in (0, 1).
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if p not in (0, 1) or size is zero.

pub fn zipf( &mut self, a: f64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of Zipf-distributed variates.

Samples from the Zipf (zeta) distribution with shape parameter a > 1, using Devroye’s rejection algorithm (Non-Uniform Random Variate Generation, p. 551). The PMF is P(k) = k^(-a) / zeta(a) for k = 1, 2, ....

Equivalent to numpy.random.Generator.zipf.

Errors

• FerrayError::InvalidValue if a <= 1 or size is invalid.

impl<B: BitGenerator> Generator<B>

pub fn standard_exponential( &mut self, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of standard exponential (rate=1, scale=1) variates.

Uses the inverse CDF method: -ln(U) where U ~ Uniform(0,1).

Errors

Returns FerrayError::InvalidValue if shape is invalid.

pub fn exponential( &mut self, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of exponential variates with the given scale.

The exponential distribution has PDF: f(x) = (1/scale) * exp(-x/scale).

Errors

Returns FerrayError::InvalidValue if scale <= 0 or shape is invalid.

pub fn standard_exponential_f32( &mut self, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of standard exponential f32 variates.

The f32 analogue of standard_exponential.

Errors

Returns FerrayError::InvalidValue if shape is invalid.

pub fn exponential_f32( &mut self, scale: f32, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of f32 exponential variates with the given scale. The f32 analogue of exponential.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or shape is invalid.

impl<B: BitGenerator> Generator<B>

pub fn standard_gamma( &mut self, alpha: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of standard gamma variates with shape parameter alpha.

Errors

Returns FerrayError::InvalidValue if alpha <= 0 or size is invalid.

pub fn gamma( &mut self, alpha: f64, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of gamma-distributed variates.

The gamma distribution with shape alpha and scale scale has PDF: f(x) = x^(alpha-1) * exp(-x/scale) / (scale^alpha * Gamma(alpha)).

Errors

Returns FerrayError::InvalidValue if alpha <= 0, scale <= 0, or size is invalid.

pub fn beta( &mut self, a: f64, b: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of beta-distributed variates in (0, 1).

Uses the relationship: if X ~ Gamma(a), Y ~ Gamma(b), then X/(X+Y) ~ Beta(a,b).

Errors

Returns FerrayError::InvalidValue if a <= 0, b <= 0, or size is invalid.

pub fn chisquare( &mut self, df: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of chi-squared distributed variates.

Chi-squared(df) = Gamma(df/2, 2).

Errors

Returns FerrayError::InvalidValue if df <= 0 or size is invalid.

pub fn f( &mut self, dfnum: f64, dfden: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of F-distributed variates.

F(d1, d2) = (Chi2(d1)/d1) / (Chi2(d2)/d2).

Errors

Returns FerrayError::InvalidValue if either df is non-positive or size is invalid.

pub fn student_t( &mut self, df: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Student’s t-distributed variates.

t(df) = Normal(0,1) / sqrt(Chi2(df)/df).

Errors

Returns FerrayError::InvalidValue if df <= 0 or size is invalid.

pub fn standard_t( &mut self, df: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Alias for student_t using NumPy’s standard_t spelling.

Errors

Returns FerrayError::InvalidValue if df <= 0 or size is invalid.

pub fn noncentral_chisquare( &mut self, df: f64, nonc: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of noncentral chi-squared variates.

noncentral_chisquare(df, nonc) is the distribution of sum((Z_i + mu_i)^2) where Z_i ~ N(0,1) and the sum of the mu_i^2 equals nonc. Implemented via the Poisson-mixed central chi-squared method: N ~ Poisson(nonc/2), X = 2 * Gamma((df + 2N)/2).

Equivalent to numpy.random.Generator.noncentral_chisquare.

Errors

• FerrayError::InvalidValue if df <= 0, nonc < 0, or size is invalid.

pub fn noncentral_f( &mut self, dfnum: f64, dfden: f64, nonc: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of noncentral F-distributed variates.

noncentral_f(dfnum, dfden, nonc) = (Chi2_nc(dfnum, nonc)/dfnum) / (Chi2(dfden)/dfden).

Equivalent to numpy.random.Generator.noncentral_f.

Errors

• FerrayError::InvalidValue if any df is non-positive, nonc < 0, or size is invalid.

impl<B: BitGenerator> Generator<B>

pub fn laplace( &mut self, loc: f64, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Laplace-distributed variates.

PDF: f(x) = (1/(2*scale)) * exp(-|x - loc| / scale).

Arguments

• loc - Location parameter.
• scale - Scale parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or size is zero.

pub fn logistic( &mut self, loc: f64, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of logistic-distributed variates.

Uses inverse CDF: loc + scale * ln(u / (1 - u)).

Arguments

• loc - Location parameter.
• scale - Scale parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or size is zero.

pub fn rayleigh( &mut self, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Rayleigh-distributed variates.

Uses inverse CDF: scale * sqrt(-2 * ln(1-u)).

Arguments

• scale - Scale parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or size is zero.

pub fn weibull( &mut self, a: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Weibull-distributed variates.

Uses inverse CDF: (-ln(1-u))^(1/a).

Arguments

• a - Shape parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if a <= 0 or size is zero.

pub fn pareto( &mut self, a: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Pareto (type II / Lomax) distributed variates.

Uses inverse CDF: (1-u)^(-1/a) - 1 (then shifted by 1 to match NumPy). NumPy’s Pareto: samples from Pareto(a) with x_m=1, so PDF = a / x^(a+1) for x >= 1.

Arguments

• a - Shape parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if a <= 0 or size is zero.

pub fn gumbel( &mut self, loc: f64, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Gumbel-distributed variates.

Uses inverse CDF: loc - scale * ln(-ln(u)).

Arguments

• loc - Location parameter.
• scale - Scale parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or size is zero.

pub fn power( &mut self, a: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of power-distributed variates.

Power distribution with shape a on [0, 1]: PDF: a * x^(a-1), CDF: x^a. Inverse CDF: u^(1/a).

Arguments

• a - Shape parameter, must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if a <= 0 or size is zero.

pub fn triangular( &mut self, left: f64, mode: f64, right: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of triangular-distributed variates.

Arguments

• left - Lower limit.
• mode - Mode (peak), must be in [left, right].
• right - Upper limit, must be > left.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if parameters are invalid or size is zero.

pub fn vonmises( &mut self, mu: f64, kappa: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of von Mises distributed variates.

The von Mises distribution is a continuous distribution on the circle. Uses Best & Fisher’s algorithm.

Arguments

• mu - Mean direction (in radians).
• kappa - Concentration parameter, must be non-negative.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if kappa < 0 or size is zero.

pub fn wald( &mut self, mean: f64, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of Wald (inverse Gaussian) distributed variates.

Arguments

• mean - Mean of the distribution, must be positive.
• scale - Scale parameter (lambda), must be positive.
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if mean <= 0, scale <= 0, or size is zero.

pub fn standard_cauchy( &mut self, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of standard Cauchy distributed variates.

Uses the inverse CDF: tan(pi * (u - 0.5)).

Arguments

• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if size is zero.

impl<B: BitGenerator> Generator<B>

pub fn multinomial( &mut self, n: u64, pvals: &[f64], size: usize, ) -> Result<Array<i64, Ix2>, FerrayError>

Generate multinomial samples.

Each row of the output is one draw of n items distributed across k categories with probabilities pvals.

Arguments

• n - Number of trials per sample.
• pvals - Category probabilities (must sum to ~1.0, length k).
• size - Number of multinomial draws (rows in output).

Returns

An Array<i64, Ix2> with shape [size, k].

Errors

Returns FerrayError::InvalidValue for invalid parameters.

pub fn multivariate_normal( &mut self, mean: &[f64], cov: &[f64], size: usize, ) -> Result<Array<f64, Ix2>, FerrayError>

Generate multivariate normal samples.

Uses the Cholesky decomposition of the covariance matrix.

Arguments

• mean - Mean vector of length d.
• cov - Covariance matrix, flattened in row-major order, shape [d, d].
• size - Number of samples (rows in output).

Returns

An Array<f64, Ix2> with shape [size, d].

Errors

Returns FerrayError::InvalidValue for invalid parameters or if the covariance matrix is not positive semi-definite.

pub fn dirichlet( &mut self, alpha: &[f64], size: usize, ) -> Result<Array<f64, Ix2>, FerrayError>

Generate Dirichlet-distributed samples.

Each row is a sample from the Dirichlet distribution parameterized by alpha, producing vectors that sum to 1.

Arguments

• alpha - Concentration parameters (all must be positive).
• size - Number of samples (rows in output).

Returns

An Array<f64, Ix2> with shape [size, k] where k = alpha.len().

Errors

Returns FerrayError::InvalidValue for invalid parameters.

impl<B: BitGenerator> Generator<B>

pub fn standard_normal( &mut self, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of standard normal (mean=0, std=1) variates.

Uses the Marsaglia–Tsang Ziggurat algorithm (256 layers), which is roughly 3× faster than Box–Muller for large draws. shape accepts usize, [usize; N], &[usize], or Vec<usize> via IntoShape.

Errors

Returns FerrayError::InvalidValue if shape is invalid.

pub fn normal( &mut self, loc: f64, scale: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of normal (Gaussian) variates with given mean and standard deviation. Equivalent to numpy.random.Generator.normal.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or shape is invalid.

pub fn standard_normal_f32( &mut self, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of standard normal (mean=0, std=1) f32 variates.

The f32 analogue of standard_normal. Equivalent to NumPy’s Generator.standard_normal(size, dtype=np.float32). Uses the same Ziggurat f64 tables, then casts to f32 to preserve tail accuracy.

Errors

Returns FerrayError::InvalidValue if shape is invalid.

pub fn normal_f32( &mut self, loc: f32, scale: f32, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of f32 normal (Gaussian) variates with given mean and standard deviation. The f32 analogue of normal.

Errors

Returns FerrayError::InvalidValue if scale <= 0 or shape is invalid.

pub fn lognormal_f32( &mut self, mean: f32, sigma: f32, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of f32 log-normal variates. The f32 analogue of lognormal.

Errors

Returns FerrayError::InvalidValue if sigma <= 0 or shape is invalid.

pub fn lognormal( &mut self, mean: f64, sigma: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of log-normal variates.

If X ~ Normal(mean, sigma), then exp(X) ~ LogNormal(mean, sigma).

Errors

Returns FerrayError::InvalidValue if sigma <= 0 or shape is invalid.

impl<B: BitGenerator> Generator<B>

pub fn random( &mut self, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of uniformly distributed f64 values in [0, 1).

Equivalent to NumPy’s Generator.random(size). shape may be a usize for a 1-D result, or any [usize; N] / &[usize] / Vec<usize> for N-dimensional output (via IntoShape).

Errors

Returns FerrayError::InvalidValue if shape contains a zero-sized axis.

Example

let mut rng = ferray_random::default_rng_seeded(42);
let v = rng.random(10).unwrap();
assert_eq!(v.shape(), &[10]);
let m = rng.random([3, 4]).unwrap();
assert_eq!(m.shape(), &[3, 4]);

pub fn uniform( &mut self, low: f64, high: f64, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of uniformly distributed f64 values in [low, high).

Equivalent to NumPy’s Generator.uniform(low, high, size).

Errors

Returns FerrayError::InvalidValue if low >= high or shape is invalid.

pub fn random_f32( &mut self, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of uniformly distributed f32 values in [0, 1).

The f32 analogue of random. Equivalent to NumPy’s Generator.random(size, dtype=np.float32).

Errors

Returns FerrayError::InvalidValue if shape contains a zero-sized axis.

Example

let mut rng = ferray_random::default_rng_seeded(42);
let v = rng.random_f32(10).unwrap();
assert_eq!(v.shape(), &[10]);
for &x in v.iter() {
    assert!((0.0..1.0).contains(&x));
}

pub fn uniform_f32( &mut self, low: f32, high: f32, size: impl IntoShape, ) -> Result<Array<f32, IxDyn>, FerrayError>

Generate an array of uniformly distributed f32 values in [low, high).

The f32 analogue of uniform.

Errors

Returns FerrayError::InvalidValue if low >= high or shape is invalid.

pub fn integers( &mut self, low: i64, high: i64, size: impl IntoShape, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of uniformly distributed random integers in [low, high).

Equivalent to NumPy’s Generator.integers(low, high, size).

Errors

Returns FerrayError::InvalidValue if low >= high or shape is invalid.

impl<B: BitGenerator> Generator<B>

pub const fn new(bg: B) -> Self

Create a new Generator wrapping the given BitGenerator.

pub const fn bit_generator(&mut self) -> &mut B

Access the underlying BitGenerator mutably.

pub fn next_u64(&mut self) -> u64

Generate the next random u64.

pub fn next_f64(&mut self) -> f64

Generate the next random f64 in [0, 1).

pub fn next_f32(&mut self) -> f32

Generate the next random f32 in [0, 1).

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

Generate a u64 in [0, bound).

pub fn bytes(&mut self, n: usize) -> Vec<u8>

Generate n random bytes as a Vec<u8>.

Equivalent to numpy.random.Generator.bytes(n). Each byte is drawn from the underlying bit generator’s u64 stream and little-endian-decomposed; calling bytes(n) advances the bit generator by ceil(n / 8) u64 draws (#446).

impl<B: BitGenerator + Clone> Generator<B>

pub fn standard_normal_parallel( &mut self, size: impl IntoShape, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate standard normal variates in parallel, deterministically.

Uses spawn() to create independent child generators (via jump-ahead for Xoshiro256**, stream IDs for Philox, or seed-from-parent for PCG64), then generates chunks in parallel using Rayon.

The output is deterministic for a given seed and thread count, but does not match standard_normal(size) (which is sequential). The parallel version produces different values because the child generators have different internal states.

Errors

Returns FerrayError::InvalidValue if shape is invalid.

pub fn spawn(&mut self, n: usize) -> Result<Vec<Self>, FerrayError>

Spawn n independent child generators for manual parallel use.

Uses jump() if available, otherwise seeds children from parent output.

Arguments

• n - Number of child generators to create.

Errors

Returns FerrayError::InvalidValue if n is zero.

impl<B: BitGenerator> Generator<B>

pub fn shuffle<T>(&mut self, arr: &mut Array<T, Ix1>) -> Result<(), FerrayError>

where T: Element,

Shuffle a 1-D array in-place using Fisher-Yates.

Errors

Returns FerrayError::InvalidValue if the array is not contiguous.

pub fn permutation<T>( &mut self, arr: &Array<T, Ix1>, ) -> Result<Array<T, Ix1>, FerrayError>

where T: Element,

Return a new array with elements randomly permuted.

If the input is 1-D, returns a shuffled copy. If an integer n is given (via permutation_range), returns a permutation of 0..n.

Errors

Returns FerrayError::InvalidValue if the array is empty.

pub fn permutation_range( &mut self, n: usize, ) -> Result<Array<i64, Ix1>, FerrayError>

Return a permutation of 0..n as an Array1<i64>.

Errors

Returns FerrayError::InvalidValue if n is zero.

pub fn permuted<T>( &mut self, arr: &Array<T, Ix1>, _axis: usize, ) -> Result<Array<T, Ix1>, FerrayError>

where T: Element,

Return an array with elements independently permuted along the given axis.

For 1-D arrays, this is the same as permutation. This simplified implementation operates on 1-D arrays along axis 0.

Errors

Returns FerrayError::InvalidValue if the array is empty.

pub fn choice<T>( &mut self, arr: &Array<T, Ix1>, size: usize, replace: bool, p: Option<&[f64]>, ) -> Result<Array<T, Ix1>, FerrayError>

where T: Element,

Randomly select elements from an array, with or without replacement.

Arguments

• arr - Source array to sample from.
• size - Number of elements to select.
• replace - If true, sample with replacement; if false, without.
• p - Optional probability weights (must sum to 1.0 and have same length as arr).

Errors

Returns FerrayError::InvalidValue if parameters are invalid (e.g., size > arr.len() when replace=false, or invalid probability weights).