Class L128X1024Mix

java.lang.Object

org.apache.commons.rng.core.BaseProvider

org.apache.commons.rng.core.source64.LongProvider

org.apache.commons.rng.core.source64.AbstractL128

org.apache.commons.rng.core.source64.L128X1024Mix

All Implemented Interfaces:

RandomLongSource, JumpableUniformRandomProvider, LongJumpableUniformRandomProvider, RestorableUniformRandomProvider, SplittableUniformRandomProvider, UniformRandomProvider

public class L128X1024Mix
extends AbstractL128
implements SplittableUniformRandomProvider

A 64-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 128-bit LCG and 1024-bit Xor-based generator. It is named as "L128X1024MixRandom" 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 1312 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 127-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

Field Summary

Fields

Modifier and Type	Field	Description
private int	index	Index in "state" array.
private static final int	LCG_STATE_SIZE	Size of the LCG state vector.
private static final long	ML	Low half of 128-bit LCG multiplier.
private static final int	SEED_SIZE	Size of the seed vector.
private final long[]	x	State of the XBG.
private static final int	XBG_STATE_SIZE	Size of the XBG state vector.

Fields inherited from class AbstractL128

lah, lal, lsh, lsl

Constructor Summary

Constructors

Modifier	Constructor	Description
	L128X1024Mix(long[] seed)	Creates a new instance.
protected	L128X1024Mix(L128X1024Mix source)	Creates a copy instance.

Method Summary

Modifier and Type	Method	Description
(package private) AbstractL128	copy()	Create a copy.
private static SplittableUniformRandomProvider	create(long seed, UniformRandomProvider source)	Create a new instance using the given seed and source of randomness to initialise the instance.
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.
long	next()	Return the next random value.
protected void	setStateInternal(byte[] s)	Resets the RNG to the given state.
SplittableUniformRandomProvider	split(UniformRandomProvider source)	Creates a new random generator, split off from this one, that implements the SplittableUniformRandomProvider interface.
Stream<SplittableUniformRandomProvider>	splits(long streamSize, SplittableUniformRandomProvider source)	Returns a stream producing the given streamSize number of new random generators, each of which implements the SplittableUniformRandomProvider interface.

Methods inherited from class LongProvider

nextBoolean, nextInt, nextLong, resetCachedState

Methods inherited from class BaseProvider

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

Methods inherited from class Object

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

Methods inherited from interface JumpableUniformRandomProvider

jumps, jumps

Methods inherited from interface LongJumpableUniformRandomProvider

longJumps, longJumps

Methods inherited from interface SplittableUniformRandomProvider

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

Methods inherited from interface UniformRandomProvider

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

Field Details

SEED_SIZE

private static final int SEED_SIZE

Size of the seed vector.

See Also:

• Constant Field Values

XBG_STATE_SIZE

private static final int XBG_STATE_SIZE

Size of the XBG state vector.

See Also:

• Constant Field Values

LCG_STATE_SIZE

private static final int LCG_STATE_SIZE

Size of the LCG state vector.

See Also:

• Constant Field Values

ML

private static final long ML

Low half of 128-bit LCG multiplier.

See Also:

• Constant Field Values

x

private final long[] x

State of the XBG.

index

private int index

Index in "state" array.

Constructor Details

L128X1024Mix

public L128X1024Mix(long[] seed)

Creates a new instance.

Parameters:

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

The 1st and 2nd elements are used to set the LCG increment; the least significant bit is set to odd to ensure a full period LCG. The 3rd and 4th elements are used to set the LCG state.

L128X1024Mix

protected L128X1024Mix(L128X1024Mix source)

Creates a copy instance.

Parameters:

source - Source to copy.

Method Details

getStateInternal

protected byte[] getStateInternal()

Creates a snapshot of the RNG state.

Overrides:

getStateInternal in class AbstractL128

Returns:

the internal state.

setStateInternal

protected void setStateInternal(byte[] s)

Resets the RNG to the given state.

Overrides:

setStateInternal in class AbstractL128

Parameters:

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

See Also:

• BaseProvider.checkStateSize(byte[],int)

next

public long next()

Return the next random value.

Specified by:

next in interface RandomLongSource

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

Overrides:

jump in class AbstractL128

Returns:

A copy of the current state.

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

Overrides:

longJump in class AbstractL128

Returns:

A copy of the current state.

copy

AbstractL128 copy()

Create a copy.

Specified by:

copy in class AbstractL128

Returns:

the copy

split

public SplittableUniformRandomProvider split(UniformRandomProvider source)

Creates a new random generator, split off from this one, that implements the SplittableUniformRandomProvider interface.

Specified by:

split in interface SplittableUniformRandomProvider

Parameters:

source - A source of randomness used to initialise the new instance.

Returns:

A new instance.

splits

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

Returns a stream producing the given streamSize number of new random generators, each of which implements the SplittableUniformRandomProvider interface.

Specified by:

splits in interface SplittableUniformRandomProvider

Parameters:

streamSize - Number of objects to generate.

source - A source of randomness used to initialise the new instances; this may be split to provide a source of randomness across a parallel stream.

Returns:

a stream of random generators; the stream is limited to the given streamSize.

create

private static SplittableUniformRandomProvider create(long seed,
 UniformRandomProvider source)

Create a new instance using the given seed and source of randomness to initialise the instance.

Parameters:

seed - Seed used to initialise the instance.

source - Source of randomness used to initialise the instance.

Returns:

A new instance.