Permuted Congruential Generator (64-bit, PCG64)¶

class randomgen.pcg64.PCG64(seed=None, inc=0, *, variant='xsl-rr', mode=None)¶

Container for the PCG-64 pseudo-random number generator.

Parameters:¶

seed=None¶

Random seed initializing the pseudo-random number generator. Can be an integer in [0, 2**128), a SeedSequence instance or None (the default). If seed is None, then PCG64 will used a SeedSequence initialized with system entropy to Seed the generator

inc=0¶

The increment in the LCG. Can be an integer in [0, 2**128) or None. If inc is None, then it is initialized using entropy. The default is None.

variant='xsl-rr'¶

Name of PCG64 variant to use. “xsl-rr” corresponds to the original PCG64 (1.0). 1 and “1.0” are aliases for “xsl-rr”. “dxsm-128” is identical to the original except that it replaces the mixing function with DXSM. “dxsm” uses a cheap multiplier (64-bit, rather than 128-bit) in the underlying LCG and the DXSM output mixer. It also returns the value before advancing the state. This variant is PCG64 2.0. “cm-dxsm” (cheap multiplier-dxsm), 2 and “2.0” are aliases for “dxsm”. None trusts randomgen to chose the variant.

mode=None¶

The seeding mode to use. “legacy” uses the legacy SplitMix64-based initialization. “sequence” uses a SeedSequence to transforms the seed into an initial state. “numpy” also uses a SeedSequence but seeds the generator in a way that is identical to NumPy. When using “numpy”, inc must be None. Additionally, to match NumPy, variant must be xsl-rr (this is not checked). None defaults to “sequence”.

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.

Type:¶

threading.Lock

seed_seq¶

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

Type:¶

{None, SeedSequence}

Notes

PCG-64 is a 128-bit implementation of O’Neill’s permuted congruential generator ([1], [2]). PCG-64 has a period of \(2^{128}\) and supports advancing an arbitrary number of steps.

Random variates are generated by permuting the output of a 128-bit LCG

\[s_{n+1} = m s_{n} + i \mod 2^{128}\]

where \(s\) is the state of the generator, \(m\) is the multipler and \(i\) is the increment. The multipler is a 128-bit unsigned integer with good spectral properties except when using the “dxsm” variant, in which case it is a 64-bit unsigned integer. The output of the LCG is the permuted using either an XOR and a random rotation (XSL-RR) or a function similar to an Xorshift (DXSM).

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

Supports the method advance to advance the RNG an arbitrary number of steps. The state of the PCG-64 RNG is represented by a 128-bit unsigned integer.

State and Seeding

The PCG64 state vector consists of 2 unsigned 128-bit values, which are represented externally as Python ints. PCG64 is seeded using a single 128-bit unsigned integer. In addition, a second 128-bit unsigned integer is used as the increment in the LCG.

Compatibility Guarantee

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

Examples

Parallel Features

PCG64 can be used in parallel applications by calling advance with a different value on each instance to produce non-overlapping sequences.

>>> from numpy.random import Generator
>>> from randomgen import PCG64
>>> rg = [Generator(PCG64(1234, i + 1)) for i in range(10)]
>>> for i in range(10):
...     rg[i].bit_generator.advance(i * 2**64)

References

Seeding and State¶

Parallel generation¶

Extending¶

Testing¶