cupy.random.Generator

class cupy.random.Generator(bit_generator)

Container for the BitGenerators.

Generator exposes a number of methods for generating random numbers drawn from a variety of probability distributions. In addition to the distribution-specific arguments, each method takes a keyword argument size that defaults to None. If size is None, then a single value is generated and returned. If size is an integer, then a 1-D array filled with generated values is returned. If size is a tuple, then an array with that shape is filled and returned. The function numpy.random.default_rng() will instantiate a Generator with numpy’s default BitGenerator. No Compatibility Guarantee Generator does not provide a version compatibility guarantee. In particular, as better algorithms evolve the bit stream may change.

Parameters

bit_generator – (cupy.random.BitGenerator): BitGenerator to use as the core generator.

Methods

beta(self, a, b, size=None, dtype=numpy.float64)

Beta distribution.

Returns an array of samples drawn from the beta distribution. Its probability density function is defined as

\[f(x) = \frac{x^{\alpha-1}(1-x)^{\beta-1}}{B(\alpha,\beta)}.\]
Parameters
  • a (float) – Parameter of the beta distribution \(\alpha\).

  • b (float) – Parameter of the beta distribution \(\beta\).

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed.

Returns

Samples drawn from the beta distribution.

Return type

cupy.ndarray

binomial(self, n, p, size=None)

Binomial distribution.

Returns an array of samples drawn from the binomial distribution. Its probability mass function is defined as

\[f(x) = \binom{n}{x}p^x(1-p)^(n-x).\]
Parameters
  • n (int or cupy.ndarray of ints) – Parameter of the distribution, >= 0. Floats are also accepted, but they will be truncated to integers.

  • p (float or cupy.ndarray of floats) – Parameter of the distribution, >= 0 and <= 1.

  • size (int or tuple of ints, optional) – The shape of the output array. If None (default), a single value is returned if n and p are both scalars. Otherwise, cupy.broadcast(n, p).size samples are drawn.

Returns

Samples drawn from the binomial distribution.

Return type

cupy.ndarray

chisquare(self, df, size=None)

Chi-square distribution.

Returns an array of samples drawn from the chi-square distribution. Its probability density function is defined as

\[f(x) = \frac{(1/2)^{k/2}}{\Gamma(k/2)}x^{k/2-1}e^{-x/2}.\]
Parameters
  • df (float or array_like of floats) – Degree of freedom \(k\).

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

Returns

Samples drawn from the chi-square distribution.

Return type

cupy.ndarray

dirichlet(self, alpha, size=None)

Dirichlet distribution.

Returns an array of samples drawn from the dirichlet distribution. Its probability density function is defined as

\[f(x) = \frac{\Gamma(\sum_{i=1}^K\alpha_i)} {\prod_{i=1}^{K}\Gamma(\alpha_i)} \prod_{i=1}^Kx_i^{\alpha_i-1}.\]
Parameters
  • alpha (array) – Parameters of the dirichlet distribution \(\alpha\).

  • size (int or tuple of ints) – The shape of the array. If None, array of alpha.shape is generated

Returns

Samples drawn from the dirichlet distribution.

Return type

cupy.ndarray

exponential(self, scale=1.0, size=None)

Exponential distribution.

Returns an array of samples drawn from the exponential distribution. Its probability density function is defined as

\[f(x) = \frac{1}{\beta}\exp (-\frac{x}{\beta}).\]
Parameters
  • scale (float or array_like of floats) – The scale parameter \(\beta\).

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

Returns

Samples drawn from the exponential distribution.

Return type

cupy.ndarray

f(self, dfnum, dfden, size=None)

F distribution.

Returns an array of samples drawn from the f distribution. Its probability density function is defined as

\[f(x) = \frac{1}{B(\frac{d_1}{2},\frac{d_2}{2})} \left(\frac{d_1}{d_2}\right)^{\frac{d_1}{2}} x^{\frac{d_1}{2}-1} \left(1+\frac{d_1}{d_2}x\right) ^{-\frac{d_1+d_2}{2}}.\]
Parameters
  • dfnum (float or array_like of floats) – Degrees of freedom in numerator, \(d_1\).

  • dfden (float or array_like of floats) – Degrees of freedom in denominator, \(d_2\).

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

Returns

Samples drawn from the f distribution.

Return type

cupy.ndarray

gamma(self, shape, scale=1.0, size=None)

Gamma distribution.

Returns an array of samples drawn from the gamma distribution. Its probability density function is defined as

\[f(x) = \frac{1}{\Gamma(k)\theta^k}x^{k-1}e^{-x/\theta}.\]
Parameters
  • shape (float or array_like of float) – The shape of the gamma distribution. Must be non-negative.

  • scale (float or array_like of float) – The scale of the gamma distribution. Must be non-negative. Default equals to 1

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

geometric(self, p, size=None)

Geometric distribution.

Returns an array of samples drawn from the geometric distribution. Its probability mass function is defined as

\[f(x) = p(1-p)^{k-1}.\]
Parameters
  • p (float or cupy.ndarray of floats) – Success probability of the geometric distribution.

  • size (int or tuple of ints, optional) – The shape of the output array. If None (default), a single value is returned if p is scalar. Otherwise, p.size samples are drawn.

Returns

Samples drawn from the geometric distribution.

Return type

cupy.ndarray

hypergeometric(self, ngood, nbad, nsample, size=None)

Hypergeometric distribution.

Returns an array of samples drawn from the hypergeometric distribution. Its probability mass function is defined as

\[f(x) = \frac{\binom{m}{n}\binom{N-m}{n-x}}{\binom{N}{n}}.\]
Parameters
  • ngood (int or array_like of ints) – Parameter of the hypergeometric distribution \(n\).

  • nbad (int or array_like of ints) – Parameter of the hypergeometric distribution \(m\).

  • nsample (int or array_like of ints) – Parameter of the hypergeometric distribution \(N\).

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

Returns

Samples drawn from the hypergeometric distribution.

Return type

cupy.ndarray

integers(self, low, high=None, size=None, dtype=numpy.int64, endpoint=False)

Returns a scalar or an array of integer values over an interval.

Each element of returned values are independently sampled from uniform distribution over the [low, high) or [low, high] intervals.

Parameters
  • low (int) – If high is not None, it is the lower bound of the interval. Otherwise, it is the upper bound of the interval and lower bound of the interval is set to 0.

  • high (int) – Upper bound of the interval.

  • size (None or int or tuple of ints) – The shape of returned value.

  • dtype – Data type specifier.

  • endpoint (bool) – If True, sample from [low, high]. Defaults to False

Returns

If size is None, it is single integer sampled. If size is integer, it is the 1D-array of length size element. Otherwise, it is the array whose shape specified by size.

Return type

int or cupy.ndarray of ints

logseries(self, p, size=None)

Log series distribution.

Returns an array of samples drawn from the log series distribution. Its probability mass function is defined as

\[f(x) = \frac{-p^x}{x\ln(1-p)}.\]
Parameters
  • p (float or cupy.ndarray of floats) – Parameter of the log series distribution. Must be in the range (0, 1).

  • size (int or tuple of ints, optional) – The shape of the output array. If None (default), a single value is returned if p is scalar. Otherwise, p.size samples are drawn.

Returns

Samples drawn from the log series distribution.

Return type

cupy.ndarray

poisson(self, lam=1.0, size=None)

Poisson distribution.

Returns an array of samples drawn from the poisson distribution. Its probability mass function is defined as

\[f(x) = \frac{\lambda^xe^{-\lambda}}{x!}.\]
Parameters
  • lam (float or array_like of floats) – Parameter of the poisson distribution \(\lambda\).

  • size (int or tuple of ints) – The shape of the array. If None, this function generate an array whose shape is lam.shape.

Returns

Samples drawn from the poisson distribution.

Return type

cupy.ndarray

power(self, a, size=None)

Power distribution.

Returns an array of samples drawn from the power distribution. Its probability density function is defined as

\[f(x) = ax^{a-1}.\]
Parameters
  • a (float or array_like of floats) – Parameter of the power distribution \(a\).

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

Returns

Samples drawn from the power distribution.

Return type

cupy.ndarray

random(self, size=None, dtype=numpy.float64, out=None)

Return random floats in the half-open interval [0.0, 1.0).

Results are from the “continuous uniform” distribution over the stated interval. To sample \(Unif[a, b), b > a\) multiply the output of random by (b-a) and add a:

(b - a) * random() + a
Parameters
  • size (None or int or tuple of ints) – The shape of returned value.

  • dtype – Data type specifier.

  • out (cupy.ndarray, optional) – If specified, values will be written to this array

Returns

Samples uniformly drawn from the [0, 1) interval

Return type

cupy.ndarray

standard_exponential(self, size=None, dtype=numpy.float64, method='inv', out=None)

Standard exponential distribution.

Returns an array of samples drawn from the standard exponential distribution. Its probability density function is defined as

\[f(x) = e^{-x}.\]
Parameters
  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed.

  • method (str) – Method to sample. Currently only 'inv', sampling from the default inverse CDF, is supported.

  • out (cupy.ndarray, optional) – If specified, values will be written to this array

Returns

Samples drawn from the standard exponential distribution.

Return type

cupy.ndarray

standard_gamma(self, shape, size=None, dtype=numpy.float64, out=None)

Standard gamma distribution.

Returns an array of samples drawn from the standard gamma distribution. Its probability density function is defined as

\[f(x) = \frac{1}{\Gamma(k)}x^{k-1}e^{-x}.\]
Parameters
  • shape (float or array_like of float) – The shape of the gamma distribution. Must be non-negative.

  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

  • dtype – Data type specifier.

  • out (cupy.ndarray, optional) – If specified, values will be written to this array

standard_normal(self, size=None, dtype=numpy.float64, out=None)

Standard normal distribution.

Returns an array of samples drawn from the standard normal distribution.

Parameters
  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.

  • dtype – Data type specifier.

  • out (cupy.ndarray, optional) – If specified, values will be written to this array

Returns

Samples drawn from the standard normal distribution.

Return type

cupy.ndarray

__eq__(value, /)

Return self==value.

__ne__(value, /)

Return self!=value.

__lt__(value, /)

Return self<value.

__le__(value, /)

Return self<=value.

__gt__(value, /)

Return self>value.

__ge__(value, /)

Return self>=value.