# Random numbers¶

class RandomDistribution(distribution, parameters_pos=None, rng=None, **parameters_named)[source]

Class which defines a next(n) method which returns an array of n random numbers from a given distribution.

Arguments:
distribution:

the name of a random number distribution.

parameters_pos:

parameters of the distribution, provided as a tuple. For the correct ordering, see random.available_distributions.

rng:

if present, should be a `NumpyRNG`, `GSLRNG` or `NativeRNG` object.

parameters_named:

parameters of the distribution, provided as keyword arguments.

Parameters may be provided either through parameters_pos or through parameters_named, but not both. All parameters must be provided, there are no default values. Parameter names are, in general, as used in Wikipedia.

Examples:

```>>> rd = RandomDistribution('uniform', (-70, -50))
>>> rd = RandomDistribution('normal', mu=0.5, sigma=0.1)
>>> rng = NumpyRNG(seed=8658764)
>>> rd = RandomDistribution('gamma', k=2.0, theta=5.0, rng=rng)
```

Available distributions:

 Name Parameters Comments binomial n, p gamma k, theta exponential beta lognormal mu, sigma normal mu, sigma normal_clipped mu, sigma, low, high Values outside (low, high) are redrawn normal_clipped_to_boundary mu, sigma, low, high Values outside low/high are set to low/high poisson lambda_ Underscore since lambda is a Python keyword uniform low, high uniform_int low, high vonmises mu, kappa

Return n random numbers from the distribution.

Generate an array of random numbers of the requested shape.

If a mask is given, produce only enough numbers to fill the region defined by the mask (hence ‘lazily’).

This method is called by the lazyarray evaluate() and _partially_evaluate() methods.

class NumpyRNG(seed=None, parallel_safe=True)[source]

Bases: `WrappedRNG`

Wrapper for the `np.random.RandomState` class (Mersenne Twister PRNG).

translations = {'binomial': ('binomial', {'n': 'n', 'p': 'p'}), 'exponential': ('exponential', {'beta': 'scale'}), 'gamma': ('gamma', {'k': 'shape', 'theta': 'scale'}), 'lognormal': ('lognormal', {'mu': 'mean', 'sigma': 'sigma'}), 'normal': ('normal', {'mu': 'loc', 'sigma': 'scale'}), 'normal_clipped': ('normal_clipped', {'mu': 'mu', 'sigma': 'sigma', 'low': 'low', 'high': 'high'}), 'normal_clipped_to_boundary': ('normal_clipped_to_boundary', {'mu': 'mu', 'sigma': 'sigma', 'low': 'low', 'high': 'high'}), 'poisson': ('poisson', {'lambda_': 'lam'}), 'uniform': ('uniform', {'low': 'low', 'high': 'high'}), 'uniform_int': ('randint', {'low': 'low', 'high': 'high'}), 'vonmises': ('vonmises', {'mu': 'mu', 'kappa': 'kappa'})}
normal_clipped(mu=0.0, sigma=1.0, low=-inf, high=inf, size=None)[source]
normal_clipped_to_boundary(mu=0.0, sigma=1.0, low=-inf, high=inf, size=None)[source]
describe()

Return n random numbers from the specified distribution.

If:
• n is None, return a float,

• n >= 1, return a Numpy array,

• n < 0, raise an Exception,

• n is 0, return an empty array.

If called with distribution=None, returns uniformly distributed floats in the range [0, 1)

If mask is provided, it should be a boolean or integer NumPy array, indicating that only a subset of the random numbers should be returned.

Example:

```rng.next(5, mask=np.array([True, False, True, False, True]))
```

or:

```rng.next(5, mask=np.array([0, 2, 4]))
```

will each return only three values.

If the rng is “parallel safe”, an array of n values will be drawn from the rng, and the mask applied. If the rng is not parallel safe, the contents of the mask are disregarded, only its size (for an integer mask) or the number of True values (for a boolean mask) is used in determining how many values to draw.

class GSLRNG(seed=None, type='mt19937', parallel_safe=True)[source]

Bases: `WrappedRNG`

Wrapper for the GSL random number generators.

translations = {'binomial': ('binomial', {'n': 'n', 'p': 'p'}), 'exponential': ('exponential', {'beta': 'mu'}), 'gamma': ('gamma', {'k': 'k', 'theta': 'theta'}), 'lognormal': ('lognormal', {'mu': 'zeta', 'sigma': 'sigma'}), 'normal': ('normal', {'mu': 'mu', 'sigma': 'sigma'}), 'normal_clipped': ('normal_clipped', {'mu': 'mu', 'sigma': 'sigma', 'low': 'low', 'high': 'high'}), 'poisson': ('poisson', {'lambda_': 'mu'}), 'uniform': ('flat', {'low': 'a', 'high': 'b'}), 'uniform_int': ('uniform_int', {'low': 'low', 'high': 'high'})}
uniform_int(low, high, size=None)[source]
gamma(k, theta, size=None)[source]
normal(mu=0.0, sigma=1.0, size=None)[source]
normal_clipped(mu=0.0, sigma=1.0, low=-inf, high=inf, size=None)[source]
describe()

Return n random numbers from the specified distribution.

If:
• n is None, return a float,

• n >= 1, return a Numpy array,

• n < 0, raise an Exception,

• n is 0, return an empty array.

If called with distribution=None, returns uniformly distributed floats in the range [0, 1)

If mask is provided, it should be a boolean or integer NumPy array, indicating that only a subset of the random numbers should be returned.

Example:

```rng.next(5, mask=np.array([True, False, True, False, True]))
```

or:

```rng.next(5, mask=np.array([0, 2, 4]))
```

will each return only three values.

If the rng is “parallel safe”, an array of n values will be drawn from the rng, and the mask applied. If the rng is not parallel safe, the contents of the mask are disregarded, only its size (for an integer mask) or the number of True values (for a boolean mask) is used in determining how many values to draw.

class NativeRNG(seed=None)[source]

Bases: `AbstractRNG`

Signals that the simulator’s own native RNG should be used. Each simulator module should implement a class of the same name which inherits from this and which sets the seed appropriately.

Return n random numbers from the specified distribution.

If:
• n is None, return a float,

• n >= 1, return a Numpy array,

• n < 0, raise an Exception,

• n is 0, return an empty array.

If called with distribution=None, returns uniformly distributed floats in the range [0, 1)

If mask is provided, it should be a boolean or integer NumPy array, indicating that only a subset of the random numbers should be returned.

Example:

```rng.next(5, mask=np.array([True, False, True, False, True]))
```

or:

```rng.next(5, mask=np.array([0, 2, 4]))
```

will each return only three values.

If the rng is “parallel safe”, an array of n values will be drawn from the rng, and the mask applied. If the rng is not parallel safe, the contents of the mask are disregarded, only its size (for an integer mask) or the number of True values (for a boolean mask) is used in determining how many values to draw.

Todo

write this