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, int, array_like[uint], SeedSequence}, optional: 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, 2, 3}, optional: 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{32, 64}, optional: Output size of a single iteration of JSF. 32 is better suited to 32-bit systems.
pint, optional: One the the three parameters that defines JSF. See Notes. If not provided uses the default values for the selected size listed in Notes.
qint, optional: One the the three parameters that defines JSF. See Notes. If not provided uses the default values for the selected size listed in Notes.
rint, optional: 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, “sequence”, “legacy”}, optional: 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”.

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.

References

[1]

Jenkins, Bob (2009). “A small noncryptographic PRNG”. https://burtleburtle.net/bob/rand/smallprng.html

Examples

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

Attributes:

lockthreading.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.
seed_seq{None, SeedSequence}: The SeedSequence instance used to initialize the generator if mode is “sequence” or is seed is a SeedSequence. None if mode is “legacy”.

Seeding and State¶

`seed`([seed])	Seed the generator
`state`	Get or set the PRNG state

Extending¶

`cffi`	CFFI interface
`ctypes`	ctypes interface

Testing¶

random_raw([size, output])

Return randoms as generated by the underlying BitGenerator