Permuted Congruential Generator (32-bit, PCG32)

class randomgen.pcg32.PCG32(seed=None, inc=0)

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

Parameters:
seed=None

Random seed initializing the pseudo-random number generator. Can be an integer in [0, 2**64], a SeedSequence instance or None (the default). If seed is None, a new SeedSequence is created using entropy from the operating system.

inc=0

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

lock

Lock instance that is shared so that the same bit 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 seed the generator. If seed is not a SeedSequence, one is created from it.

Type:

{None, SeedSequence}

Notes

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

PCG32 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-32 PRNG is represented by 2 64-bit unsigned integers.

See PCG64 for a similar implementation with a larger period.

State and Seeding

The PCG32 state vector consists of 2 unsigned 64-bit values. PCG32 is seeded using a single 64-bit unsigned integer.

Parallel Features

PCG32 can be used in parallel applications using advance with a different value in each instance to produce non-overlapping sequences.

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

Each instance above uses a different increment inc. To split a single stream, advance stream i by i * step, where step is advance_step(max_draws) and max_draws is the most draws that any stream makes, or use jumped. Do not advance by a large power of two such as 2**63, which gives strongly related streams (see advance). The period of PCG32 is only 2**64, which limits how many streams fit without overlapping, for example to about 1.4 * 10**7 streams of 10**12 draws. Use PCG64, or the related PCG64DXSM or LCG128Mix, when many streams or many draws per stream are needed.

Compatibility Guarantee

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

References

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.

advance_step(max_draws)

Step for splitting one stream into streams of up to max_draws draws

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