Random Functions

Chunk-parallel, NumPy-quality random NDArray constructors. Each chunk gets its own independent SeedSequence-spawned stream and is generated concurrently in a thread pool, so generation itself parallelizes (not just compression).

examples/ndarray/random-constructor.py is a runnable walkthrough: basic draws, reproducibility semantics, passing blosc2 storage arguments through, a vector-valued distribution, and a timing comparison against asarray(np.random...). Start there if you just want working code.

default_rng([seed])	Construct a chunk-parallel Generator, mirroring numpy.random.default_rng().
Generator([seed])	Chunk-parallel counterpart of numpy.random.Generator.

blosc2.random.default_rng(seed=None) → Generator

Construct a chunk-parallel Generator, mirroring numpy.random.default_rng().

Parameters:

seed (int, array-like, SeedSequence or None) – Seed for the root numpy.random.SeedSequence. None (default) draws entropy from the OS.

Returns:

out

Return type:

Generator

class blosc2.random.Generator(seed=None)

Chunk-parallel counterpart of numpy.random.Generator.

Create via default_rng(). Each method call draws a full NDArray in one shot, generating its chunks concurrently.

Methods

beta(a, b, *, shape, **kwargs)	Draw samples from a beta distribution.
binomial(n, p, *, shape, **kwargs)	Draw samples from a binomial distribution.
chisquare(df, *, shape, **kwargs)	Draw samples from a chi-square distribution.
choice(a, *, shape[, p, replace])	Draw samples from a with replacement.
dirichlet(alpha, *, shape, **kwargs)	Draw samples from a Dirichlet distribution.
exponential([scale])	Draw samples from an exponential distribution.
f(dfnum, dfden, *, shape, **kwargs)	Draw samples from an F distribution.
gamma(shape_param, /[, scale])	Draw samples from a gamma distribution.
geometric(p, *, shape, **kwargs)	Draw samples from a geometric distribution.
gumbel([loc, scale])	Draw samples from a Gumbel distribution.
hypergeometric(ngood, nbad, nsample, *, ...)	Draw samples from a hypergeometric distribution.
integers(low[, high, dtype, endpoint])	Draw random integers.
laplace([loc, scale])	Draw samples from a Laplace distribution.
logistic([loc, scale])	Draw samples from a logistic distribution.
lognormal([mean, sigma])	Draw samples from a log-normal distribution.
logseries(p, *, shape, **kwargs)	Draw samples from a logarithmic series distribution.
multinomial(n, pvals, *, shape, **kwargs)	Draw samples from a multinomial distribution.
multivariate_hypergeometric(colors, nsample, ...)	Draw samples from a multivariate hypergeometric distribution.
multivariate_normal(mean, cov, *, shape, ...)	Draw samples from a multivariate normal distribution.
negative_binomial(n, p, *, shape, **kwargs)	Draw samples from a negative binomial distribution.
noncentral_chisquare(df, nonc, *, shape, ...)	Draw samples from a noncentral chi-square distribution.
noncentral_f(dfnum, dfden, nonc, *, shape, ...)	Draw samples from a noncentral F distribution.
normal([loc, scale])	Draw samples from a normal distribution.
pareto(a, *, shape, **kwargs)	Draw samples from a Pareto distribution.
permutation(x, *[, axis])	Return a shuffled copy of x (or of arange(x) if x is an int).
permuted(x, *[, axis])	Return a copy of x with elements permuted along axis (flattened if None).
poisson([lam])	Draw samples from a Poisson distribution.
power(a, *, shape, **kwargs)	Draw samples from a power distribution.
random(shape[, dtype])	Draw uniform floats in [0, 1).
rayleigh([scale])	Draw samples from a Rayleigh distribution.
shuffle(x, *[, axis])	Shuffle x in place along axis.
standard_cauchy(*, shape, **kwargs)	Draw samples from a standard Cauchy distribution.
standard_exponential(*, shape[, dtype, method])	Draw samples from a standard exponential distribution.
standard_gamma(shape_param, /, *, shape[, dtype])	Draw samples from a standard gamma distribution.
standard_normal(*, shape[, dtype])	Draw samples from a standard normal distribution.
standard_t(df, *, shape, **kwargs)	Draw samples from a standard Student's t distribution.
triangular(left, mode, right, *, shape, **kwargs)	Draw samples from a triangular distribution.
uniform([low, high])	Draw samples from a uniform distribution.
vonmises(mu, kappa, *, shape, **kwargs)	Draw samples from a von Mises distribution.
wald(mean, scale, *, shape, **kwargs)	Draw samples from a Wald distribution.
weibull(a, *, shape, **kwargs)	Draw samples from a Weibull distribution.
zipf(a, *, shape, **kwargs)	Draw samples from a Zipf distribution.

beta(a, b, *, shape, **kwargs: Any) → NDArray

Draw samples from a beta distribution. Mirrors numpy.random.Generator.beta().

binomial(n, p, *, shape, **kwargs: Any) → NDArray

Draw samples from a binomial distribution. Mirrors numpy.random.Generator.binomial().

chisquare(df, *, shape, **kwargs: Any) → NDArray

Draw samples from a chi-square distribution. Mirrors numpy.random.Generator.chisquare().

choice(a, *, shape, p=None, replace: bool = True, **kwargs: Any) → NDArray

Draw samples from a with replacement. Mirrors numpy.random.Generator.choice().

Only replace=True (numpy’s default) and 1-D or scalar-int a are supported: sampling without replacement, or along an axis of a multi-dimensional a, needs whole-array coordination across chunks that this module doesn’t do.

dirichlet(alpha, *, shape, **kwargs: Any) → NDArray

Draw samples from a Dirichlet distribution. Mirrors numpy.random.Generator.dirichlet().

Output shape is shape + (len(alpha),); see _fill_vector() — the trailing dimension holds one full draw and is never split across chunks.

exponential(scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from an exponential distribution. Mirrors numpy.random.Generator.exponential().

f(dfnum, dfden, *, shape, **kwargs: Any) → NDArray

Draw samples from an F distribution. Mirrors numpy.random.Generator.f().

gamma(shape_param, /, scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a gamma distribution. Mirrors numpy.random.Generator.gamma().

shape_param is numpy’s shape (the gamma distribution’s shape parameter, usually called k); renamed here, and made positional-only, to avoid colliding with the array-shape shape keyword.

geometric(p, *, shape, **kwargs: Any) → NDArray

Draw samples from a geometric distribution. Mirrors numpy.random.Generator.geometric().

gumbel(loc=0.0, scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a Gumbel distribution. Mirrors numpy.random.Generator.gumbel().

hypergeometric(ngood, nbad, nsample, *, shape, **kwargs: Any) → NDArray

Draw samples from a hypergeometric distribution. Mirrors numpy.random.Generator.hypergeometric().

integers(low, high=None, *, shape, dtype=<class 'numpy.int64'>, endpoint: bool = False, **kwargs: ~typing.Any) → NDArray

Draw random integers. Mirrors numpy.random.Generator.integers().

laplace(loc=0.0, scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a Laplace distribution. Mirrors numpy.random.Generator.laplace().

logistic(loc=0.0, scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a logistic distribution. Mirrors numpy.random.Generator.logistic().

lognormal(mean=0.0, sigma=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a log-normal distribution. Mirrors numpy.random.Generator.lognormal().

logseries(p, *, shape, **kwargs: Any) → NDArray

Draw samples from a logarithmic series distribution. Mirrors numpy.random.Generator.logseries().

multinomial(n, pvals, *, shape, **kwargs: Any) → NDArray

Draw samples from a multinomial distribution. Mirrors numpy.random.Generator.multinomial().

Output shape is shape + (len(pvals),); see dirichlet() for the trailing-dimension note.

multivariate_hypergeometric(colors, nsample, *, shape, **kwargs: Any) → NDArray

Draw samples from a multivariate hypergeometric distribution.

Mirrors numpy.random.Generator.multivariate_hypergeometric(). Output shape is shape + (len(colors),); see dirichlet() for the trailing-dimension note.

multivariate_normal(mean, cov, *, shape, **kwargs: Any) → NDArray

Draw samples from a multivariate normal distribution.

Mirrors numpy.random.Generator.multivariate_normal(). Output shape is shape + (len(mean),); see dirichlet() for the trailing-dimension note.

negative_binomial(n, p, *, shape, **kwargs: Any) → NDArray

Draw samples from a negative binomial distribution. Mirrors numpy.random.Generator.negative_binomial().

noncentral_chisquare(df, nonc, *, shape, **kwargs: Any) → NDArray

Draw samples from a noncentral chi-square distribution. Mirrors numpy.random.Generator.noncentral_chisquare().

noncentral_f(dfnum, dfden, nonc, *, shape, **kwargs: Any) → NDArray

Draw samples from a noncentral F distribution. Mirrors numpy.random.Generator.noncentral_f().

normal(loc=0.0, scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a normal distribution. Mirrors numpy.random.Generator.normal().

pareto(a, *, shape, **kwargs: Any) → NDArray

Draw samples from a Pareto distribution. Mirrors numpy.random.Generator.pareto().

permutation(x, *, axis: int = 0, **kwargs: Any) → NDArray

Return a shuffled copy of x (or of arange(x) if x is an int).

Mirrors numpy.random.Generator.permutation().

Unlike the rest of this module, permuting is inherently sequential: it loads x fully into memory and shuffles it single-threaded, rather than generating chunks independently in parallel.

permuted(x, *, axis: int | None = None, **kwargs: Any) → NDArray

Return a copy of x with elements permuted along axis (flattened if None).

Mirrors numpy.random.Generator.permuted(). See permutation() for the single-threaded, full-materialization caveat.

poisson(lam=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a Poisson distribution. Mirrors numpy.random.Generator.poisson().

power(a, *, shape, **kwargs: Any) → NDArray

Draw samples from a power distribution. Mirrors numpy.random.Generator.power().

random(shape, dtype=<class 'numpy.float64'>, **kwargs: ~typing.Any) → NDArray

Draw uniform floats in [0, 1). Mirrors numpy.random.Generator.random().

rayleigh(scale=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a Rayleigh distribution. Mirrors numpy.random.Generator.rayleigh().

shuffle(x: NDArray, *, axis: int = 0) → None

Shuffle x in place along axis. Mirrors numpy.random.Generator.shuffle().

x must be a NDArray: its full contents are read into memory, shuffled single-threaded (see permutation()), and written back. Returns None, matching numpy.

standard_cauchy(*, shape, **kwargs: Any) → NDArray

Draw samples from a standard Cauchy distribution. Mirrors numpy.random.Generator.standard_cauchy().

standard_exponential(*, shape, dtype=<class 'numpy.float64'>, method='zig', **kwargs: ~typing.Any) → NDArray

Draw samples from a standard exponential distribution.

Mirrors numpy.random.Generator.standard_exponential().

standard_gamma(shape_param, /, *, shape, dtype=<class 'numpy.float64'>, **kwargs: ~typing.Any) → NDArray

Draw samples from a standard gamma distribution.

Mirrors numpy.random.Generator.standard_gamma(); see gamma() for why the distribution’s shape parameter is renamed shape_param here.

standard_normal(*, shape, dtype=<class 'numpy.float64'>, **kwargs: ~typing.Any) → NDArray

Draw samples from a standard normal distribution.

Mirrors numpy.random.Generator.standard_normal().

standard_t(df, *, shape, **kwargs: Any) → NDArray

Draw samples from a standard Student’s t distribution. Mirrors numpy.random.Generator.standard_t().

triangular(left, mode, right, *, shape, **kwargs: Any) → NDArray

Draw samples from a triangular distribution. Mirrors numpy.random.Generator.triangular().

uniform(low=0.0, high=1.0, *, shape, **kwargs: Any) → NDArray

Draw samples from a uniform distribution. Mirrors numpy.random.Generator.uniform().

vonmises(mu, kappa, *, shape, **kwargs: Any) → NDArray

Draw samples from a von Mises distribution. Mirrors numpy.random.Generator.vonmises().

wald(mean, scale, *, shape, **kwargs: Any) → NDArray

Draw samples from a Wald distribution. Mirrors numpy.random.Generator.wald().

weibull(a, *, shape, **kwargs: Any) → NDArray

Draw samples from a Weibull distribution. Mirrors numpy.random.Generator.weibull().

zipf(a, *, shape, **kwargs: Any) → NDArray

Draw samples from a Zipf distribution. Mirrors numpy.random.Generator.zipf().

NumPy compatibility

Generator mirrors numpy.random.Generator method-for-method: same method names, same distribution parameters, same math. A few differences apply consistently across the module:

• shape replaces numpy’s size and is required (no implicit scalar draws), and keyword-only on every method except random().

• There is no out= parameter — each call allocates its own destination NDArray, filled chunk by chunk.

• Extra keyword arguments (chunks, cparams, urlpath, …) are forwarded to blosc2.empty().

• Results are reproducible for a given (seed, call order, shape, chunks); changing the chunk layout changes the values, since chunks map one-to-one to independent SeedSequence streams.

• gamma() and standard_gamma() rename numpy’s distribution-shape parameter (itself called shape) to shape_param, and make it positional-only, to avoid colliding with the array-shape shape keyword.

• choice() only supports replace=True (numpy’s default) and a 1-D or scalar-int a; sampling without replacement, or along an axis of a multi-dimensional a, needs whole-array coordination across chunks that this module doesn’t do.

• The vector-valued distributions (dirichlet(), multinomial(), multivariate_hypergeometric(), multivariate_normal()) draw one length-k vector per element: output shape is shape + (k,), and that trailing dimension is always kept whole within a chunk.

• permutation(), permuted(), and shuffle() are not chunk-parallel: whole-array shuffling is inherently sequential, so these load the full array into memory and shuffle it single-threaded rather than generating chunks independently. shuffle() additionally requires its argument to already be a NDArray, since it mutates it in place and returns None, matching numpy.

Coverage of numpy.random.Generator’s public methods:

Method	Status	Notes
beta	✅
binomial	✅
bytes	❌	returns raw bytes, not an NDArray — outside this module’s contract
chisquare	✅
choice	✅	replace=True and 1-D/scalar a only
dirichlet	✅	vector output, see above
exponential	✅
f	✅
gamma	✅	distribution-shape parameter renamed shape_param
geometric	✅
gumbel	✅
hypergeometric	✅
integers	✅
laplace	✅
logistic	✅
lognormal	✅
logseries	✅
multinomial	✅	vector output, see above
multivariate_hypergeometric	✅	vector output, see above
multivariate_normal	✅	vector output, see above
negative_binomial	✅
noncentral_chisquare	✅
noncentral_f	✅
normal	✅
pareto	✅
permutation	✅	single-threaded, full-materialization — see above
permuted	✅	single-threaded, full-materialization — see above
poisson	✅
power	✅
random	✅
rayleigh	✅
shuffle	✅	single-threaded, full-materialization; requires an NDArray — see above
standard_cauchy	✅
standard_exponential	✅
standard_gamma	✅	distribution-shape parameter renamed shape_param
standard_normal	✅
standard_t	✅
triangular	✅
uniform	✅
vonmises	✅
wald	✅
weibull	✅
zipf	✅