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, actual_default_rng=<cyfunction default_rng>)

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,

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

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`:

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.

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