Random sampling (dpnp.random)

Hint

NumPy API Reference: Random sampling

DPNP draws random numbers on the SYCL device, with the counter-based Philox4x32x10 generator of the oneMKL device RNG API. It provides the Generator API of NumPy, recommended for new code. The legacy RandomState API and the module-level functions still use the host-side oneMKL RNG.

import dpnp

rng = dpnp.random.default_rng(seed=42)
x = rng.standard_normal((3, 4))                # on the default device
y = rng.integers(0, 10, size=5, usm_type="shared")

rng = dpnp.random.default_rng(42, device="cpu")

A generator draws all its samples on one SYCL queue, chosen with the device or sycl_queue keyword when it is created. All samples are dpnp.ndarray, zero-dimensional when size is None.

Differences from NumPy

• The streams differ from NumPy's. For a given seed, output size and data type, the raw bits and the uniform floats are the same on every device. The other distributions use transcendental functions, which may round differently on another device: their samples agree to a few ULP, or differ when a rejection sampler then takes another candidate. The discrete distributions also depend on the device's support of double precision, as noted below.

• The values depend on the output size: a draw is not a prefix of a larger one, and two draws of n values differ from one draw of 2 * n. Code splitting its draws into chunks gets other values.

• The floating-point distributions take a dtype keyword, as in CuPy, which defaults to the default floating-point type of the device, so on a device without double precision the same seed gives other values by default.

• All methods take a usm_type keyword. With usm_type=None, the default, the samples take the USM type of the array parameters, or "device" when there are none.

• Parameters on the host (Python scalars, lists and NumPy arrays) are checked as in NumPy. Parameters in dpnp.ndarray are not, since that would wait for the device. Invalid ones give undefined values, such as NaN or the smallest int64, but the kernels handle them safely: they never loop without end or access memory out of bounds. Floating-point arrays given for integer parameters are converted as by dpnp.ndarray.astype(), whose result for NaN and out-of-range values is undefined.

• The discrete distributions return int64 values. They compute in double precision on devices supporting it, and in single precision otherwise. There, the streams differ from the ones of devices with double precision, and some samples are only multiples of a power of two: the ones above 2**24 of geometric, logseries and zipf, and the ones of poisson and binomial with a standard deviation above about 2**22.

• zipf follows the Zipf distribution truncated to the largest int64. NumPy's rejection test rounds to accepting every sample above 2**53, which makes its tail too heavy for a close to 1.

• hypergeometric requires ngood and nbad below 10**9.

• Generator.shuffle() only accepts a dpnp.ndarray, as in CuPy.

• Generators and bit generators cannot be pickled or copied, and the bit generators have no advance or jumped method.

Random Generator

default_rng	Construct a new dpnp.random.Generator with the default bit generator, dpnp.random.Philox4x3210.
Generator	A container for the bit generator and the distribution samplers.

Accessing the bit generator and spawning

Generator.bit_generator	The bit generator used by the generator.
Generator.spawn	Create new independent child generators on the same SYCL queue.

Simple random data

Generator.integers	Return random integers from low (inclusive) to high (exclusive), or if endpoint=True, low (inclusive) to high (inclusive).
Generator.random	Return random floats in the half-open interval [0.0, 1.0).
Generator.choice	Generate a random sample from a given array.
Generator.bytes	Return random bytes.

Permutations

Generator.shuffle	Modify an array in place by shuffling its contents.
Generator.permutation	Randomly permute a sequence, or return a permuted range.
Generator.permuted	Randomly permute x along axis axis.

Distributions

Generator.beta	Draw samples from a beta distribution.
Generator.binomial	Draw samples from a binomial distribution.
Generator.chisquare	Draw samples from a chi-square distribution.
Generator.dirichlet	Draw samples from the Dirichlet distribution.
Generator.exponential	Draw samples from an exponential distribution.
Generator.f	Draw samples from an F distribution.
Generator.gamma	Draw samples from a gamma distribution.
Generator.geometric	Draw samples from the geometric distribution.
Generator.gumbel	Draw samples from a Gumbel distribution.
Generator.hypergeometric	Draw samples from a hypergeometric distribution.
Generator.laplace	Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
Generator.logistic	Draw samples from a logistic distribution.
Generator.lognormal	Draw samples from a log-normal distribution.
Generator.logseries	Draw samples from a logarithmic series distribution.
Generator.multinomial	Draw samples from a multinomial distribution.
Generator.multivariate_hypergeometric	Generate variates from a multivariate hypergeometric distribution.
Generator.multivariate_normal	Draw random samples from a multivariate normal distribution.
Generator.negative_binomial	Draw samples from a negative binomial distribution.
Generator.noncentral_chisquare	Draw samples from a noncentral chi-square distribution.
Generator.noncentral_f	Draw samples from the noncentral F distribution.
Generator.normal	Draw samples from a normal (Gaussian) distribution.
Generator.pareto	Draw samples from a Pareto II (AKA Lomax) distribution with the specified shape.
Generator.poisson	Draw samples from a Poisson distribution.
Generator.power	Draw samples in [0, 1] from a power distribution with positive exponent a - 1.
Generator.rayleigh	Draw samples from a Rayleigh distribution.
Generator.standard_cauchy	Draw samples from a standard Cauchy distribution with mode = 0.
Generator.standard_exponential	Draw samples from the standard exponential distribution.
Generator.standard_gamma	Draw samples from a standard gamma distribution.
Generator.standard_normal	Draw samples from a standard normal distribution.
Generator.standard_t	Draw samples from a standard Student's t distribution with df degrees of freedom.
Generator.triangular	Draw samples from the triangular distribution over the interval [left, right].
Generator.uniform	Draw samples from a uniform distribution over [low, high).
Generator.vonmises	Draw samples from a von Mises distribution.
Generator.wald	Draw samples from a Wald, or inverse Gaussian, distribution.
Generator.weibull	Draw samples from a Weibull distribution.
Generator.zipf	Draw samples from a Zipf distribution.

Bit generators

BitGenerator	Base class for the bit generators of dpnp.random.Generator.
BitGenerator.random_raw	Return raw 64-bit outputs of the bit generator.
BitGenerator.spawn	Create new independent child bit generators on the same SYCL queue.
BitGenerator.state	The state of the bit generator, as a dictionary.
Philox4x3210	A Philox4x32-10 counter-based bit generator on the device.
SeedSequence	SeedSequence mixes sources of entropy in a reproducible way to set the initial state for independent and very probably non-overlapping BitGenerators.

Legacy random generation

Hint

NumPy API Reference: Legacy random generation

Simple random data

rand	Random values in a given shape.
randn	Return a sample (or samples) from the "standard normal" distribution.
randint	Return random integers from low (inclusive) to high (exclusive).
random_integers	Random integers between low and high, inclusive.
random_sample	Return random floats in the half-open interval [0.0, 1.0).
random	Return random floats in the half-open interval [0.0, 1.0).
ranf	Return random floats in the half-open interval [0.0, 1.0).
sample	Return random floats in the half-open interval [0.0, 1.0).
choice	Generates a random sample from a given 1-D array.
bytes	Return random bytes.

Permutations

shuffle	Modify a sequence in-place by shuffling its contents.
permutation	Randomly permute a sequence, or return a permuted range.

Distributions

beta	Draw samples from a Beta distribution.
binomial	Draw samples from a binomial distribution.
chisquare	Draw samples from a chi-square distribution.
dirichlet	Draw samples from the Dirichlet distribution.
exponential	Draw samples from an exponential distribution.
f	Draw samples from an F distribution.
gamma	Draw samples from a Gamma distribution.
geometric	Draw samples from the geometric distribution.
gumbel	Draw samples from a Gumbel distribution.
hypergeometric	Draw samples from a Hypergeometric distribution.
laplace	Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
logistic	Draw samples from a logistic distribution.
lognormal	Draw samples from a log-normal distribution.
logseries	Draw samples from a logarithmic series distribution.
multinomial	Draw samples from a multinomial distribution.
multivariate_normal	Draw random samples from a multivariate normal distribution.
negative_binomial	Draw samples from a negative binomial distribution.
noncentral_chisquare	Draw samples from a non-central chi-square distribution.
noncentral_f	Draw samples from the non-central F distribution.
normal	Draw random samples from a normal (Gaussian) distribution.
pareto	Draw samples from a Pareto II or Lomax distribution with specified shape.
poisson	Draw samples from a Poisson distribution.
power	Draws samples in [0, 1] from a power distribution with positive exponent a - 1.
rayleigh	Draw samples from a Rayleigh distribution.
standard_cauchy	Draw samples from a standard Cauchy distribution with mode = 0.
standard_exponential	Draw samples from the standard exponential distribution.
standard_gamma	Draw samples from a standard Gamma distribution.
standard_normal	Draw samples from a standard Normal distribution (mean=0, stdev=1).
standard_t	Draw samples from a standard Student’s t distribution with df degrees of freedom.
triangular	Draw samples from the triangular distribution over the interval [left, right].
uniform	Draw samples from a uniform distribution.
vonmises	Draw samples from a von Mises distribution.
wald	Draw samples from a Wald, or inverse Gaussian, distribution.
weibull	Draw samples from a Weibull distribution.
zipf	Returns an array of samples drawn from the Zipf distribution.

Random generator

RandomState	A container for the Mersenne Twister pseudo-random number generator.
seed	Reseed a legacy MT19937 random number generator engine.