Random Sampling (cupy.random)

CuPy’s random number generation routines are based on cuRAND. They cover a small fraction of numpy.random.

The big difference of cupy.random from numpy.random is that cupy.random supports dtype option for most functions. This option enables us to generate float32 values directly without any space overhead.

Sample random data

cupy.random.choice(a, size=None, replace=True, p=None)[source]

Returns an array of random values from a given 1-D array.

Each element of the returned array is independently sampled from a according to p or uniformly.

Parameters:
  • a (1-D array-like or int) – If an array-like, a random sample is generated from its elements. If an int, the random sample is generated as if a was cupy.arange(n)
  • size (int or tuple of ints) – The shape of the array.
  • replace (boolean) – Whether the sample is with or without replacement
  • p (1-D array-like) – The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a.
Returns:

An array of a values distributed according to

p or uniformly.

Return type:

cupy.ndarray

cupy.random.rand(*size, **kwarg)[source]

Returns an array of uniform random values over the interval [0, 1).

Each element of the array is uniformly distributed on the half-open interval [0, 1). All elements are identically and independently distributed (i.i.d.).

Parameters:
  • size (tuple of ints) – The shape of the array.
  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed. The default is numpy.float64.
Returns:

A random array.

Return type:

cupy.ndarray

cupy.random.randn(*size, **kwarg)[source]

Returns an array of standard normal random values.

Each element of the array is normally distributed with zero mean and unit variance. All elements are identically and independently distributed (i.i.d.).

Parameters:
  • size (tuple of ints) – The shape of the array.
  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed. The default is numpy.float64.
Returns:

An array of standard normal random values.

Return type:

cupy.ndarray

cupy.random.randint(low, high=None, size=None)[source]

Returns a scalar or an array of integer values over [low, high).

Each element of returned values are independently sampled from uniform distribution over left-close and right-open interval [low, high).

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

cupy.random.random_integers(low, high=None, size=None)[source]

Return a scalar or an array of integer values over [low, high]

Each element of returned values are independently sampled from uniform distribution over closed interval [low, high].

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 the lower bound is set to 1.
  • high (int) – Upper bound of the interval.
  • size (None or int or tuple of ints) – The shape of returned value.
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

cupy.random.random_sample(size=None, dtype=<type 'float'>)[source]

Returns an array of random values over the interval [0, 1).

This is a variant of cupy.random.rand().

Parameters:
  • size (int or tuple of ints) – The shape of the array.
  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed.
Returns:

An array of uniformly distributed random values.

Return type:

cupy.ndarray

cupy.random.random(size=None, dtype=<type 'float'>)

Returns an array of random values over the interval [0, 1).

This is a variant of cupy.random.rand().

Parameters:
  • size (int or tuple of ints) – The shape of the array.
  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed.
Returns:

An array of uniformly distributed random values.

Return type:

cupy.ndarray

cupy.random.ranf(size=None, dtype=<type 'float'>)

Returns an array of random values over the interval [0, 1).

This is a variant of cupy.random.rand().

Parameters:
  • size (int or tuple of ints) – The shape of the array.
  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed.
Returns:

An array of uniformly distributed random values.

Return type:

cupy.ndarray

cupy.random.sample(size=None, dtype=<type 'float'>)

Returns an array of random values over the interval [0, 1).

This is a variant of cupy.random.rand().

Parameters:
  • size (int or tuple of ints) – The shape of the array.
  • dtype – Data type specifier. Only numpy.float32 and numpy.float64 types are allowed.
Returns:

An array of uniformly distributed random values.

Return type:

cupy.ndarray

Distributions

cupy.random.gumbel(loc=0.0, scale=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of samples drawn from a Gumbel distribution.

The samples are drawn from a Gumbel distribution with location loc and scale scale. Its probability density function is defined as

\[f(x) = \frac{1}{\eta} \exp\left\{ - \frac{x - \mu}{\eta} \right\} \exp\left[-\exp\left\{-\frac{x - \mu}{\eta} \right\}\right],\]

where \(\mu\) is loc and \(\eta\) is scale.

Parameters:
  • loc (float) – The location of the mode \(\mu\).
  • scale (float) – The scale parameter \(\eta\).
  • 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 Gumbel destribution.

Return type:

cupy.ndarray

cupy.random.lognormal(mean=0.0, sigma=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of samples drawn from a log normal distribution.

The samples are natural log of samples drawn from a normal distribution with mean mean and deviation sigma.

Parameters:
  • mean (float) – Mean of the normal distribution.
  • sigma (float) – Standard deviation of the normal distribution.
  • 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 log normal distribution.

Return type:

cupy.ndarray

cupy.random.normal(loc=0.0, scale=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of normally distributed samples.

Parameters:
  • loc (float or array_like of floats) – Mean of the normal distribution.
  • scale (float or array_like of floats) – Standard deviation of the normal distribution.
  • 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:

Normally distributed samples.

Return type:

cupy.ndarray

cupy.random.standard_normal(size=None, dtype=<type 'float'>)[source]

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

This is a variant of cupy.random.randn().

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

Samples drawn from the standard normal distribution.

Return type:

cupy.ndarray

cupy.random.uniform(low=0.0, high=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of uniformly-distributed samples over an interval.

Samples are drawn from a uniform distribution over the half-open interval [low, high).

Parameters:
  • low (float) – Lower end of the interval.
  • high (float) – Upper end of the interval.
  • size (int or tuple of ints) – The shape of the array. If None, a zero-dimensional array is generated.
  • dtype – Data type specifier.
Returns:

Samples drawn from the uniform distribution.

Return type:

cupy.ndarray

Random number generator

cupy.random.seed(seed=None)[source]

Resets the state of the random number generator with a seed.

This function resets the state of the global random number generator for the current device. Be careful that generators for other devices are not affected.

Parameters:seed (None or int) – Seed for the random number generator. If None, it uses os.urandom() if available or time.clock() otherwise. Note that this function does not support seeding by an integer array.
cupy.random.get_random_state()[source]

Gets the state of the random number generator for the current device.

If the state for the current device is not created yet, this function creates a new one, initializes it, and stores it as the state for the current device.

Returns:The state of the random number generator for the device.
Return type:RandomState
class cupy.random.RandomState(seed=None, method=100)[source]

Portable container of a pseudo-random number generator.

An instance of this class holds the state of a random number generator. The state is available only on the device which has been current at the initialization of the instance.

Functions of cupy.random use global instances of this class. Different instances are used for different devices. The global state for the current device can be obtained by the cupy.random.get_random_state() function.

Parameters:
  • seed (None or int) – Seed of the random number generator. See the seed() method for detail.
  • method (int) –

    Method of the random number generator. Following values are available:

    cupy.cuda.curand.CURAND_RNG_PSEUDO_DEFAULT
    cupy.cuda.curand.CURAND_RNG_XORWOW
    cupy.cuda.curand.CURAND_RNG_MRG32K3A
    cupy.cuda.curand.CURAND_RNG_MTGP32
    cupy.cuda.curand.CURAND_RNG_MT19937
    cupy.cuda.curand.CURAND_RNG_PHILOX4_32_10
    
choice(a, size=None, replace=True, p=None)[source]

Returns an array of random values from a given 1-D array.

See also

cupy.random.choice() for full document, numpy.random.choice()

interval(mx, size)[source]

Generate multiple integers independently sampled uniformly from [0, mx].

Parameters:
  • mx (int) – Upper bound of the interval
  • size (None or int or tuple) – Shape of the array or the scalar returned.
Returns:

If None, an cupy.ndarray with shape () is returned. If int, 1-D array of length size is returned. If tuple, multi-dimensional array with shape size is returned. Currently, each element of the array is numpy.int32.

Return type:

int or cupy.ndarray

lognormal(mean=0.0, sigma=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of samples drawn from a log normal distribution.

normal(loc=0.0, scale=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of normally distributed samples.

See also

cupy.random.normal() for full documentation, numpy.random.RandomState.normal()

rand(*size, **kwarg)[source]

Returns uniform random values over the interval [0, 1).

See also

cupy.random.rand() for full documentation, numpy.random.RandomState.rand()

randn(*size, **kwarg)[source]

Returns an array of standard normal random values.

See also

cupy.random.randn() for full documentation, numpy.random.RandomState.randn()

random_sample(size=None, dtype=<type 'float'>)[source]

Returns an array of random values over the interval [0, 1).

seed(seed=None)[source]

Resets the state of the random number generator with a seed.

See also

cupy.random.seed() for full documentation, numpy.random.RandomState.seed()

standard_normal(size=None, dtype=<type 'float'>)[source]

Returns samples drawn from the standard normal distribution.

uniform(low=0.0, high=1.0, size=None, dtype=<type 'float'>)[source]

Returns an array of uniformly-distributed samples over an interval.