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 2¹³⁰.

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

Field Summary

Fields

Modifier and Type	Field	Description
private int[]	buffer	Output buffer.
private int	bufferPosition	Output buffer index.
private int	counter0	Counter 0.
private int	counter1	Counter 1.
private int	counter2	Counter 2.
private int	counter3	Counter 3.
private static int	K_PHILOX_10_A	Philox 32-bit mixing constant for counter 0.
private static int	K_PHILOX_10_B	Philox 32-bit mixing constant for counter 1.
private static int	K_PHILOX_SA	Philox 32-bit constant for key 0.
private static int	K_PHILOX_SB	Philox 32-bit constant for key 1.
private int	key0	Key low bits.
private int	key1	Key high bits.
private static int	LOG_PERIOD	The base-2 logarithm of the period.
private static double	PERIOD	The period of 2^130 as a double.
private static int	PHILOX_BUFFER_SIZE	Internal buffer size.
private static int	STATE_SIZE	Number of state variables.
private static double	TWO_POW_54	2^54.

Constructor Summary

Constructors

Modifier	Constructor	Description
	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).
private	Philox4x32(Philox4x32 source)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
private ArbitrarilyJumpableUniformRandomProvider	copyAndJump(int skip, int[] increment)	Copy the generator and advance the internal state.
private void	finishJump()	Finish the jump of this generator.
private static int	getBufferPositionIncrement(double distance)	Gets the buffer position increment from the jump distance.
private static int[]	getCounterIncrement(double distance)	Gets the counter increment from the jump distance.
protected byte[]	getStateInternal()	Creates a snapshot of the RNG state.
private void	incrementCounter()	Increment the counter by one.
UniformRandomProvider	jump()	Creates a copy of the UniformRandomProvider and then advances the state of the current instance.
ArbitrarilyJumpableUniformRandomProvider	jump(double distance)	Creates a copy of the ArbitrarilyJumpableUniformRandomProvider and then advances the state cycle of the current instance by the specified distance.
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.
java.util.stream.Stream<ArbitrarilyJumpableUniformRandomProvider>	jumps(double distance)	Returns an effectively unlimited stream of new random generators, each of which implements the ArbitrarilyJumpableUniformRandomProvider interface.
JumpableUniformRandomProvider	longJump()	Creates a copy of the JumpableUniformRandomProvider and then advances the state of the current instance.
int	next()	Return the next random value.
private void	rand10()	Perform 10 rounds, using counter0, counter1, counter2, counter3 as starting point.
private void	setState(int[] state)	Copies the state from the array into the generator state.
protected void	setStateInternal(byte[] s)	Resets the RNG to the given state.
private static void	singleRound(int[] counter, int key0, int key1)	Performs a single round of philox.

Methods inherited from class org.apache.commons.rng.core.source32.IntProvider

nextBoolean, nextBytes, nextBytes, nextBytesFill, nextDouble, 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.ArbitrarilyJumpableUniformRandomProvider

jumps

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

doubles, doubles, doubles, doubles, ints, ints, ints, ints, longs, longs, longs, longs, nextBoolean, nextBytes, nextBytes, nextDouble, nextDouble, nextDouble, nextFloat, nextFloat, nextFloat, nextInt, nextInt, nextInt, nextLong, nextLong, nextLong

Field Detail

K_PHILOX_10_A

private static final int K_PHILOX_10_A

Philox 32-bit mixing constant for counter 0.

See Also:

Constant Field Values

K_PHILOX_10_B

private static final int K_PHILOX_10_B

Philox 32-bit mixing constant for counter 1.

See Also:

Constant Field Values

K_PHILOX_SA

private static final int K_PHILOX_SA

Philox 32-bit constant for key 0.

See Also:

Constant Field Values

K_PHILOX_SB

private static final int K_PHILOX_SB

Philox 32-bit constant for key 1.

See Also:

Constant Field Values

PHILOX_BUFFER_SIZE

private static final int PHILOX_BUFFER_SIZE

Internal buffer size.

See Also:

Constant Field Values

STATE_SIZE

private static final int STATE_SIZE

Number of state variables.

See Also:

Constant Field Values

LOG_PERIOD

private static final int LOG_PERIOD

The base-2 logarithm of the period.

See Also:

Constant Field Values

PERIOD

private static final double PERIOD

The period of 2^130 as a double.

See Also:

Constant Field Values

TWO_POW_54

private static final double TWO_POW_54

2^54. Threshold for a double that cannot have the 2 least significant bits set when converted to a long.

See Also:

Constant Field Values

counter0

private int counter0

Counter 0.

counter1

private int counter1

Counter 1.

counter2

private int counter2

Counter 2.

counter3

private int counter3

Counter 3.

buffer

private final int[] buffer

Output buffer.

key0

private int key0

Key low bits.

key1

private int key1

Key high bits.

bufferPosition

private int bufferPosition

Output buffer index. When at the end of the buffer the counter is incremented and the buffer regenerated.

Constructor Detail

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.

Philox4x32

private Philox4x32(Philox4x32 source)

Copy constructor.

Parameters:

source - Source to copy.

Method Detail

setState

private void setState(int[] state)

Copies the state from the array into the generator state.

Parameters:

state - 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:

BaseProvider.checkStateSize(byte[],int)

next

public int next()

Return the next random value.

Specified by:

next in interface RandomIntSource

Returns:

the next random value.

incrementCounter

private void incrementCounter()

Increment the counter by one.

rand10

private void rand10()

Perform 10 rounds, using counter0, counter1, counter2, counter3 as starting point. It updates the buffer member variable, but no others.

singleRound

private static void singleRound(int[] counter,
                                int key0,
                                int key1)

Performs a single round of philox.

Parameters:

counter - Counter, which will be updated after each call.

key0 - Key low bits.

key1 - Key high bits.

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 2⁶⁶ calls to nextInt(). 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 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 2⁹⁸ calls to nextLong(). It can provide up to 2³² non-overlapping subsequences of length 2⁹⁸; each subsequence can provide up to 2³² non-overlapping subsequences of length 2⁶⁶ 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 2^logDistance. 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 2^logDistance 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 java.util.stream.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.

getBufferPositionIncrement

private static int getBufferPositionIncrement(double distance)

Gets the buffer position increment from the jump distance.

Parameters:

distance - Jump distance.

Returns:

the buffer position increment

getCounterIncrement

private static int[] getCounterIncrement(double distance)

Gets the counter increment from the jump distance.

Parameters:

distance - Jump distance.

Returns:

the counter increment

copyAndJump

private ArbitrarilyJumpableUniformRandomProvider copyAndJump(int skip,
                                                             int[] increment)

Copy the generator and advance the internal state. The copy is returned.

This method: (1) assumes that the arguments have been validated; and (2) regenerates the output buffer if required.

Parameters:

skip - Amount to skip the buffer position in [0, 3].

increment - Unsigned 128-bit increment, least significant bits first.

Returns:

the copy

finishJump

private void finishJump()

Finish the jump of this generator. Resets the cached state and regenerates the output buffer if required.