Class L64X128StarStar

java.lang.Object

org.apache.commons.rng.core.BaseProvider

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

org.apache.commons.rng.core.source64.L64X128StarStar

All Implemented Interfaces:

RandomLongSource, JumpableUniformRandomProvider, LongJumpableUniformRandomProvider, RestorableUniformRandomProvider, SplittableUniformRandomProvider, UniformRandomProvider

public class L64X128StarStar
extends LongProvider
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 64-bit LCG and 128-bit Xor-based generator. It is named as "L64X128StarStarRandom" 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 256 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 63-bits.

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
protected long	la	Per-instance LCG additive parameter (must be odd).
protected long	ls	State of the LCG generator.
protected static final long	M	LCG multiplier.
protected long	x0	State 0 of the XBG.
protected long	x1	State 1 of the XBG.

Constructor Summary

Constructors

Modifier	Constructor	Description
	L64X128StarStar(long[] seed)	Creates a new instance.
	L64X128StarStar(long seed0, long seed1, long seed2, long seed3)	Creates a new instance using a 4 element seed.
protected	L64X128StarStar(L64X128StarStar source)	Creates a copy instance.

Method Summary

Modifier and Type	Method	Description
protected L64X128StarStar	copy()	Create a copy.
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

M

protected static final long M

LCG multiplier.

See Also:

• Constant Field Values

x0

protected long x0

State 0 of the XBG.

x1

protected long x1

State 1 of the XBG.

la

protected long la

Per-instance LCG additive parameter (must be odd). Cannot be final to support RestorableUniformRandomProvider.

ls

protected long ls

State of the LCG generator.

Constructor Details

L64X128StarStar

public L64X128StarStar(long[] 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.

L64X128StarStar

public L64X128StarStar(long seed0,
 long seed1,
 long seed2,
 long 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.

L64X128StarStar

protected L64X128StarStar(L64X128StarStar source)

Creates a copy instance.

Parameters:

source - Source to copy.

Method Details

next

public long next()

Return the next random value.

Specified by:

next in interface RandomLongSource

Returns:

the next random value.

copy

protected L64X128StarStar copy()

Create a copy.

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.

getStateInternal

protected byte[] getStateInternal()

Creates a snapshot of the RNG state.

Returns:

the internal state.

setStateInternal

protected void setStateInternal(byte[] s)

Resets the RNG to the given state.

Parameters:

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

See Also:

• BaseProvider.checkStateSize(byte[],int)

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

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

Returns:

A copy of the current state.