Jenkins Small Fast Generator¶

class randomgen.jsf.JSF(seed=None, *, seed_size=1, size=64, p=None, q=None, r=None, mode=None)¶

Container for Jenkins’s Fast Small (JSF) pseudo-random number generator

Parameters:¶

seed=None¶

Random seed initializing the pseudo-random number generator. Can be an integer in [0, 2**size), an array of integers in [0, 2**size), a SeedSequence or None (the default). If seed is None, then data is read from /dev/urandom (or the Windows analog) if available. If unavailable, a hash of the time and process ID is used.

seed_size=1¶

Number of distinct seed values used to initialize JSF. The original implementation uses 1 (default). Higher values increase the size of the seed space which is 2**(size*seed_size).

size=64¶

Output size of a single iteration of JSF. 32 is better suited to 32-bit systems.

p=None¶

One the the three parameters that defines JSF. See Notes. If not provided uses the default values for the selected size listed in Notes.

q=None¶

One the the three parameters that defines JSF. See Notes. If not provided uses the default values for the selected size listed in Notes.

r=None¶

One the the three parameters that defines JSF. See Notes. If not provided uses the default values for the selected size listed in Notes.

mode=None¶

The seeding mode to use. “legacy” uses the legacy SplitMix64-based initialization. “sequence” uses a SeedSequence to transforms the seed into an initial state. None defaults to “sequence”.

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. None if mode is “legacy”.

Type:¶

{None, SeedSequence}

Notes

The JSF generator uses a 4-element state of unsigned integers, either uint32 or uint64, a, b, c and d ([1]). The generator also depends on 3 parameters p, q, and r that must be between 0 and size-1.

The algorithm is defined by:

e = a - ROTL(b, p)
a = b ^ ROTL(c, q)
b = c + ROTL(d, r)
c = d + e
d = e + a

where d is the value returned at the end of a single iteration and ROTL(x, y) left rotates x by y bits.

Default Parameters

The defaults are

Parameter		32	64
p		27	7
q		17	13
r		0	37

There are many other parameterizations. See the class attribute JSF.parameters for a list of the values provided by Jenkins. Note that if r is 0, the generator uses only 2 rotations.

State and Seeding

The state consists of the 4 values a, b, c and d. The size of these values depends on size. The seed value is an unsided integer with the same size as the generator (e.g., uint64 for size==64).

Compatibility Guarantee

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

Examples

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

References

Seeding and State¶

Extending¶

Testing¶