ThreeFry Counter-based RNG¶

class randomgen.threefry.ThreeFry(seed=None, *, counter=None, key=None, number=4, width=64)¶

Container for the ThreeFry family of pseudo-random number generators.

Parameters:¶

seed=None¶

Entropy initializing the pseudo-random number generator. Can be an integer in [0, 2**64), array of integers 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.

counter=None¶

Counter to use in the ThreeFry state. Can be either a Python int in [0, 2**(N*W)) where N is number of W is the width, or a M-element uint64 array where M = N*W // 64. If not provided, the counter is initialized at 0.

key=None¶

Key to use in the ThreeFry state. Unlike seed, which is run through another RNG before use, the value in key is directly set. Can be either a Python int in [0, 2**(N*W)) or a M-element uint64 array where M = N*W // 64. key and seed cannot both be used.

number=4¶

Number of values to produce in a single call. Maps to N in the ThreeFry variant naming scheme ThreeFryNxW.

width=64¶

Bit width the values produced. Maps to W in the ThreeFry variant naming scheme ThreeFryNxW.

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

ThreeFry is a 32 or 64-bit PRNG that uses a counter-based design based on weaker (and faster) versions of cryptographic functions [1]. Instances using different values of the key produce distinct sequences. ThreeFry has a period of \(N*2^{N*W}\) and supports arbitrary advancing and jumping the sequence in increments of \(2^{N*W//2}\). These features allow multiple non-overlapping sequences to be generated.

ThreeFry 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.

See Philox for a closely related PRNG.

State and Seeding

The ThreeFry state vector consists of two (N*W)-bit values. These are encoded as an n-element w-bit array. One is a counter which is incremented by 1 for every n w-bit randoms produced. The second is a key which determines the sequence produced. Using different keys produces distinct sequences.

Using a single 64-bit value for the seed can only initialize a small range of the possible initial state values.

Parallel Features

ThreeFry can be used in parallel applications by calling the jumped method to advances the state as-if \(2^{N*W//2}\) random numbers have been generated. Alternatively, advance can be used to advance the counter for any positive step in [0, 2**N*W). When using jumped, all generators should be initialized with the same seed to ensure that the segments come from the same sequence.

>>> from numpy.random import Generator
>>> from randomgen import ThreeFry
# Advance each ThreeFry instance by i jumps
>>> rg = [Generator(ThreeFry(1234).jumped(i)) for i in range(10)]

Alternatively, ThreeFry can be used in parallel applications by using a sequence of distinct keys where each instance uses different key.

>>> key = 2**196 + 2**132 + 2**65 + 2**33 + 2**17 + 2**9
>>> rg = [Generator(ThreeFry(key=key+i)) for i in range(10)]

Compatibility Guarantee

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

Examples

>>> from numpy.random import Generator
>>> from randomgen import ThreeFry
>>> rg = Generator(ThreeFry(1234))
>>> rg.standard_normal()
0.123  # random

References

Seeding and State¶

Parallel generation¶

Extending¶

Testing¶