cupy.random.Generator#

class cupy.random.Generator(bit_generator)[source]#

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

uniform(self, low=0.0, high=1.0, size=None, dtype=numpy.float64)#

Draw samples from a uniform distribution. Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high). In other words, any value within the given interval is equally likely to be drawn by uniform.

Parameters:
  • low (float or array_like of floats, optional) – Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0.

  • high (float or array_like of floats) – Upper boundary of the output interval. All values generated will be less than high. The high limit may be included in the returned array of floats due to floating-point rounding in the equation low + (high-low) * random(). high - low must be non-negative. The default value is 1.0.

  • size (int or tuple of ints, optional) – Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn. If size is None (default), a single value is returned if low and high are both scalars. Otherwise, cupy.broadcast(low, high).size samples are drawn.

Returns:

out – Drawn samples from the parameterized uniform distribution.

Return type:

ndarray or scalar

See also

-

meth:numpy.random.Generator.uniform

-

meth:integers: Discrete uniform distribution, yielding integers.

-

meth:random: Floats uniformly distributed over [0, 1).

__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.