This module is a thin Python wrapper over C library dcmt, created by Makoto Matsumoto and Takuji Nishimura, authors of Mersenne twister RNG algorithm. The original library provides functions for creating multiple independent RNGs (which can be used, for example, in parallel Monte-Carlo simulations).
We will start from importing the module:
>>> from dcmt import DcmtRandom
Creating three independent RNGs with default parameters:
>>> rngs = DcmtRandom.range(3, gen_seed=777)
If seed is not specified, the value from system RNG or timer is taken. Now we may explicitly initialize each generator (although they are initialised with random seed by default):
>>> rngs[0].seed(1)
>>> rngs[1].seed(2)
>>> rngs[2].seed(3)
Here seeds can be omitted too. They are independent from the one that was used to create generators. After initialisation every generator is ready to produce random numbers:
>>> rngs[0].random()
0.23113428363530963
>>> rngs[1].random()
0.2925564946366318
>>> rngs[2].random()
0.5276839180208412
>>> rngs[0].random()
0.3694159212179581
>>> rngs[1].random()
0.2539639751553334
>>> rngs[2].random()
0.5633233881529953
RNG objects support pickling and copying, so you can save and restore their states freely.
For further information about generator properties and various pitfalls please refer to the Reference section.
Before diving into module description it is necessary to clarify the purpose of different RNG creation parameters, which can be encountered in various constructors.
wordlen specifies the range of integer numbers RNG produces during each step: it is [0, 2 ** wordlen). Larger ranges (like 53-bit float, for example) can be achieved by combining random numbers from several subsequent steps of RNG.
Supported values: 31, 32.
exponent corresponds to the period of RNG, which equals to 2 ** exponent - 1. After this number of steps RNG will start to repeat previously generated sequence.
Supported values: 521, 607, 1279, 2203, 2281, 3217, 4253, 4423, 9689, 9941, 11213, 19937, 21701, 23209, 44497.
id as a keyword parameter or as an element of range in *range functions stands for RNG identifier. It can correspond, for example, to processor ID or thread ID in distributed calculations.
Supported values: [0, 65536).
seed, gen_seed: values for initialising RNGs. Any RNG needs two seeds: one to create RNG itself, and one to initialise its state (the latter is the common usage of term “seed”). Along with the parameters described above these two numbers fully specify created RNGs, and subsequent calls to the same functions with the same parameters will produce exactly the same RNG objects. If None is passed as a seed (which is a default value in all functions), the value of the seed will be taken from system RNG or current time. If int or long is passed, their lowest 4 bytes are taken; if the passed object is hashable, the lowest 4 bytes of its hash value are taken; otherwise DcmtParameterError is thrown.
Supported values: [0, 2 ** 32) or None.
Warning
There is a known bug in the algorithm where it fails to create RNG for wordlen=31, exponent=521 and id=9. The function will throw DcmtParameterError if this ID belongs to the range of requested IDs.
Tuple with integers, containing the module version, for example (0, 6, 1, 1). Here first three numbers specify the version of original dcmt library (because this module is very tightly coupled to C implementation), and the last number is the actual version of the wrapper.
This exception is thrown for an internal error of DCMT algorithm (usually some failure to create a generator).
This exception is thrown if parameters specified for creation/initialization of MT generators are incorrect.
Class, mimicking random.Random from Python standard library. For the list of available methods see Python reference.
For the information on keywords see Mersenne twister RNG parameters.
Analogue of built-in range which creates a list with DcmtRandom objects with given parameters and IDs in range(start, stop).
Note
The result of this function is not identical to several calls to DcmtRandom constructor, since this function specifically aims at creating independent RNGs with given range of IDs.
Class, partially mimicking numpy.random.RandomState. Currently supported: rand, get_state and set_state methods along with pickling/copying support (which is missing in numpy class).
For the information on keywords see Mersenne twister RNG parameters.
Fills given array with random double precision floating point random numbers.
| Parameters: | arr – numpy array with type float64. |
|---|
Fills given array with raw random integers provided by underlying RNG.
| Parameters: | arr – numpy array with any 4-byte elements (uint32_t if you want to see meaningful values). |
|---|
Warning
The integers are not scaled in any way. So, if the RNG has wordlen equal to 31, all integers will belong to interval [0, 2 ** 31).
Analogue of built-in range which creates a list with DcmtRandomState objects with given parameters and IDs in range(start, stop).
Note
The result of this function is not identical to several calls to DcmtRandomState constructor, since this function specifically aims at creating independent RNGs with given range of IDs.
Creates list of DcmtRandomState objects from the result of mt_range() function.
Creates optimized RNG data with no repeating elements.
| Returns: | tuple with two elements: dictionary with common parameters for all RNGs, and numpy array with parameters unique for each generator. |
|---|
Note
This function uses the same creation algorithm as DcmtRandomState.range() and DcmtRandom.range().
Note
This function is intended for usage in MT implementations on GPU, so the array with unique parameters contains RNG index, which, technically, is intialised only after the call to RNG seed() method. The addition of this parameter allows one to employ the returned continous buffer in random number generation without rearranging its elements (and, as a bonus, makes entries for separate RNGs 16 bytes long).