Skip to main content
`Ctrl`+`K`

# Random `Generator`

The `Generator` provides access to a wide range of distributions, and served as a replacement for `RandomState`. The main difference between the two is that `Generator` relies on an additional BitGenerator to manage state and generate the random bits, which are then transformed into random values from useful distributions. The default BitGenerator used by `Generator` is `PCG64`. The BitGenerator can be changed by passing an instantized BitGenerator to `Generator`.

numpy.random.default_rng(seed=None)

  Construct a new Generator with the default BitGenerator (PCG64).

  Parameters:
    seed{None, int, array_like[ints], SeedSequence, BitGenerator, Generator, RandomState}, optional

      A seed to initialize the `BitGenerator`. If None, then fresh, unpredictable entropy will be pulled from the OS. If an `int` or `array_like[ints]` is passed, then all values must be non-negative and will be passed to `SeedSequence` to derive the initial `BitGenerator` state. One may also pass in a `SeedSequence` instance. Additionally, when passed a `BitGenerator`, it will be wrapped by `Generator`. If passed a `Generator`, it will be returned unaltered. When passed a legacy `RandomState` instance it will be coerced to a `Generator`.

  Returns:
    Generator

      The initialized generator object.

  Notes

  If `seed` is not a `BitGenerator` or a `Generator`, a new `BitGenerator` is instantiated. This function does not manage a default global instance.

  See Seeding and entropy for more information about seeding.

  Examples

  `default_rng` is the recommended constructor for the random number class `Generator`. Here are several ways we can construct a random number generator using `default_rng` and the `Generator` class.

  Here we use `default_rng` to generate a random float:

      >>> import numpy as np
      >>> rng = np.random.default_rng(12345)
      >>> print(rng)
      Generator(PCG64)
      >>> rfloat = rng.random()
      >>> rfloat
      0.22733602246716966
      >>> type(rfloat)
      <class 'float'>

  Here we use `default_rng` to generate 3 random integers between 0 (inclusive) and 10 (exclusive):

      >>> import numpy as np
      >>> rng = np.random.default_rng(12345)
      >>> rints = rng.integers(low=0, high=10, size=3)
      >>> rints
      array([6, 2, 7])
      >>> type(rints[0])
      <class 'numpy.int64'>

  Here we specify a seed so that we have reproducible results:

      >>> import numpy as np
      >>> rng = np.random.default_rng(seed=42)
      >>> print(rng)
      Generator(PCG64)
      >>> arr1 = rng.random((3, 3))
      >>> arr1
      array([[0.77395605, 0.43887844, 0.85859792],
             [0.69736803, 0.09417735, 0.97562235],
             [0.7611397 , 0.78606431, 0.12811363]])

  If we exit and restart our Python interpreter, we’ll see that we generate the same random numbers again:

      >>> import numpy as np
      >>> rng = np.random.default_rng(seed=42)
      >>> arr2 = rng.random((3, 3))
      >>> arr2
      array([[0.77395605, 0.43887844, 0.85859792],
             [0.69736803, 0.09417735, 0.97562235],
             [0.7611397 , 0.78606431, 0.12811363]])

class numpy.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 BitGenerator

      BitGenerator to use as the core generator.

  See also

  `default_rng`

    Recommended constructor for `Generator`.

  Notes

  The Python stdlib module `random` contains pseudo-random number generator with a number of methods that are similar to the ones available in `Generator`. It uses Mersenne Twister, and this bit generator can be accessed using `MT19937`. `Generator`, besides being NumPy-aware, has the advantage that it provides a much larger number of probability distributions to choose from.

  Examples

      >>> from numpy.random import Generator, PCG64
      >>> rng = Generator(PCG64())
      >>> rng.standard_normal()
      -0.203  # random

## Accessing the BitGenerator and spawning

`bit_generator` | Gets the bit generator instance used by the generator
`spawn`(n_children) | Create new independent child generators.

## Simple random data

`integers`(low[, high, size, dtype, endpoint]) | Return random integers from low (inclusive) to high (exclusive), or if endpoint=True, low (inclusive) to high (inclusive).
`random`([size, dtype, out]) | Return random floats in the half-open interval [0.0, 1.0).
`choice`(a[, size, replace, p, axis, shuffle]) | Generates a random sample from a given array
`bytes`(length) | Return random bytes.

## Permutations

The methods for randomly permuting a sequence are

`shuffle`(x[, axis]) | Modify an array or sequence in-place by shuffling its contents.
`permutation`(x[, axis]) | Randomly permute a sequence, or return a permuted range.
`permuted`(x[, axis, out]) | Randomly permute x along axis axis.

The following table summarizes the behaviors of the methods.

method | copy/in-place | axis handling
--- | --- | ---
shuffle | in-place | as if 1d
permutation | copy | as if 1d
permuted | either (use ‘out’ for in-place) | axis independent

The following subsections provide more details about the differences.

### In-place vs. copy

The main difference between `Generator.shuffle` and `Generator.permutation` is that `Generator.shuffle` operates in-place, while `Generator.permutation` returns a copy.

By default, `Generator.permuted` returns a copy. To operate in-place with `Generator.permuted`, pass the same array as the first argument and as the value of the `out` parameter. For example,

    >>> import numpy as np
    >>> rng = np.random.default_rng()
    >>> x = np.arange(0, 15).reshape(3, 5)
    >>> x
    array([[ 0,  1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, 13, 14]])
    >>> y = rng.permuted(x, axis=1, out=x)
    >>> x
    array([[ 1,  0,  2,  4,  3],  # random
           [ 6,  7,  8,  9,  5],
           [10, 14, 11, 13, 12]])

Note that when `out` is given, the return value is `out`:

    >>> y is x
    True

### Handling the `axis` parameter

An important distinction for these methods is how they handle the `axis` parameter. Both `Generator.shuffle` and `Generator.permutation` treat the input as a one-dimensional sequence, and the `axis` parameter determines which dimension of the input array to use as the sequence. In the case of a two-dimensional array, `axis=0` will, in effect, rearrange the rows of the array, and `axis=1` will rearrange the columns. For example

    >>> import numpy as np
    >>> rng = np.random.default_rng()
    >>> x = np.arange(0, 15).reshape(3, 5)
    >>> x
    array([[ 0,  1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, 13, 14]])
    >>> rng.permutation(x, axis=1)
    array([[ 1,  3,  2,  0,  4],  # random
           [ 6,  8,  7,  5,  9],
           [11, 13, 12, 10, 14]])

Note that the columns have been rearranged “in bulk”: the values within each column have not changed.

The method `Generator.permuted` treats the `axis` parameter similar to how `numpy.sort` treats it. Each slice along the given axis is shuffled independently of the others. Compare the following example of the use of `Generator.permuted` to the above example of `Generator.permutation`:

    >>> import numpy as np
    >>> rng = np.random.default_rng()
    >>> rng.permuted(x, axis=1)
    array([[ 1,  0,  2,  4,  3],  # random
           [ 5,  7,  6,  9,  8],
           [10, 14, 12, 13, 11]])

In this example, the values within each row (i.e. the values along `axis=1`) have been shuffled independently. This is not a “bulk” shuffle of the columns.

### Shuffling non-NumPy sequences

`Generator.shuffle` works on non-NumPy sequences. That is, if it is given a sequence that is not a NumPy array, it shuffles that sequence in-place.

    >>> import numpy as np
    >>> rng = np.random.default_rng()
    >>> a = ['A', 'B', 'C', 'D', 'E']
    >>> rng.shuffle(a)  # shuffle the list in-place
    >>> a
    ['B', 'D', 'A', 'E', 'C']  # random

## Distributions

`beta`(a, b[, size]) | Draw samples from a Beta distribution.
`binomial`(n, p[, size]) | Draw samples from a binomial distribution.
`chisquare`(df[, size]) | Draw samples from a chi-square distribution.
`dirichlet`(alpha[, size]) | Draw samples from the Dirichlet distribution.
`exponential`([scale, size]) | Draw samples from an exponential distribution.
`f`(dfnum, dfden[, size]) | Draw samples from an F distribution.
`gamma`(shape[, scale, size]) | Draw samples from a Gamma distribution.
`geometric`(p[, size]) | Draw samples from the geometric distribution.
`gumbel`([loc, scale, size]) | Draw samples from a Gumbel distribution.
`hypergeometric`(ngood, nbad, nsample[, size]) | Draw samples from a Hypergeometric distribution.
`laplace`([loc, scale, size]) | Draw samples from the Laplace or double exponential distribution with specified location (or mean) and scale (decay).
`logistic`([loc, scale, size]) | Draw samples from a logistic distribution.
`lognormal`([mean, sigma, size]) | Draw samples from a log-normal distribution.
`logseries`(p[, size]) | Draw samples from a logarithmic series distribution.
`multinomial`(n, pvals[, size]) | Draw samples from a multinomial distribution.
`multivariate_hypergeometric`(colors, nsample) | Generate variates from a multivariate hypergeometric distribution.
`multivariate_normal`(mean, cov[, size, ...]) | Draw random samples from a multivariate normal distribution.
`negative_binomial`(n, p[, size]) | Draw samples from a negative binomial distribution.
`noncentral_chisquare`(df, nonc[, size]) | Draw samples from a noncentral chi-square distribution.
`noncentral_f`(dfnum, dfden, nonc[, size]) | Draw samples from the noncentral F distribution.
`normal`([loc, scale, size]) | Draw random samples from a normal (Gaussian) distribution.
`pareto`(a[, size]) | Draw samples from a Pareto II (AKA Lomax) distribution with specified shape.
`poisson`([lam, size]) | Draw samples from a Poisson distribution.
`power`(a[, size]) | Draws samples in [0, 1] from a power distribution with positive exponent a - 1.
`rayleigh`([scale, size]) | Draw samples from a Rayleigh distribution.
`standard_cauchy`([size]) | Draw samples from a standard Cauchy distribution with mode = 0.
`standard_exponential`([size, dtype, method, out]) | Draw samples from the standard exponential distribution.
`standard_gamma`(shape[, size, dtype, out]) | Draw samples from a standard Gamma distribution.
`standard_normal`([size, dtype, out]) | Draw samples from a standard Normal distribution (mean=0, stdev=1).
`standard_t`(df[, size]) | Draw samples from a standard Student's t distribution with df degrees of freedom.
`triangular`(left, mode, right[, size]) | Draw samples from the triangular distribution over the interval `[left, right]`.
`uniform`([low, high, size]) | Draw samples from a uniform distribution.
`vonmises`(mu, kappa[, size]) | Draw samples from a von Mises distribution.
`wald`(mean, scale[, size]) | Draw samples from a Wald, or inverse Gaussian, distribution.
`weibull`(a[, size]) | Draw samples from a Weibull distribution.
`zipf`(a[, size]) | Draw samples from a Zipf distribution.