# 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, int, array_like[int], SeedSequence}, optional

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{None, int}, optional

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{None, “xsl-rr”, “1.0”, 1, “dxsm”, “cm-dxsm”, 2, “2.0”, “dxsm-128”}, optional

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, “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. “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”.

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.

References

1

“PCG, A Family of Better Random Number Generators”, https://www.pcg-random.org/

2

O’Neill, Melissa E. “PCG: A Family of Simple Fast Space-Efficient Statistically Good Algorithms for Random Number Generation”

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.

>>> rg = [Generator(PCG64(1234, i + 1)) for i in range(10)]
>>> for i in range(10):

Attributes

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, inc]) Seed the generator state Get or set the PRNG state

## Parallel generation¶

 advance(delta) Advance the underlying RNG as-if delta draws have occurred. jump([iter]) Jump the state a fixed increment jumped([iter]) 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