Class L128X128Mix
- 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.L128X128Mix
-
- All Implemented Interfaces:
RandomLongSource
,JumpableUniformRandomProvider
,LongJumpableUniformRandomProvider
,RestorableUniformRandomProvider
,SplittableUniformRandomProvider
,UniformRandomProvider
public class L128X128Mix 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 128-bit Xor-based generator. It is named as
"L128X128MixRandom"
in thejava.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 384 bits and the period is 2128 (2128 - 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 thesplits
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 static long
ML
Low half of 128-bit LCG multiplier.private static int
SEED_SIZE
Size of the seed vector.private long
x0
State 0 of the XBG.private long
x1
State 1 of the XBG.private static int
XBG_STATE_SIZE
Size of the XBG state vector.-
Fields inherited from class org.apache.commons.rng.core.source64.AbstractL128
lah, lal, lsh, lsl
-
-
Constructor Summary
Constructors Modifier Constructor Description L128X128Mix(long[] seed)
Creates a new instance.L128X128Mix(long seed0, long seed1, long seed2, long seed3, long seed4, long seed5)
Creates a new instance using a 6 element seed.protected
L128X128Mix(L128X128Mix source)
Creates a copy instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods 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 givenseed
andsource
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 givenstate
.SplittableUniformRandomProvider
split(UniformRandomProvider source)
Creates a new random generator, split off from this one, that implements theSplittableUniformRandomProvider
interface.java.util.stream.Stream<SplittableUniformRandomProvider>
splits(long streamSize, SplittableUniformRandomProvider source)
Returns a stream producing the givenstreamSize
number of new random generators, each of which implements theSplittableUniformRandomProvider
interface.-
Methods inherited from class org.apache.commons.rng.core.source64.LongProvider
nextBoolean, 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
-
-
-
-
Field Detail
-
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
-
ML
private static final long ML
Low half of 128-bit LCG multiplier.- See Also:
- Constant Field Values
-
x0
private long x0
State 0 of the XBG.
-
x1
private long x1
State 1 of the XBG.
-
-
Constructor Detail
-
L128X128Mix
public L128X128Mix(long[] seed)
Creates a new instance.- Parameters:
seed
- Initial seed. If the length is larger than 6, only the first 6 elements will be used; if smaller, the remaining elements will be automatically set. A seed containing all zeros in the last four elements will create a non-functional XBG sub-generator and a low quality output with a period of 2128.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.
-
L128X128Mix
public L128X128Mix(long seed0, long seed1, long seed2, long seed3, long seed4, long seed5)
Creates a new instance using a 6 element seed. A seed containing all zeros in the last four elements will create a non-functional XBG sub-generator and a low quality output with a period of 2128.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.
- Parameters:
seed0
- Initial seed element 0.seed1
- Initial seed element 1.seed2
- Initial seed element 2.seed3
- Initial seed element 3.seed4
- Initial seed element 4.seed5
- Initial seed element 5.
-
L128X128Mix
protected L128X128Mix(L128X128Mix source)
Creates a copy instance.- Parameters:
source
- Source to copy.
-
-
Method Detail
-
getStateInternal
protected byte[] getStateInternal()
Creates a snapshot of the RNG state.- Overrides:
getStateInternal
in classAbstractL128
- Returns:
- the internal state.
-
setStateInternal
protected void setStateInternal(byte[] s)
Resets the RNG to the givenstate
.- Overrides:
setStateInternal
in classAbstractL128
- Parameters:
s
- State (previously obtained by a call toBaseProvider.getStateInternal()
).- See Also:
BaseProvider.checkStateSize(byte[],int)
-
next
public long next()
Return the next random value.- Specified by:
next
in interfaceRandomLongSource
- 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 (2128 - 1) positions. It can provide up to 2128 non-overlapping subsequences.
- Specified by:
jump
in interfaceJumpableUniformRandomProvider
- Overrides:
jump
in classAbstractL128
- 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 264 cycles. The XBG state is unchanged.
The jump size is the equivalent of moving the state backwards by 264 (2128 - 1) positions. It can provide up to 264 non-overlapping subsequences of length 264 (2128 - 1); each subsequence can provide up to 264 non-overlapping subsequences of length (2128 - 1) using the
jump()
method.- Specified by:
longJump
in interfaceLongJumpableUniformRandomProvider
- Overrides:
longJump
in classAbstractL128
- Returns:
- A copy of the current state.
-
copy
AbstractL128 copy()
Create a copy.- Specified by:
copy
in classAbstractL128
- Returns:
- the copy
-
split
public SplittableUniformRandomProvider split(UniformRandomProvider source)
Creates a new random generator, split off from this one, that implements theSplittableUniformRandomProvider
interface.- Specified by:
split
in interfaceSplittableUniformRandomProvider
- Parameters:
source
- A source of randomness used to initialise the new instance.- Returns:
- A new instance.
-
splits
public java.util.stream.Stream<SplittableUniformRandomProvider> splits(long streamSize, SplittableUniformRandomProvider source)
Returns a stream producing the givenstreamSize
number of new random generators, each of which implements theSplittableUniformRandomProvider
interface.- Specified by:
splits
in interfaceSplittableUniformRandomProvider
- 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 givenseed
andsource
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.
-
-