Random sampling (dpnp.random)

Hint

NumPy API Reference: Random sampling

DPNP draws random numbers on the SYCL device, by default with the counter-based Philox4x32x10 generator of the oneMKL device RNG API, or with NumPy's PCG64DXSM generator or the MRG32k3a generator of the oneMKL device RNG API. It provides both NumPy random APIs: the Generator API recommended for new code, and the legacy RandomState API with the module-level functions built on it.

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, and the samples depend only on the seed, not on the device, except that the discrete distributions also depend on its support of double precision. All samples are dpnp.ndarray, zero-dimensional when size is None.

Differences from NumPy

• The same seed gives the same stream on every device, but for the discrete distributions noted below. The streams differ from NumPy's, except that PCG64DXSM gives NumPy's raw values, Generator.random(), Generator.uniform() and Generator.bytes(), and can exchange states with numpy.random.PCG64DXSM.

• The floating-point distributions take a dtype keyword, as in CuPy, which defaults to the default floating-point type of the device. All methods take a usm_type keyword.

• Parameters on the host (Python scalars, lists and NumPy arrays) are checked as in NumPy. In Generator, 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.

• RandomState.randint() and randint() return int64 values by default, as do RandomState.random_integers(), random_integers() and RandomState.tomaxint(), whose values reach the largest int64. NumPy returns a C long instead, which is int32 on Windows.

• hypergeometric requires ngood and nbad below 10**9, also in RandomState.

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

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.

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.
Philox4x3210	A Philox4x32-10 counter-based bit generator on the device.
PCG64DXSM	NumPy's PCG64DXSM bit generator on the device.
MRG32k3a	An MRG32k3a combined multiple recursive 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

RandomState keeps the parameter checks of NumPy's legacy one, also for parameters in dpnp.ndarray, as CuPy's does, so that a call with such parameters waits for the device to check them. The module-level functions use one RandomState per SYCL queue: the queue given by the device or sycl_queue keyword, or else the queue of a dpnp.ndarray parameter, or else the default queue.

RandomState	A container of a pseudo-random number generator on a SYCL device, with the legacy API of NumPy.
seed	Reseed the state of a queue.
get_state	Return the state of a queue.
set_state	Set the state of a queue.
get_bit_generator	Return the bit generator of the state of a queue, which the dpnp.random functions draw from on that queue.
set_bit_generator	Set the bit generator of the state of the queue of bitgen, which the dpnp.random functions then draw from on that queue.

Simple random data

rand	Random values in a given shape, from a uniform distribution over [0, 1).
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	Generate a random sample from a given 1-D array.
bytes	Return random bytes.

Permutations

shuffle	Modify an array in place by shuffling its contents along the first axis.
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.
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 noncentral chi-square distribution.
noncentral_f	Draw samples from the noncentral 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 over [low, high).
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	Draw samples from a Zipf distribution.