Middle Square with Weyl increment (64-bit, Squares)¶

class randomgen.squares.Squares(seed=None, counter=None, key=None, variant=64)¶

Squares counter-based PRNG

Squares is a counter-based PRNG that uses a key to generate random numbers using the middle-square random number generator [1]. The key is carefully generated using a SeedSequence to satisfy certain characteristics regarding bit density.

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, then data is read from /dev/urandom (or the Windows analog) if available.

counter=None¶

The initial counter to use when constructing the PRNG. The defalt value is 0.

key=None¶

The key to use when constructing the PRNG. If None, the key is generated using the seeded SeedSequence. Default is None. Setting this value will override the key generated by the SeedSequence.

variant=64¶

The variance of the Square to use. Default is 64.

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.

Type:¶

{None, SeedSequence}

Notes

Squares [2] is a pseudo-random number generator based on the Squares PRNG. It comes in both 64-bit (default) and 32-bit variants. It uses a 64-bit key and a counter. Each draw transforms the current counter using a number of middle-square operations and the key. The key is constructed using 3 rues:

• The first word (16 bits) ia selected from the set {1, 3, 5, … B, D, F}, and so is always odd.

• The next 7 words are selected without repetition from the set {1, 2, 3, …, D, E, F}, excluding the word selected in the 1st position.

• The remaining 8 words are selected at random (with replacement) from the set {1, 2, 3, …, D, E, F} with the run that the word in position i must differ from the work in position j.

The SeedSequence used in the initialization of the bit generator is used as the source of randomness for

State and Seeding

The Squares state consists of a 64-bit unsigned integer key and a 64-bit unsigned integer counter. By default, the seed value is translated into the 64-bit unsigned integer. If counter is None, the PRNG starts with a counter of 0..

Compatibility Guarantee

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

Examples

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

Parallel Features

Squares can be used in parallel when combined with a SeedSequence using spawn.

>>> from randomgen import SeedSequence
>>> entropy = 8509285875904376097169743623867
>>> ss = SeedSequence(entropy)
>>> bit_gens = [Squares(child) for child in ss.spawn(1024)]

An alternative generates a set of keys from a single seed.

>>> from randomgen.squares import generate_keys
>>> keys = generate_keys(1234, 1024)
>>> bit_gens = [Squares(key=key) for key in keys]

The final options uses the same seed value along with different counter values.

>>> from randomgen import SeedSequence
>>> bit_gens = []
>>> for i in range(1024):
...     bit_gens.append(Squares(SeedSequence(entropy), counter=1_000_000_000 * i))

See also

randomgen.squares.generate_keys

Key generation function for the Squares PRNG with additional details on key requirements.

References

Seeding and State¶

Parallel generation¶

Extending¶

Testing¶

Key Generation¶

A convenience function for pre-generating keys that can be used with the key argument of Squares is available. This function transforms the entropy in a SeedSequence into a 64-bit unsigned integer key that can be used with Squares.