| # Licensed to the Apache Software Foundation (ASF) under one |
| # or more contributor license agreements. See the NOTICE file |
| # distributed with this work for additional information |
| # regarding copyright ownership. The ASF licenses this file |
| # to you under the Apache License, Version 2.0 (the |
| # "License"); you may not use this file except in compliance |
| # with the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, |
| # software distributed under the License is distributed on an |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| # KIND, either express or implied. See the License for the |
| # specific language governing permissions and limitations |
| # under the License. |
| |
| """Random distribution generator Symbol API of MXNet.""" |
| |
| from ..base import numeric_types, _Null |
| from . import _internal |
| from .symbol import Symbol |
| |
| |
| __all__ = ['uniform', 'normal', 'randn', 'poisson', 'exponential', 'gamma', 'categorical', 'multinomial', |
| 'binomial', 'negative_binomial', 'generalized_negative_binomial', 'shuffle', 'randint'] |
| |
| |
| def _random_helper(random, sampler, params, shape, dtype, kwargs): |
| """Helper function for random generators.""" |
| if isinstance(params[0], Symbol): |
| for i in params[1:]: |
| assert isinstance(i, Symbol), \ |
| "Distribution parameters must all have the same type, but got " \ |
| f"both {type(params[0])} and {type(i)}." |
| return sampler(*params, shape=shape, dtype=dtype, **kwargs) |
| elif isinstance(params[0], numeric_types): |
| for i in params[1:]: |
| assert isinstance(i, numeric_types), \ |
| "Distribution parameters must all have the same type, but got " \ |
| f"both {type(params[0])} and {type(i)}." |
| return random(*params, shape=shape, dtype=dtype, **kwargs) |
| |
| raise ValueError("Distribution parameters must be either Symbol or numbers, " |
| f"but got {type(params[0])}.") |
| |
| |
| def uniform(low=0, high=1, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| 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. |
| """ |
| return _random_helper(_internal._random_uniform, _internal._sample_uniform, |
| [low, high], shape, dtype, kwargs) |
| |
| |
| def normal(loc=0, scale=1, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| 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. |
| """ |
| return _random_helper(_internal._random_normal, _internal._sample_normal, |
| [loc, scale], shape, dtype, kwargs) |
| |
| |
| def randn(*shape, **kwargs): |
| """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 |
| 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 NDArrays 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' |
| """ |
| loc = kwargs.pop('loc', 0) |
| scale = kwargs.pop('scale', 1) |
| dtype = kwargs.pop('dtype', _Null) |
| assert isinstance(loc, (int, float, Symbol)) |
| assert isinstance(scale, (int, float, Symbol)) |
| return _random_helper(_internal._random_normal, _internal._sample_normal, |
| [loc, scale], shape, dtype, kwargs) |
| |
| |
| def poisson(lam=1, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| 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`. |
| """ |
| return _random_helper(_internal._random_poisson, _internal._sample_poisson, |
| [lam], shape, dtype, kwargs) |
| |
| |
| def exponential(scale=1, shape=_Null, dtype=_Null, **kwargs): |
| r"""Draw samples from an exponential distribution. |
| |
| Its probability density function is |
| |
| .. math:: 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' |
| |
| Returns |
| ------- |
| Symbol |
| 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`. |
| """ |
| return _random_helper(_internal._random_exponential, _internal._sample_exponential, |
| [1.0/scale], shape, dtype, kwargs) |
| |
| |
| def gamma(alpha=1, beta=1, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| 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. |
| """ |
| return _random_helper(_internal._random_gamma, _internal._sample_gamma, |
| [alpha, beta], shape, dtype, kwargs) |
| |
| |
| def binomial(n=1, p=0.5, shape=_Null, dtype=_Null, **kwargs): |
| """Draw random samples from a binomial distribution. |
| |
| Samples are distributed according to a binomial distribution parametrized |
| by *n* (number of trials) and *p* (success probability). |
| |
| Parameters |
| ---------- |
| n : float or Symbol, optional |
| Number of experiments, > 0. |
| p : float or Symbol, optional |
| Success probability in each experiment, >= 0 and <= 1. |
| shape : int or tuple of ints, optional |
| The number of samples to draw. If shape is, e.g., `(m, n)` and `n` and |
| `p` are scalars, output shape will be `(m, n)`. If `n` and `p` |
| are NDArrays with shape, e.g., `(x, y)`, then output will have shape |
| `(x, y, m, n)`, where `m*n` samples are drawn for each `[n, p)` pair. |
| dtype : {'float16', 'float32', 'float64'}, optional |
| Data type of output samples. Default is 'float32' |
| |
| Returns |
| ------- |
| Symbol |
| If input `shape` has shape, e.g., `(m, n)` and `n` and `p` are scalars, output |
| shape will be `(m, n)`. If `n` and `p` are NDArrays with shape, e.g., |
| `(x, y)`, then output will have shape `(x, y, m, n)`, where `m*n` samples are |
| drawn for each `[n, p)` pair. |
| """ |
| return _random_helper(_internal._random_binomial, _internal._sample_binomial, |
| [n, p], shape, dtype, kwargs) |
| |
| |
| def negative_binomial(k=1, p=1, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| 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. |
| """ |
| return _random_helper(_internal._random_negative_binomial, |
| _internal._sample_negative_binomial, |
| [k, p], shape, dtype, kwargs) |
| |
| |
| def generalized_negative_binomial(mu=1, alpha=1, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| 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. |
| """ |
| return _random_helper(_internal._random_generalized_negative_binomial, |
| _internal._sample_generalized_negative_binomial, |
| [mu, alpha], shape, dtype, kwargs) |
| |
| |
| def categorical(data, shape=_Null, get_prob=True, dtype='int32', **kwargs): |
| """Concurrent sampling from multiple categorical 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 categorical distribution. |
| For example, data with shape `(m, n, k)` specifies `m*n` categorical |
| 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`. |
| |
| Returns |
| ------- |
| Symbol |
| 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 categorical 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. |
| """ |
| return _internal._sample_categorical(data, shape, get_prob, dtype=dtype, **kwargs) |
| |
| |
| def multinomial(n=[1], p=[[1.0]], shape=_Null, dtype='float32', **kwargs): |
| """Concurrent sampling from multiple multinomial distributions. |
| |
| .. note:: The input distribution must be normalized, i.e. `p` must sum to |
| 1 along its last dimension. |
| |
| Parameters |
| ---------- |
| n : Symbol |
| An *n* dimensional array containing the number of trials of each |
| multinomial distribution. |
| p : Symbol |
| An *n+1* dimensional array containing the probabilities of each multinomial |
| distribution. Its last dimension has length `k`, where `k` is the number |
| of possible outcomes of each multinomial distribution. |
| For example, p 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. |
| dtype : {'float16', 'float32', 'float64'}, optional |
| Data type of output samples. Default is 'float32' |
| |
| Returns |
| ------- |
| Symbol |
| If input `shape` has shape, e.g., `(m, n)` and `n` and `p` are a scalar and an array of length k |
| respectively, output shape will be `(m, n, k)`. If `n` and `p` are NDArrays with shape, e.g., |
| `(x, y)` and `(x, y, k)`, then output will have shape `(x, y, m, n, k)`, where `m*n` |
| samples are drawn for each `[n, p)` pair. |
| """ |
| return _internal._sample_multinomial(n, p, shape, dtype=dtype, **kwargs) |
| |
| |
| def shuffle(data, **kwargs): |
| """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. |
| |
| Returns |
| ------- |
| Symbol |
| A new symbol representing the shuffled version of input `data`. |
| |
| 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.]] |
| <NDArray 2x3 @cpu(0)> |
| >>> b.eval(a=data) |
| [[ 3. 4. 5.] |
| [ 0. 1. 2.] |
| [ 6. 7. 8.]] |
| <NDArray 2x3 @cpu(0)> |
| """ |
| return _internal._shuffle(data, **kwargs) |
| |
| |
| def randint(low, high, shape=_Null, dtype=_Null, **kwargs): |
| """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' |
| |
| Returns |
| ------- |
| Symbol |
| If input `shape` has dimensions, e.g., `(m, n)`, and `low` and |
| `high` are scalars, returned Symbol will resolve to shape `(m, n)`. |
| """ |
| return _random_helper(_internal._random_randint, None, |
| [low, high], shape, dtype, kwargs) |
