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: usize, ) -> Result<Array<i64, Ix1>, 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: usize, ) -> Result<Array<i64, Ix1>, 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: usize, ) -> Result<Array<i64, Ix1>, 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: usize, ) -> Result<Array<i64, Ix1>, 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: usize, ) -> Result<Array<i64, Ix1>, 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: usize, ) -> Result<Array<i64, Ix1>, 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.

impl<B: BitGenerator> Generator<B>

pub fn standard_exponential( &mut self, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

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

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

Arguments

• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if size is zero.

pub fn exponential( &mut self, scale: f64, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

Generate an array of exponential variates with the given scale.

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

Arguments

• scale - Scale parameter (1/rate), must be positive.
• size - Number of values to generate.

Errors

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

impl<B: BitGenerator> Generator<B>

pub fn standard_gamma( &mut self, shape: f64, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

Generate an array of standard gamma variates with shape shape.

Arguments

• shape - Shape parameter (alpha), must be positive.
• size - Number of values to generate.

Errors

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

pub fn gamma( &mut self, shape: f64, scale: f64, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

Generate an array of gamma-distributed variates.

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

Arguments

• shape - Shape parameter (alpha), must be positive.
• scale - Scale parameter (beta), must be positive.
• size - Number of values to generate.

Errors

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

pub fn beta( &mut self, a: f64, b: f64, size: usize, ) -> Result<Array<f64, Ix1>, 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).

Arguments

• a - First shape parameter, must be positive.
• b - Second shape parameter, must be positive.
• size - Number of values to generate.

Errors

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

pub fn chisquare( &mut self, df: f64, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

Generate an array of chi-squared distributed variates.

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

Arguments

• df - Degrees of freedom, must be positive.
• size - Number of values to generate.

Errors

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

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

Generate an array of F-distributed variates.

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

Arguments

• dfnum - Numerator degrees of freedom, must be positive.
• dfden - Denominator degrees of freedom, must be positive.
• size - Number of values to generate.

Errors

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

pub fn student_t( &mut self, df: f64, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

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

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

Arguments

• df - Degrees of freedom, must be positive.
• size - Number of values to generate.

Errors

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

impl<B: BitGenerator> Generator<B>

pub fn laplace( &mut self, loc: f64, scale: f64, size: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, 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: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

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

Uses the Box-Muller transform for generation.

Arguments

• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if size is zero.

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

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

Arguments

• loc - Mean of the distribution.
• scale - Standard deviation (must be positive).
• size - Number of values to generate.

Errors

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

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

Generate an array of log-normal variates.

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

Arguments

• mean - Mean of the underlying normal distribution.
• sigma - Standard deviation of the underlying normal distribution (must be positive).
• size - Number of values to generate.

Errors

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

impl<B: BitGenerator> Generator<B>

pub fn random(&mut self, size: usize) -> Result<Array<f64, Ix1>, FerrayError>

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

Equivalent to NumPy’s Generator.random(size).

Arguments

• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if size is zero.

Example

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

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

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

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

Arguments

• low - Lower bound (inclusive).
• high - Upper bound (exclusive).
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if low >= high or size is zero.

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

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

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

Arguments

• low - Lower bound (inclusive).
• high - Upper bound (exclusive).
• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if low >= high or size is zero.

impl<B: BitGenerator> Generator<B>

pub fn new(bg: B) -> Self

Create a new Generator wrapping the given BitGenerator.

pub 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_u64_bounded(&mut self, bound: u64) -> u64

Generate a u64 in [0, bound).

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

pub fn standard_normal_parallel( &mut self, size: usize, ) -> Result<Array<f64, Ix1>, FerrayError>

Generate standard normal variates in parallel, deterministically.

The output is identical to standard_normal(size) with the same seed. Parallelism uses jump-ahead (Xoshiro256**) or stream IDs (Philox) to derive per-chunk generators. The chunk assignment is fixed (not work-stealing) so results are deterministic.

For BitGenerators that do not support jump or streams (e.g., PCG64), this falls back to sequential generation.

Arguments

• size - Number of values to generate.

Errors

Returns FerrayError::InvalidValue if size is zero.

pub fn spawn(&mut self, n: usize) -> Result<Vec<Generator<B>>, 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).