Package org.apache.commons.rng.core.source32

Class L32X64Mix

java.lang.Object

org.apache.commons.rng.core.BaseProvider

org.apache.commons.rng.core.source32.IntProvider

org.apache.commons.rng.core.source32.L32X64Mix

All Implemented Interfaces:

RandomIntSource, JumpableUniformRandomProvider, LongJumpableUniformRandomProvider, RestorableUniformRandomProvider, SplittableUniformRandomProvider, UniformRandomProvider

public final class L32X64Mix
extends IntProvider
implements LongJumpableUniformRandomProvider, SplittableUniformRandomProvider

A 32-bit all purpose generator.

This is a member of the LXM family of generators: L=Linear congruential generator; X=Xor based generator; and M=Mix. This member uses a 32-bit LCG and 64-bit Xor-based generator. It is named as "L32X64MixRandom" in the java.util.random package introduced in JDK 17; the LXM family is described in further detail in:

Steele and Vigna (2021) LXM: better splittable pseudorandom number generators (and almost as fast). Proceedings of the ACM on Programming Languages, Volume 5, Article 148, pp 1–31.

Memory footprint is 128 bits and the period is 2³² (2⁶⁴ - 1).

This generator implements LongJumpableUniformRandomProvider. In addition instances created with a different additive parameter for the LCG are robust against accidental correlation in a multi-threaded setting. The additive parameters must be different in the most significant 31-bits.

This generator implements SplittableUniformRandomProvider. The stream of generators created using the splits methods support parallelisation and are robust against accidental correlation by using unique values for the additive parameter for each instance in the same stream. The primitive streaming methods support parallelisation but with no assurances of accidental correlation; each thread uses a new instance with a randomly initialised state.

Since:

1.5

See Also:

Steele & Vigna (2021) Proc. ACM Programming Languages 5, 1-31, JDK 17 java.util.random javadoc

Constructor Summary

Constructors

Constructor	Description
L32X64Mix(int[] seed)	Creates a new instance.
L32X64Mix(int seed0, int seed1, int seed2, int seed3)	Creates a new instance using a 4 element seed.

Method Summary

Modifier and Type	Method	Description
protected byte[]	getStateInternal()	Creates a snapshot of the RNG state.
UniformRandomProvider	jump()	Creates a copy of the UniformRandomProvider and then retreats the state of the current instance.
JumpableUniformRandomProvider	longJump()	Creates a copy of the UniformRandomProvider and then retreats the state of the current instance.
int	next()
protected void	setStateInternal(byte[] s)	Resets the RNG to the given state.
SplittableUniformRandomProvider	split(UniformRandomProvider source)
Stream<SplittableUniformRandomProvider>	splits(long streamSize, SplittableUniformRandomProvider source)

Methods inherited from class org.apache.commons.rng.core.source32.IntProvider

nextBoolean, nextBytes, nextBytes, nextDouble, nextInt, nextLong, resetCachedState

Methods inherited from class org.apache.commons.rng.core.BaseProvider

checkIndex, checkStateSize, composeStateInternal, extendSeed, extendSeed, fillState, fillState, restoreState, saveState, splitStateInternal, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.commons.rng.JumpableUniformRandomProvider

jumps, jumps

Methods inherited from interface org.apache.commons.rng.LongJumpableUniformRandomProvider

longJumps, longJumps

Methods inherited from interface org.apache.commons.rng.SplittableUniformRandomProvider

doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, split, splits, splits, splits

Methods inherited from interface org.apache.commons.rng.UniformRandomProvider

nextBoolean, nextBytes, nextBytes, nextDouble, nextDouble, nextDouble, nextFloat, nextFloat, nextFloat, nextInt, nextInt, nextInt, nextLong, nextLong, nextLong

Constructor Detail

L32X64Mix

public L32X64Mix(int[] seed)

Creates a new instance.

Parameters:

seed - Initial seed. If the length is larger than 4, only the first 4 elements will be used; if smaller, the remaining elements will be automatically set. A seed containing all zeros in the last two elements will create a non-functional XBG sub-generator and a low quality output with a period of 2³².

The 1st element is used to set the LCG increment; the least significant bit is set to odd to ensure a full period LCG. The 2nd element is used to set the LCG state.

L32X64Mix

public L32X64Mix(int seed0,
                 int seed1,
                 int seed2,
                 int seed3)

Creates a new instance using a 4 element seed. A seed containing all zeros in the last two elements will create a non-functional XBG sub-generator and a low quality output with a period of 2³².

The 1st element is used to set the LCG increment; the least significant bit is set to odd to ensure a full period LCG. The 2nd element is used to set the LCG state.

Parameters:

seed0 - Initial seed element 0.

seed1 - Initial seed element 1.

seed2 - Initial seed element 2.

seed3 - Initial seed element 3.

Method Detail

getStateInternal

protected byte[] getStateInternal()

Creates a snapshot of the RNG state.

Overrides:

getStateInternal in class IntProvider

Returns:

the internal state.

setStateInternal

protected void setStateInternal(byte[] s)

Resets the RNG to the given state.

Overrides:

setStateInternal in class IntProvider

Parameters:

s - State (previously obtained by a call to BaseProvider.getStateInternal()).

See Also:

BaseProvider.checkStateSize(byte[],int)

next

public int next()

Specified by:

next in interface RandomIntSource

Returns:

the next random value.

jump

public UniformRandomProvider jump()

Creates a copy of the UniformRandomProvider and then retreats the state of the current instance. The copy is returned.

The jump is performed by advancing the state of the LCG sub-generator by 1 cycle. The XBG state is unchanged. The jump size is the equivalent of moving the state backwards by (2⁶⁴ - 1) positions. It can provide up to 2³² non-overlapping subsequences.

Specified by:

jump in interface JumpableUniformRandomProvider

longJump

public JumpableUniformRandomProvider longJump()

Creates a copy of the UniformRandomProvider and then retreats the state of the current instance. The copy is returned.

The jump is performed by advancing the state of the LCG sub-generator by 2¹⁶ cycles. The XBG state is unchanged. The jump size is the equivalent of moving the state backwards by 2¹⁶ (2⁶⁴ - 1) positions. It can provide up to 2¹⁶ non-overlapping subsequences of length 2¹⁶ (2⁶⁴ - 1); each subsequence can provide up to 2¹⁶ non-overlapping subsequences of length (2⁶⁴ - 1) using the jump() method.

Specified by:

longJump in interface LongJumpableUniformRandomProvider

split

public SplittableUniformRandomProvider split(UniformRandomProvider source)

Specified by:

split in interface SplittableUniformRandomProvider

splits

public Stream<SplittableUniformRandomProvider> splits(long streamSize,
                                                      SplittableUniformRandomProvider source)

Specified by:

splits in interface SplittableUniformRandomProvider