numpy.random — Random number generation

The numpy.random submodule provides a Generator class that draws samples from common probability distributions. The underlying algorithm is a permuted-congruential generator (PCG); see https://www.pcg-random.org/ for details.

A Generator is a stateful object: each call to one of its sampling methods advances the internal state, so consecutive calls return independent samples. Output arrays are always of dtype numpy.float.

Classes

class numpy.random.Generator(seed: int | tuple[int, ...] | None = None)

Construct a new pseudo-random number generator.

Parameters:

seed – the seed used to initialise the generator state. If an integer is supplied it is used directly. If a tuple of integers is supplied, a tuple of independently-seeded Generator objects (one per element) is returned instead of a single instance. If None is supplied, a platform-default seed is used (when one is configured at build time); otherwise a ValueError is raised.

Raises:

  • TypeError – if seed is not None, an integer, or a tuple of integers.

  • ValueError – if seed is None and no default seed is configured.

normal(loc: float = 0.0, scale: float = 1.0, size: int | tuple[int, ...] | None = None) → float | ndarray

Draw samples from a normal (Gaussian) distribution.

Parameters:

  • loc – the mean (centre) of the distribution.

  • scale – the standard deviation (width) of the distribution. Must be non-negative.

  • size – the shape of the output. If an integer, a one-dimensional array of that length is returned. If a tuple, an array of that shape is returned. If None (the default), a single Python float is returned.

Returns:

either a Python float or a float numpy.ndarray of the requested shape.

Raises:

  • ValueError – if the requested shape exceeds ULAB_MAX_DIMS.

  • TypeError – if size is neither None, an integer, nor a tuple.

Samples are generated using the Box-Muller transform.

random(size: int | tuple[int, ...] | None = None, *, out: ndarray | None = None) → float | ndarray

Draw samples from the uniform distribution over the half-open interval [0.0, 1.0).

Parameters:

  • size – the shape of the output. If an integer, a one-dimensional array of that length is returned. If a tuple, an array of that shape is returned. If None (the default) and out is also None, a single Python float is returned.

  • out – an optional pre-allocated, dense, float numpy.ndarray to receive the samples. If both size and out are supplied, their shapes must agree.

Returns:

a Python float, a new numpy.ndarray, or out (filled with samples) depending on the arguments.

Raises:

  • TypeError – if size has an unsupported type, or out is not an ndarray, or out is not of dtype float.

  • ValueError – if the requested shape exceeds ULAB_MAX_DIMS, if size and out.shape disagree, or if out is not contiguous.

uniform(low: float = 0.0, high: float = 1.0, size: int | tuple[int, ...] | None = None) → float | ndarray

Draw samples from the uniform distribution over the half-open interval [low, high).

Parameters:

  • low – the lower bound (inclusive) of the distribution.

  • high – the upper bound (exclusive) of the distribution.

  • size – the shape of the output. If a tuple, an array of that shape is returned. If None (the default), a single Python float drawn from [0.0, 1.0) is returned (the low/high bounds are ignored in the scalar case).

Returns:

either a Python float or a float numpy.ndarray of the requested shape.

Raises:

  • ValueError – if the requested shape exceeds ULAB_MAX_DIMS.

  • TypeError – if size is neither None nor a tuple.

With identical default arguments, uniform() produces the same sequence as random().