Random numbers

There are four considerations for random number generation and consumption in PyNN:

Reproducibility:
When comparing simulations with different backends, we may wish to ensure that all backends use the same sequence of random numbers so that the only differences between simulations arise from the numerics of the simulators.
Performance:
All simulators have their own built-in facilities for random number generation, and it may be faster to use these than to use random numbers generated by PyNN.
Distributed simulations:
When distributing simulations across multiple processors using MPI, we may wish to ensure that the sequence of random numbers is independent of the number of computation nodes.
Quality:
Different models have different requirements for the quality of the (pseudo-)random number generator used. For models that are not strongly dependent on this, we may wish to use a generator that is faster but has lower-quality. For models that are highly sensitive, a slower but higher-quality generator may be desired.

Because of these considerations, PyNN aims to provide a great deal of flexibility in specifying random number generation for those who need it, while hiding the details entirely for those who do not.

RNG classes

All functions and methods in the PyNN API that can make use of random numbers have an optional rng argument, which should be an instance of a subclass of pyNN.random.AbstractRNG. PyNN provides three such sub-classes:

NumpyRNG:
Uses the numpy.random.RandomState class (Mersenne Twister).
GSLRNG:
Uses the GNU Scientific Library random number generators.
NativeRNG:
Signals that the simulator’s own built-in RNG should be used.

If you wish to use your own random number generator, it is reasonably straightforward to do so: see Random numbers in the API reference.

Note

If the rng argument is not supplied (or is None), then the method or function creates a new NumpyRNG for its own use.

All RNG classes accept a seed argument, and a parallel_safe argument. The latter is True by default, and ensures that the simulation results will not depend on the number of MPI nodes in a distributed simulation. This independence can be computationally costly, however, so it is possible to set parallel_safe=False, accepting that the results will be dependent on the number of nodes, in order to get better performace.

Note

if you do not provide a seed, PyNN will provide one for you, the same each time. This means that running the same simulation several times will use identical random numbers each time, so if you want to have different random numbers on different runs, you must provide your own seed and change it (or randomly generate it) each time.

Note

parallel_safe may or may not have any effect when using a NativeRNG, depending on the simulator.

The next() method

Apart from the constructor, RNG classes have only one important method: next(), which returns a NumPy array containing random numbers from the requested distribution:

>>> rng = NumpyRNG(seed=824756)
>>> rng.next(5, 'normal', {'mu': 1.0, 'sigma': 0.2})
array([ 0.65866423,  0.87500017,  0.90755753,  0.93793779,  0.94839735])
>>> rng = GSLRNG(seed=824756, type='ranlxd2')  # RANLUX algorithm of Luescher
>>> rng.next(5, 'normal', {'mu': 1.0, 'sigma': 0.2})
array([ 0.61104097,  0.83086026,  0.87072741,  0.7513628 ,  1.12875371])

In versions of PyNN prior to 0.8, distribution names and parameterisations were not standardized: e.g. GSLRNG needed ‘gaussian’ rather than ‘normal’. As of PyNN 0.8, the following standardized names are used:

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 below/above low/high are set to low/high
poisson lambda  
uniform low, high  
uniform_int low, high  
vonmises mu, kappa  

The RandomDistribution class

The RandomDistribution class encapsulates a choice of random number generator and a choice of distribution, so that its next() method requires only the number of values required as argument:

>>> gamma = RandomDistribution('gamma', (2.0, 0.3), rng=NumpyRNG(seed=72386))
>>> gamma.next(5)
array([ 0.4325809 ,  0.12952503,  1.58510406,  0.81182457,  0.07577787])

You can alternatively provide parameter names as keyword arguments, e.g.:

>>> gamma = RandomDistribution('gamma', k=2.0, theta=0.3, rng=NumpyRNG(seed=72386))

Note that next() called without any arguments returns a single number, not an array:

>>> gamma.next()
0.52020946027308368
>>> gamma.next(1)
array([ 0.4863944])

Note

the apparent difference in precision between the single number and the array is not real: NumPy only displays a limited number of digits but the numbers in the array have full precision.

SpikeSourcePoisson

The SpikeSourcePoisson model is currently an exception to the situation outlined above. It ought to take an rng argument, but at present this is not supported, and the model uses the global random number generator seed, as set in the setup() function.