randomgen.squares.generate_keys¶

randomgen.squares.generate_keys(seed=None, n=1, unique=False)¶

Pre-generate keys for use with Squares

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.
n=1¶: Number of keys to generate. Must be a positive integer. Default is 1.
unique=False¶: If True, return only unique keys. Default is False.

Returns:¶

keys – Array of generated keys.

Return type:¶

numpy.ndarray

Notes

The keys are generated randomly using the entropy generated by a SeedSequence (which is either the value of seed or a SeedSequence created using seed).

Key are generated according to the following rules [1]:

Word 0: Odd number between 1 and 15.
Words 1-7: Randomly selected from 1 to 15. Each word can appear at most once (including word 0).
Words 9 - 15: Randomly selected from 1 to 15. Word n is required to be different from word n-1.

There is no guarantee that the keys returns are distinct unless unique is True. Using unqiue keys can be expensive as it requires calling np.unique on the generated keys, and then regenerating keys additional keys if there are incufficient unique keys. The number of distinct keys is

\[8 \cdot 14_p 7 \cdot 14^8 = 204,217,092,180,541,440\]

where \(14_p 7\) is the number of permutations of 7 elements from 14. The chance of observing at least one repeated key in a subsample of 25,000 would be approximately 1 in 8,168,683,687,202.

Examples

>>> from numpy.random import SeedSequence
>>> from randomgen.squares import generate_keys
>>> ss = SeedSequence(1234)
>>> keys = generate_keys(ss, 5)
>>> keys
array([ 9470186258571876535, 11789540394216366135, 11013866738698308655,
    7246136968226125645,  1784984383128236737], dtype=uint64)

>>> for k in keys: print(hex(k))
0x836cdc3a1af658b7
0xa39cdc865e62a037
0x98d91d71e39a4c2f
0x648f732e50f1b74d
0x18c589d6d5fa72c1