Class 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 232 (264 - 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:
  • Field Details

    • M

      private static final int M
      LCG multiplier.
      See Also:
    • SEED_SIZE

      private static final int SEED_SIZE
      Size of the state vector.
      See Also:
    • la

      private int la
      Per-instance LCG additive parameter (must be odd). Cannot be final to support RestorableUniformRandomProvider.
    • ls

      private int ls
      State of the LCG generator.
    • x0

      private int x0
      State 0 of the XBG generator.
    • x1

      private int x1
      State 1 of the XBG generator.
  • Constructor Details

    • 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 232.

      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 232.

      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.
    • L32X64Mix

      private L32X64Mix(L32X64Mix source)
      Creates a copy instance.
      Parameters:
      source - Source to copy.
  • Method Details

    • setState

      private void setState(int[] state)
      Copies the state into the generator state.
      Parameters:
      state - the new state
    • 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:
    • next

      public int next()
      Return the next random value.
      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 (264 - 1) positions. It can provide up to 232 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 216 cycles. The XBG state is unchanged. The jump size is the equivalent of moving the state backwards by 216 (264 - 1) positions. It can provide up to 216 non-overlapping subsequences of length 216 (264 - 1); each subsequence can provide up to 216 non-overlapping subsequences of length (264 - 1) using the jump() method.

      Specified by:
      longJump in interface LongJumpableUniformRandomProvider
      Returns:
      A copy of the current state.
    • split

      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.