java.lang.Object
- org.apache.commons.rng.core.BaseProvider
- - org.apache.commons.rng.core.source64.LongProvider
  - - org.apache.commons.rng.core.source64.L128X128Mix

All Implemented Interfaces:

RandomLongSource, org.apache.commons.rng.JumpableUniformRandomProvider, org.apache.commons.rng.LongJumpableUniformRandomProvider, org.apache.commons.rng.RestorableUniformRandomProvider, org.apache.commons.rng.SplittableUniformRandomProvider, org.apache.commons.rng.UniformRandomProvider
```
public class L128X128Mix
extends LongProvider
implements org.apache.commons.rng.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 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 384 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
`protected long`	`lah`	High half of the 128-bit per-instance LCG additive parameter.
`protected long`	`lal`	Low half of the 128-bit per-instance LCG additive parameter (must be odd).
`protected long`	`lsh`	High half of the 128-bit state of the LCG generator.
`protected long`	`lsl`	Low half of the 128-bit state of the LCG generator.

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 Instance Methods Concrete Methods
Modifier and Type	Method	Description
`protected byte[]`	`getStateInternal()`	Creates a snapshot of the RNG state.
`org.apache.commons.rng.UniformRandomProvider`	`jump()`	Creates a copy of the UniformRandomProvider and then retreats the state of the current instance.
`org.apache.commons.rng.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`.
`org.apache.commons.rng.SplittableUniformRandomProvider`	`split(org.apache.commons.rng.UniformRandomProvider source)`
`Stream<org.apache.commons.rng.SplittableUniformRandomProvider>`	`splits(long streamSize, org.apache.commons.rng.SplittableUniformRandomProvider source)`

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
  - lah
```
protected long lah
```
    High half of the 128-bit per-instance LCG additive parameter. Cannot be final to support RestorableUniformRandomProvider.
  - lal
```
protected long lal
```
    Low half of the 128-bit per-instance LCG additive parameter (must be odd). Cannot be final to support RestorableUniformRandomProvider.
  - lsh
```
protected long lsh
```
    High half of the 128-bit state of the LCG generator.
  - lsl
```
protected long lsl
```
    Low half of the 128-bit state of the LCG generator.
- 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 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.
  - 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 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.
    
    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.
    
    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)
  - next
```
public long next()
```
    Return the next random value.
    
    Specified by:
    
    next in interface RandomLongSource
    
    Returns:
    
    the next random value.
  - jump
```
public org.apache.commons.rng.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 org.apache.commons.rng.JumpableUniformRandomProvider
  - longJump
```
public org.apache.commons.rng.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 org.apache.commons.rng.LongJumpableUniformRandomProvider
  - split
```
public org.apache.commons.rng.SplittableUniformRandomProvider split(org.apache.commons.rng.UniformRandomProvider source)
```
    Specified by:
    
    split in interface org.apache.commons.rng.SplittableUniformRandomProvider
  - splits
```
public Stream<org.apache.commons.rng.SplittableUniformRandomProvider> splits(long streamSize,
                                                                             org.apache.commons.rng.SplittableUniformRandomProvider source)
```
    Specified by:
    
    splits in interface org.apache.commons.rng.SplittableUniformRandomProvider

Class L128X128Mix

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.apache.commons.rng.core.source64.LongProvider

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

Methods inherited from class java.lang.Object

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

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

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

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

Field Detail

lah

lal

lsh

lsl

Constructor Detail

L128X128Mix

L128X128Mix

L128X128Mix

Method Detail

getStateInternal

setStateInternal

next

jump

longJump

split

splits