This library is an implementation of arXiv:2004.06278 adapted for any number of bits. Keep in mind that the original implementation was designed for 64 bit numbers while this implementation uses a default of 32.
The generation algorithm is NOT MY WORK. For the paper on which this utility is based, please look here.
The package can be installed with
pip install squares-rng
After installing, the generator can be used with
from squares import squares
rng = squares()
next(rng) # Returns 32-bit uint
The generator can be seeded
rng = squares(seed=42)
next(rng) # 4161798144
If you are struggling to decide on a seed to use for reproducible testing, one can be generated from the computer's internal clock
from squares import get_suitable_seed
seed = get_suitable_seed()
This function is used in the case that no seed is provided to the generator.
get_suitable_seed
has no bit restrictions. If a seed containing too many bits is passed to the generator, it will be truncated and a warning will be shown.
For small seeds, the safety
parameter should be left as True
rng = squares(seed=42, safety=False)
next(rng) # 0
next(rng) # 115605504
safety
is a proprietary method to allow for smaller keys, iterating the generator until the seed has a non-zero maximal bit. Due to the nature of the algorithm, smaller keys would otherwise result in much smaller numbers for the first few iterations. With safety=True
, keep in mind that the first generation will take longer than subsequent calls.
The maximal bits of the generated number can also be set
rng = squares(seed=84, bits=64)
next(rng) # 9267630197371305984
The default is bits=32
for maximal python compatibility. Keep in mind that this does not automatically influence the internal calculation except where necessary. Some internal calculations may involve more than the specified number of bits if python allows it. However, the generated integer will not exceed the requested bits.
Lastly, a truncation utility is included
from squares import truncate
truncate(6798039809, 32) # 2503072513
The truncation utility defaults to truncating the higher bits, but can be configured to preserve them instead
truncate(698320, 16, right_shift=True) # 43645