# Random Distribution Generator Symbol API¶

## Overview¶

This document lists the random distribution generator routines of the symbolic expression package:

 mxnet.symbol.random Random distribution generator Symbol API of MXNet.

The Random Distribution Generator Symbol API, defined in the symbol.random package, provides symbolic expressions for random distribution generator routines.

In the rest of this document, we list routines provided by the symbol.random package.

## Random Distribution Generator¶

 exponential Draw samples from an exponential distribution. gamma Draw random samples from a gamma distribution. generalized_negative_binomial Draw random samples from a generalized negative binomial distribution. multinomial Concurrent sampling from multiple multinomial distributions. negative_binomial Draw random samples from a negative binomial distribution. normal Draw random samples from a normal (Gaussian) distribution. poisson Draw random samples from a Poisson distribution. randint Draw random samples from a discrete uniform distribution. shuffle Shuffle the elements randomly. uniform Draw random samples from a uniform distribution. mxnet.random.seed Seeds the random number generators in MXNet.

## API Reference¶

Random distribution generator Symbol API of MXNet.

mxnet.symbol.random.uniform(low=0, high=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a uniform distribution.

Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high).

Parameters: low (float or Symbol, 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 Symbol, optional) – Upper boundary of the output interval. All values generated will be less than high. The default value is 1.0. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and low and high are scalars, output shape will be (m, n). If low and high are Symbols with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each [low, high) pair. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n), and low and high are scalars, returned Symbol will resolve to shape (m, n). If low and high are Symbols with shape, e.g., (x, y), returned Symbol will have shape (x, y, m, n), where m*n samples are drawn for each [low, high) pair. Symbol
mxnet.symbol.random.normal(loc=0, scale=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a normal (Gaussian) distribution.

Samples are distributed according to a normal distribution parametrized by loc (mean) and scale (standard deviation).

Parameters: loc (float or Symbol, optional) – Mean (centre) of the distribution. scale (float or Symbol, optional) – Standard deviation (spread or width) of the distribution. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and loc and scale are scalars, output shape will be (m, n). If loc and scale are Symbols with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each [loc, scale) pair. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n), and loc and scale are scalars, returned Symbol will resolve to shape (m, n). If loc and scale are Symbols with shape, e.g., (x, y), returned Symbol will resolve to shape (x, y, m, n), where m*n samples are drawn for each [loc, scale) pair. Symbol
mxnet.symbol.random.poisson(lam=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a Poisson distribution.

Samples are distributed according to a Poisson distribution parametrized by lambda (rate). Samples will always be returned as a floating point data type.

Parameters: lam (float or Symbol, optional) – Expectation of interval, should be >= 0. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and lam is a scalar, output shape will be (m, n). If lam is an Symbol with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each entry in lam. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n), and lam is a scalar, output shape will be (m, n). If lam is an Symbol with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each entry in lam. Symbol
mxnet.symbol.random.exponential(scale=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw samples from an exponential distribution.

Its probability density function is

$f(x; \frac{1}{\beta}) = \frac{1}{\beta} \exp(-\frac{x}{\beta}),$

for x > 0 and 0 elsewhere. beta is the scale parameter, which is the inverse of the rate parameter lambda = 1/beta.

Parameters: scale (float or Symbol, optional) – The scale parameter, beta = 1/lambda. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and scale is a scalar, output shape will be (m, n). If scale is an Symbol with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each entry in scale. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n), and scale is a scalar, returned Symbol will have shape (m, n). If scale is a Symbol with shape, e.g., (x, y), returned Symbol will resolve to shape (x, y, m, n), where m*n samples are drawn for each entry in scale. Symbol
mxnet.symbol.random.gamma(alpha=1, beta=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a gamma distribution.

Samples are distributed according to a gamma distribution parametrized by alpha (shape) and beta (scale).

Parameters: alpha (float or Symbol, optional) – The shape of the gamma distribution. Should be greater than zero. beta (float or Symbol, optional) – The scale of the gamma distribution. Should be greater than zero. Default is equal to 1. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and alpha and beta are scalars, output shape will be (m, n). If alpha and beta are Symbols with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each [alpha, beta) pair. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n) and alpha and beta are scalars, returned Symbol will resolve to shape (m, n). If alpha and beta are Symbols with shape, e.g., (x, y), returned Symbol will resolve to shape (x, y, m, n), where m*n samples are drawn for each [alpha, beta) pair. Symbol
mxnet.symbol.random.negative_binomial(k=1, p=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a negative binomial distribution.

Samples are distributed according to a negative binomial distribution parametrized by k (limit of unsuccessful experiments) and p (failure probability in each experiment). Samples will always be returned as a floating point data type.

Parameters: k (float or Symbol, optional) – Limit of unsuccessful experiments, > 0. p (float or Symbol, optional) – Failure probability in each experiment, >= 0 and <=1. shape (int or tuple of ints) – The number of samples to draw. If shape is, e.g., (m, n) and k and p are scalars, output shape will be (m, n). If k and p are Symbols with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each [k, p) pair. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n), and k and p are scalars, returned Symbol will resolve to shape (m, n). If k and p are Symbols with shape, e.g., (x, y), returned Symbol will resolve to shape (x, y, m, n), where m*n samples are drawn for each [k, p) pair. Symbol
mxnet.symbol.random.generalized_negative_binomial(mu=1, alpha=1, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a generalized negative binomial distribution.

Samples are distributed according to a generalized negative binomial distribution parametrized by mu (mean) and alpha (dispersion). alpha is defined as 1/k where k is the failure limit of the number of unsuccessful experiments (generalized to real numbers). Samples will always be returned as a floating point data type.

Parameters: mu (float or Symbol, optional) – Mean of the negative binomial distribution. alpha (float or Symbol, optional) – Alpha (dispersion) parameter of the negative binomial distribution. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and mu and alpha are scalars, output shape will be (m, n). If mu and alpha are Symbols with shape, e.g., (x, y), then output will have shape (x, y, m, n), where m*n samples are drawn for each [mu, alpha) pair. dtype ({'float16', 'float32', 'float64'}, optional) – Data type of output samples. Default is ‘float32’ If input shape has dimensions, e.g., (m, n), and mu and alpha are scalars, returned Symbol will resolve to shape (m, n). If mu and alpha are Symbols with shape, e.g., (x, y), returned Symbol will resolve to shape (x, y, m, n), where m*n samples are drawn for each [mu, alpha) pair. Symbol
mxnet.symbol.random.multinomial(data, shape=_Null, get_prob=True, dtype='int32', **kwargs)[source]

Concurrent sampling from multiple multinomial distributions.

Note

The input distribution must be normalized, i.e. data must sum to 1 along its last dimension.

Parameters: data (Symbol) – An n dimensional array whose last dimension has length k, where k is the number of possible outcomes of each multinomial distribution. For example, data with shape (m, n, k) specifies m*n multinomial distributions each with k possible outcomes. shape (int or tuple of ints, optional) – The number of samples to draw from each distribution. If shape is empty one sample will be drawn from each distribution. get_prob (bool, optional) – If true, a second array containing log likelihood of the drawn samples will also be returned. This is usually used for reinforcement learning, where you can provide reward as head gradient w.r.t. this array to estimate gradient. dtype (str or numpy.dtype, optional) – Data type of the sample output array. The default is int32. Note that the data type of the log likelihood array is the same with that of data. For input data with n dimensions and shape (d1, d2, ..., dn-1, k), and input shape with shape (s1, s2, ..., sx), returns a Symbol that resovles to shape (d1, d2, ... dn-1, s1, s2, ..., sx). The s1, s2, ... sx dimensions of the returned Symbol’s resolved value will consist of 0-indexed values sampled from each respective multinomial distribution provided in the k dimension of data. For the case n=1, and x=1 (one shape dimension), returned Symbol will resolve to shape (s1,). If get_prob is set to True, this function returns a Symbol that will resolve to a list of outputs: [ndarray_output, log_likelihood_output], where log_likelihood_output will resolve to the same shape as the sampled outputs in ndarray_output. Symbol
mxnet.symbol.random.shuffle(data, **kwargs)[source]

Shuffle the elements randomly.

This shuffles the array along the first axis. The order of the elements in each subarray does not change. For example, if a 2D array is given, the order of the rows randomly changes, but the order of the elements in each row does not change.

Parameters: data (NDArray) – Input data array. A new symbol representing the shuffled version of input data. Symbol

Examples

>>> data = mx.nd.array([[0, 1, 2], [3, 4, 5], [6, 7, 8]])
>>> a = mx.sym.Variable('a')
>>> b = mx.sym.random.shuffle(a)
>>> b.eval(a=data)
[[ 0.  1.  2.]
[ 6.  7.  8.]
[ 3.  4.  5.]]

>>> b.eval(a=data)
[[ 3.  4.  5.]
[ 0.  1.  2.]
[ 6.  7.  8.]]


mxnet.symbol.random.randint(low, high, shape=_Null, dtype=_Null, **kwargs)[source]

Draw random samples from a discrete uniform distribution.

Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high).

Parameters: low (int, required) – Lower boundary of the output interval. All values generated will be greater than or equal to low. high (int, required) – Upper boundary of the output interval. All values generated will be less than high. shape (int or tuple of ints, optional) – The number of samples to draw. If shape is, e.g., (m, n) and low and high are scalars, output shape will be (m, n). dtype ({'int32', 'int64'}, optional) – Data type of output samples. Default is ‘int32’ If input shape has dimensions, e.g., (m, n), and low and high are scalars, returned Symbol will resolve to shape (m, n). Symbol
mxnet.symbol.random.exponential_like(data=None, lam=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from an exponential distribution according to the input array shape.

Samples are distributed according to an exponential distribution parametrized by lambda (rate).

Example:

exponential(lam=4, data=ones(2,2)) = [[ 0.0097189 ,  0.08999364],
[ 0.04146638,  0.31715935]]


Defined in src/operator/random/sample_op.cc:L242

Parameters: lam (float, optional, default=1) – Lambda parameter (rate) of the exponential distribution. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol
mxnet.symbol.random.gamma_like(data=None, alpha=_Null, beta=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from a gamma distribution according to the input array shape.

Samples are distributed according to a gamma distribution parametrized by alpha (shape) and beta (scale).

Example:

gamma(alpha=9, beta=0.5, data=ones(2,2)) = [[ 7.10486984,  3.37695289],
[ 3.91697288,  3.65933681]]


Defined in src/operator/random/sample_op.cc:L231

Parameters: alpha (float, optional, default=1) – Alpha parameter (shape) of the gamma distribution. beta (float, optional, default=1) – Beta parameter (scale) of the gamma distribution. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol
mxnet.symbol.random.generalized_negative_binomial_like(data=None, mu=_Null, alpha=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from a generalized negative binomial distribution according to the input array shape.

Samples are distributed according to a generalized negative binomial distribution parametrized by mu (mean) and alpha (dispersion). alpha is defined as 1/k where k is the failure limit of the number of unsuccessful experiments (generalized to real numbers). Samples will always be returned as a floating point data type.

Example:

generalized_negative_binomial(mu=2.0, alpha=0.3, data=ones(2,2)) = [[ 2.,  1.],
[ 6.,  4.]]


Defined in src/operator/random/sample_op.cc:L283

Parameters: mu (float, optional, default=1) – Mean of the negative binomial distribution. alpha (float, optional, default=1) – Alpha (dispersion) parameter of the negative binomial distribution. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol
mxnet.symbol.random.negative_binomial_like(data=None, k=_Null, p=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from a negative binomial distribution according to the input array shape.

Samples are distributed according to a negative binomial distribution parametrized by k (limit of unsuccessful experiments) and p (failure probability in each experiment). Samples will always be returned as a floating point data type.

Example:

negative_binomial(k=3, p=0.4, data=ones(2,2)) = [[ 4.,  7.],
[ 2.,  5.]]


Defined in src/operator/random/sample_op.cc:L267

Parameters: k (int, optional, default='1') – Limit of unsuccessful experiments. p (float, optional, default=1) – Failure probability in each experiment. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol
mxnet.symbol.random.normal_like(data=None, loc=_Null, scale=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from a normal (Gaussian) distribution according to the input array shape.

Samples are distributed according to a normal distribution parametrized by loc (mean) and scale (standard deviation).

Example:

normal(loc=0, scale=1, data=ones(2,2)) = [[ 1.89171135, -1.16881478],
[-1.23474145,  1.55807114]]


Defined in src/operator/random/sample_op.cc:L220

Parameters: loc (float, optional, default=0) – Mean of the distribution. scale (float, optional, default=1) – Standard deviation of the distribution. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol
mxnet.symbol.random.poisson_like(data=None, lam=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from a Poisson distribution according to the input array shape.

Samples are distributed according to a Poisson distribution parametrized by lambda (rate). Samples will always be returned as a floating point data type.

Example:

poisson(lam=4, data=ones(2,2)) = [[ 5.,  2.],
[ 4.,  6.]]


Defined in src/operator/random/sample_op.cc:L254

Parameters: lam (float, optional, default=1) – Lambda parameter (rate) of the Poisson distribution. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol
mxnet.symbol.random.uniform_like(data=None, low=_Null, high=_Null, name=None, attr=None, out=None, **kwargs)

Draw random samples from a uniform distribution according to the input array shape.

Samples are uniformly distributed over the half-open interval [low, high) (includes low, but excludes high).

Example:

uniform(low=0, high=1, data=ones(2,2)) = [[ 0.60276335,  0.85794562],
[ 0.54488319,  0.84725171]]


Defined in src/operator/random/sample_op.cc:L208

Parameters: low (float, optional, default=0) – Lower bound of the distribution. high (float, optional, default=1) – Upper bound of the distribution. data (Symbol) – The input name (string, optional.) – Name of the resulting symbol. The result symbol. Symbol

Random number interface of MXNet.

mxnet.random.seed(seed_state, ctx='all')[source]

Seeds the random number generators in MXNet.

This affects the behavior of modules in MXNet that uses random number generators, like the dropout operator and NDArray‘s random sampling operators.

Parameters: seed_state (int) – The random number seed. ctx (Context) – The device context of the generator. The default is “all” which means seeding random number generators of all devices.

Notes

Random number generators in MXNet are device specific. mx.random.seed(seed_state) sets the state of each generator using seed_state and the device id. Therefore, random numbers generated from different devices can be different even if they are seeded using the same seed.

To produce identical random number sequences independent of the device id, set optional ctx argument. This produces the same sequence of random numbers independent of the device id, but the sequence can be different on different kind of devices as MXNet’s random number generators for CPU and GPU use different algorithms.

Example

>>> print(mx.nd.random.normal(shape=(2,2)).asnumpy())
[[ 1.36481571 -0.62203991]
[-1.4962182  -0.08511394]]
>>> print(mx.nd.random.normal(shape=(2,2)).asnumpy())
[[ 1.09544981 -0.20014545]
[-0.20808885  0.2527658 ]]
# Same results on the same device with the same seed
>>> mx.random.seed(128)
>>> print(mx.nd.random.normal(shape=(2,2)).asnumpy())
[[ 0.47400656 -0.75213492]
[ 0.20251541  0.95352972]]
>>> mx.random.seed(128)
>>> print(mx.nd.random.normal(shape=(2,2)).asnumpy())
[[ 0.47400656 -0.75213492]
[ 0.20251541  0.95352972]]
# Different results on gpu(0) and gpu(1) with the same seed
>>> mx.random.seed(128)
>>> print(mx.nd.random.normal(shape=(2,2), ctx=mx.gpu(0)).asnumpy())
[[ 2.5020072 -1.6884501]
[-0.7931333 -1.4218881]]
>>> mx.random.seed(128)
>>> print(mx.nd.random.normal(shape=(2,2), ctx=mx.gpu(1)).asnumpy())
[[ 0.24336822 -1.664805  ]
[-1.0223296   1.253198  ]]
# Seeding with ctx argument produces identical results on gpu(0) and gpu(1)
>>> mx.random.seed(128, ctx=mx.gpu(0))
>>> print(mx.nd.random.normal(shape=(2,2), ctx=mx.gpu(0)).asnumpy())
[[ 2.5020072 -1.6884501]
[-0.7931333 -1.4218881]]
>>> mx.random.seed(128, ctx=mx.gpu(1))
>>> print(mx.nd.random.normal(shape=(2,2), ctx=mx.gpu(1)).asnumpy())
[[ 2.5020072 -1.6884501]
[-0.7931333 -1.4218881]]