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 poisson_array( &mut self, lam: &Array<f64, IxDyn>, ) -> Result<Array<i64, IxDyn>, FerrayError>

Generate an array of Poisson variates with a broadcast lam parameter (#449).

lam is an array of expected counts; each output element is sampled from Poisson(lam[i]). Output shape equals lam.shape().

Errors

• FerrayError::InvalidValue if any lam element is negative.

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_into( &mut self, out: &mut Array<f64, IxDyn>, ) -> Result<(), FerrayError>

Fill a pre-allocated out buffer with standard exponential (rate=1) variates (#454).

Equivalent to numpy.random.Generator.standard_exponential(out=buffer).

Errors

FerrayError::InvalidValue if out is non-contiguous.

pub fn exponential_array( &mut self, scale: &Array<f64, IxDyn>, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of exponential variates with a broadcast scale parameter (#449).

scale is an array; each output element is sampled from Exp(rate = 1/scale[i]). The output shape equals scale.shape().

Errors

• FerrayError::InvalidValue if any scale element is <= 0.

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 multivariate_hypergeometric( &mut self, colors: &[u64], nsample: u64, size: usize, ) -> Result<Array<i64, Ix2>, FerrayError>

Generate samples from the multivariate hypergeometric distribution.

Models drawing nsample items without replacement from a population partitioned into K colors with colors[k] items of color k. Each row of the output is one such draw — a vector of K non-negative counts summing to nsample.

Uses the marginals algorithm: a sequence of K-1 univariate hypergeometric draws, each picking the count of one color from the remainder of the population. The final color is what’s left. This matches numpy.random.Generator.multivariate_hypergeometric (#445).

Arguments

• colors - Number of items of each color (length K, all non-negative).
• nsample - Number of items drawn per sample (must be ≤ sum of colors).
• size - Number of multivariate draws (rows in output).

Returns

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

Errors

Returns FerrayError::InvalidValue if colors is empty, size is 0, or nsample exceeds the population total.

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

Generate multivariate normal samples taking Array parameters.

Ergonomic counterpart to [multivariate_normal] (#451): accepts the mean as Array<f64, Ix1> and the covariance as Array<f64, Ix2> directly, no manual flattening required.

Cholesky decomposition is delegated to ferray_linalg::cholesky (#452) which is faer-backed and surfaces non-positive-definite inputs as FerrayError::SingularMatrix instead of the home-grown cholesky_decompose helper.

Errors

• FerrayError::ShapeMismatch if cov is not square or its side does not match mean.len().
• FerrayError::SingularMatrix if cov is not positive definite (propagated from ferray-linalg).
• FerrayError::InvalidValue for size = 0 or empty mean.

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_into( &mut self, out: &mut Array<f64, IxDyn>, ) -> Result<(), FerrayError>

Fill a pre-allocated out buffer with standard normal (mean=0, std=1) variates (#454).

Equivalent to numpy.random.Generator.standard_normal(out=buffer). Each slot is overwritten with a fresh Ziggurat draw — no heap allocation.

Errors

FerrayError::InvalidValue if out is non-contiguous.

pub fn normal_array( &mut self, loc: &Array<f64, IxDyn>, scale: &Array<f64, IxDyn>, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of normal variates with broadcast array parameters (#449).

loc and scale are arrays that NumPy-broadcast against each other to produce the output shape. Each output element is loc[i] + scale[i] * Z where Z is a fresh standard-normal draw. Equivalent to numpy.random.Generator.normal(loc, scale) when both are arrays.

For scalar parameters, prefer normal — it avoids the broadcast view and is faster.

Errors

• FerrayError::ShapeMismatch if the two shapes are not broadcast-compatible.
• FerrayError::InvalidValue if any scale element is <= 0.

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 random_into( &mut self, out: &mut Array<f64, IxDyn>, ) -> Result<(), FerrayError>

Fill a pre-allocated out buffer with uniform [0, 1) variates (#454).

Equivalent to numpy.random.Generator.random(out=buffer) — the allocation is the caller’s, so hot loops that produce many equal-shaped batches reuse a single buffer instead of churning the heap.

Errors

FerrayError::InvalidValue if out is non-contiguous.

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 uniform_array( &mut self, low: &Array<f64, IxDyn>, high: &Array<f64, IxDyn>, ) -> Result<Array<f64, IxDyn>, FerrayError>

Generate an array of uniform variates with broadcast array parameters (#449).

low and high are arrays that NumPy-broadcast to determine the output shape. Each element is drawn from Uniform([low[i], high[i])). Equivalent to numpy.random.Generator.uniform(low, high) when both are arrays.

Errors

• FerrayError::ShapeMismatch if shapes don’t broadcast.
• FerrayError::InvalidValue if any element has low >= high.

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 fn integers_u8( &mut self, low: u8, high: u8, size: impl IntoShape, ) -> Result<Array<u8, IxDyn>, FerrayError>

Generate u8 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.uint8).

Errors

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

impl<B: BitGenerator> Generator<B>

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

Generate i8 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.int8).

Errors

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

impl<B: BitGenerator> Generator<B>

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

Generate u16 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.uint16).

Errors

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

impl<B: BitGenerator> Generator<B>

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

Generate i16 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.int16).

Errors

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

impl<B: BitGenerator> Generator<B>

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

Generate u32 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.uint32).

Errors

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

impl<B: BitGenerator> Generator<B>

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

Generate i32 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.int32).

Errors

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

impl<B: BitGenerator> Generator<B>

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

Generate u64 integers in [low, high), matching numpy.random.Generator.integers(..., dtype=np.uint64).

Errors

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 state_bytes(&self) -> Result<Vec<u8>, FerrayError>

Serialize the underlying BitGenerator’s full internal state to a byte vector — pair with set_state_bytes to restore. Used to checkpoint reproducible experiments (#453).

The format is the LE-byte serialization of the bit generator’s state words; it is stable per-generator-type but not portable across different BitGenerator implementations (Pcg64 state cannot be loaded into Xoshiro256**).

Errors

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

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

Restore the underlying BitGenerator’s state from previously captured bytes.

Errors

FerrayError::InvalidValue if the byte length is wrong for this generator type or the embedded state is invalid (e.g. all-zero state for Xoshiro256**, even inc for Pcg64).

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 shuffle_dyn<T>( &mut self, arr: &mut Array<T, IxDyn>, axis: usize, ) -> Result<(), FerrayError>

where T: Element,

Shuffle an N-D array in place along axis, swapping whole hyperslices (rows when axis == 0 for a 2-D array).

Equivalent to numpy.random.Generator.shuffle(x, axis=axis). Each pair (i, j) selected by Fisher-Yates exchanges all elements with axis-coordinate i and j simultaneously, so rows / columns / N-D slices keep their internal structure (#447).

Errors

• FerrayError::AxisOutOfBounds if axis >= arr.ndim().
• FerrayError::InvalidValue if arr is non-contiguous.

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

where T: Element,

Sample N-D hyperslices from arr along axis (#448).

For each of size draws, picks an index along axis (uniformly or weighted by p, with or without replacement) and copies the corresponding (N-1)-D slice into the output. The output has the same shape as arr with the axis-th dimension replaced by size.

Equivalent to numpy.random.Generator.choice(arr, size, replace, p, axis) for N-D arr. The shuffle parameter (numpy 1.24+) controls whether the indices are returned in selection order (shuffle = true, default) or sorted (shuffle = false, only meaningful when replace = false).

Errors

• FerrayError::AxisOutOfBounds if axis >= arr.ndim().
• FerrayError::InvalidValue if the axis dimension is empty, size > axis_len with replace = false, arr is non-contiguous, or p is malformed.

pub fn permuted_dyn<T>( &mut self, arr: &Array<T, IxDyn>, axis: usize, ) -> Result<Array<T, IxDyn>, FerrayError>

where T: Element,

Independently permute the entries along axis of arr.

Returns a new array. For each combination of “other” indices (everything except axis) the values along axis are shuffled with their own Fisher-Yates pass — so columns of a 2-D array get independent permutations when axis = 0. Equivalent to numpy.random.Generator.permuted(x, axis=axis).

Errors

• FerrayError::AxisOutOfBounds if axis >= arr.ndim().
• FerrayError::InvalidValue if arr is non-contiguous.

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).