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 randomgen import Generator, 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