Package org.apache.commons.rng.core.source32

Class Philox4x32

java.lang.Object
org.apache.commons.rng.core.BaseProvider
org.apache.commons.rng.core.source32.IntProvider
org.apache.commons.rng.core.source32.Philox4x32
All Implemented Interfaces:
ArbitrarilyJumpableUniformRandomProvider, RandomIntSource, JumpableUniformRandomProvider, LongJumpableUniformRandomProvider, RestorableUniformRandomProvider, UniformRandomProvider
public final class Philox4x32 extends IntProvider implements LongJumpableUniformRandomProvider, ArbitrarilyJumpableUniformRandomProvider
This class implements the Philox4x32 128-bit counter-based generator with 10 rounds.

This is a member of the Philox family of generators. Memory footprint is 192 bits and the period is 2130.

Jumping in the sequence is essentially instantaneous. This generator provides both subsequences and arbitrary jumps for easy parallelization.

References:

  1. Salmon, J.K. et al (2011) Parallel Random Numbers: As Easy as 1,2,3.
Since:
1.7

  • Constructor Details

    • Philox4x32

      public Philox4x32(int[] seed)
      Creates a new instance based on an array of int containing, key (first two ints) and the counter (next 4 ints, low bits = first int). The counter is not scrambled and may be used to create contiguous blocks with size a multiple of 4 ints. For example, setting seed[2] = 1 is equivalent to start with seed[2]=0 and calling next() 4 times.
      Parameters:
      seed - Array of size 6 defining key0,key1,counter0,counter1,counter2,counter3. If the size is smaller, zero values are assumed.

  • Method Details

    • 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 advances the state of the current instance. The copy is returned.

      The current state will be advanced in a single operation by the equivalent of a number of sequential calls to a method that updates the state of the provider. The size of the jump is implementation dependent.

      Repeat invocations of this method will create a series of generators that are uniformly spaced at intervals of the output sequence. Each generator provides non-overlapping output for the length of the jump for use in parallel computations.

      The jump size is the equivalent of 266 calls to nextInt(). It can provide up to 264 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 JumpableUniformRandomProvider and then advances the state of the current instance. The copy is returned.

      The current state will be advanced in a single operation by the equivalent of a number of sequential calls to a method that updates the state of the provider. The size of the long jump is implementation dependent.

      Repeat invocations of this method will create a series of generators that are uniformly spaced at intervals of the output sequence. Each generator provides non-overlapping output for the length of the long jump for use in parallel computations.

      The returned copy may be jumped m / n times before overlap with the current instance where m is the long jump length and n is the jump length of the JumpableUniformRandomProvider.jump() method.

      The jump size is the equivalent of 298 calls to nextLong(). It can provide up to 232 non-overlapping subsequences of length 298; each subsequence can provide up to 232 non-overlapping subsequences of length 266 using the jump() method.

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

    • jump

      public ArbitrarilyJumpableUniformRandomProvider jump(double distance)
      Creates a copy of the ArbitrarilyJumpableUniformRandomProvider and then advances the state cycle of the current instance by the specified distance. The copy is returned.

      The current state will be advanced in a single operation by the equivalent of a number of sequential calls to a method that updates the state cycle of the provider.

      Repeat invocations of this method will create a series of generators that are uniformly spaced at intervals of the output sequence. Each generator provides non-overlapping output for the length specified by distance for use in parallel computations.

      Specified by:
      jump in interface ArbitrarilyJumpableUniformRandomProvider
      Parameters:
      distance - Distance to jump forward with the state cycle.
      Returns:
      A copy of the current state.

    • jumpPowerOfTwo

      public ArbitrarilyJumpableUniformRandomProvider jumpPowerOfTwo(int logDistance)
      Creates a copy of the ArbitrarilyJumpableUniformRandomProvider and then advances the state cycle of the current instance by a distance equal to 2logDistance. The copy is returned.

      The current state will be advanced in a single operation by the equivalent of a number of sequential calls to a method that updates the state cycle of the provider.

      Repeat invocations of this method will create a series of generators that are uniformly spaced at intervals of the output sequence. Each generator provides non-overlapping output for the length specified by 2logDistance for use in parallel computations.

      Specified by:
      jumpPowerOfTwo in interface ArbitrarilyJumpableUniformRandomProvider
      Parameters:
      logDistance - Base-2 logarithm of the distance to jump forward with the state cycle.
      Returns:
      A copy of the current state.

    • jumps

      public Stream<ArbitrarilyJumpableUniformRandomProvider> jumps(double distance)
      Returns an effectively unlimited stream of new random generators, each of which implements the ArbitrarilyJumpableUniformRandomProvider interface. The generators are output at integer multiples of the specified jump distance in the generator's state cycle.
      Specified by:
      jumps in interface ArbitrarilyJumpableUniformRandomProvider
      Parameters:
      distance - Distance to jump forward with the state cycle.
      Returns:
      a stream of random generators.