# LXM Generator¶

class randomgen.lxm.LXM(seed=None, *, b=3037000493)

Container for the LXM pseudo-random number generator.

Parameters:
seed{None, int, array_like[uint64], SeedSequence}, optional

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. If unavailable, a hash of the time and process ID is used.

buint64

The additive constant in the LCG update. Must be odd, and so 1 is added if even. The default value is 3037000493.

Notes

The LXM generator combines two simple generators with an optional additional hashing of the output. This generator has been proposed for inclusion in Java ([1]). The first generator is a LCG of with and update

$s = a s + b \mod 2^{64}$

where a is 2862933555777941757 and b is settable. The default value of b is 3037000493 ([5]). The second is the standard 64-bit xorshift generator ([2], [3]). The output of these two is combined using addition. This sum is hashed using the Murmur3 hash function using the parameters suggested by David Stafford ([4]). Is pseudo-code, each value is computed as Mix(LCG + Xorshift). While the origins of LXM are not clear from ([1]), it appears to be derived from LCG Xorshift Mix.

LXM provides a capsule containing function pointers that produce doubles, and unsigned 32 and 64- bit integers. These are not directly consumable in Python and must be consumed by a Generator or similar object that supports low-level access.

State and Seeding

The LXM state vector consists of a 4-element array of 64-bit unsigned integers that constraint he state of the Xorshift generator and an addition 64-bit unsigned integer that holds the state of the LCG.

The seed value is used to create a SeedSequence which is then used to set the initial state.

Parallel Features

LXM can be used in parallel applications by calling the method jumped which provides a new instance with a state that has been updated as-if $$2^{128}$$ random numbers have been generated. This allows the original sequence to be split so that distinct segments can be used in each worker process. All generators should be initialized with the same seed to ensure that the segments come from the same sequence.

>>> from numpy.random import Generator
>>> from randomgen import LXM
>>> rg = [Generator(LXM(1234))]
# Advance each LXM instance by i jumps
>>> for i in range(10):
...     rg.append(rg[-1].jumped())


Note that jumped states only alters the Xorshift state since the jump is a full cycle of the LCG.

Compatibility Guarantee

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

References

[1] (1,2)

Guy Steele (2019, June 21). JEP 356: Enhanced Pseudo-Random Number Generators. Retrieved June 01, 2020, from https://openjdk.java.net/jeps/356.

[2]

Marsaglia, George. “Xorshift RNGs.” Journal of Statistical Software [Online], 8.14, pp. 1 - 6, 2003.

[3]

“xorshift*/xorshift+ generators and the PRNG shootout”, https://prng.di.unimi.it/.

[4]

David Stafford (2011, September 28). Better Bit Mixing - Improving on MurmurHash3’s 64-bit Finalizer. Retrieved June 01, 2020, from https://zimbry.blogspot.com/2011/09/better-bit-mixing-improving-on.html.

[5]

Bret R. Beck and Eugene D. Brooks III (2000, December 8). 64-bit Linear Congruential Generator. Retrieved June 01, 2020, from https://nuclear.llnl.gov/CNP/rng/rngman/node4.html.

Examples

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

Attributes:

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

## Parallel generation¶

 jump([iter]) Jumps the state as-if 2**128 random numbers have been generated jumped([iter]) Returns a new bit generator with the state jumped

## Extending¶

 cffi CFFI interface ctypes ctypes interface

## Testing¶

 random_raw([size, output]) Return randoms as generated by the underlying BitGenerator