Mersenne Twister (MT19937)

class randomgen.mt19937.MT19937(seed=None, *, mode=None)

Container for the Mersenne Twister pseudo-random number generator.

Parameters
seed{None, int, array_like[uint32], SeedSequence}, optional

Random seed used to initialize the pseudo-random number generator. Can be any integer between 0 and 2**32 - 1 inclusive, an array (or other sequence) of unsigned 32-bit integers, a SeedSequence instance or None (the default). If seed is None, then 624 32-bit unsigned integers are read from /dev/urandom (or the Windows analog) if available. If unavailable, a hash of the time and process ID is used.

mode{None, “sequence”, “legacy”, “numpy”}, optional

The seeding mode to use. “legacy” uses the legacy SplitMix64-based initialization. “sequence” uses a SeedSequence to transforms the seed into an initial state. None defaults to “sequence”. “numpy” uses the same seeding mechanism as NumPy and so matches exactly.

Notes

MT19937 provides a capsule containing function pointers that produce doubles, and unsigned 32 and 64- bit integers [1]. These are not directly consumable in Python and must be consumed by a Generator or similar object that supports low-level access.

The Python stdlib module “random” also contains a Mersenne Twister pseudo-random number generator.

State and Seeding

The MT19937 state vector consists of a 768-element array of 32-bit unsigned integers plus a single integer value between 0 and 768 that indexes the current position within the main array.

MT19937 is seeded using either a single 32-bit unsigned integer or a vector of 32-bit unsigned integers. In either case, the input seed is used as an input (or inputs) for a hashing function, and the output of the hashing function is used as the initial state. Using a single 32-bit value for the seed can only initialize a small range of the possible initial state values.

Parallel Features

MT19937 can be used in parallel applications by calling the method jump which advances the state as-if \(2^{128}\) random numbers have been generated ([1], [2]). This allows the original sequence to be split so that distinct segments can be used in each worker process. All generators should be initialized with the same seed to ensure that the segments come from the same sequence.

>>> from randomgen.entropy import random_entropy
>>> from randomgen import Generator, MT19937
>>> seed = random_entropy()
>>> rs = [Generator(MT19937(seed)) for _ in range(10)]
# Advance each MT19937 instance by i jumps
>>> for i in range(10):
...     rs[i].bit_generator.jump(i)

Compatibility Guarantee

MT19937 makes a guarantee that a fixed seed and will always produce the same random integer stream.

References

1(1,2)

Hiroshi Haramoto, Makoto Matsumoto, and Pierre L’Ecuyer, “A Fast Jump Ahead Algorithm for Linear Recurrences in a Polynomial Space”, Sequences and Their Applications - SETA, 290–298, 2008.

2

Hiroshi Haramoto, Makoto Matsumoto, Takuji Nishimura, François Panneton, Pierre L’Ecuyer, “Efficient Jump Ahead for F2-Linear Random Number Generators”, INFORMS JOURNAL ON COMPUTING, Vol. 20, No. 3, Summer 2008, pp. 385-390.

Attributes
lockthreading.Lock

Lock instance that is shared so that the same bit git generator can be used in multiple Generators without corrupting the state. Code that generates values from a bit generator should hold the bit generator’s lock.

seed_seq{None, SeedSequence}

The SeedSequence instance used to initialize the generator if mode is “sequence” or is seed is a SeedSequence. None if mode is “legacy”.

Seeding and State

seed([seed])

Seed the generator

state

Get or set the PRNG state

Parallel generation

jump([jumps])

Jumps the state as-if 2**128 random numbers have been generated.

jumped([jumps])

Returns a new bit generator with the state jumped

Extending

cffi

CFFI interface

ctypes

ctypes interface

Testing

random_raw([size, output])

Return randoms as generated by the underlying BitGenerator