Package org.apache.commons.rng.core.source64

Class Philox4x64

java.lang.Object

org.apache.commons.rng.core.BaseProvider

org.apache.commons.rng.core.source64.LongProvider

org.apache.commons.rng.core.source64.Philox4x64

All Implemented Interfaces:

ArbitrarilyJumpableUniformRandomProvider, RandomLongSource, JumpableUniformRandomProvider, LongJumpableUniformRandomProvider, RestorableUniformRandomProvider, UniformRandomProvider

public final class Philox4x64
extends LongProvider
implements LongJumpableUniformRandomProvider, ArbitrarilyJumpableUniformRandomProvider

This class implements the Philox4x64 256-bit counter-based generator with 10 rounds.

This is a member of the Philox family of generators. Memory footprint is 384 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 long[]	buffer	Output buffer.
private int	bufferPosition	Output buffer index.
private long	counter0	Counter 0.
private long	counter1	Counter 1.
private long	counter2	Counter 2.
private long	counter3	Counter 3.
private long	key0	Key low bits.
private long	key1	Key high bits.
private static int	LOG_PERIOD	The base-2 logarithm of the period.
private static double	PERIOD	The period of 2^258 as a double.
private static int	PHILOX_BUFFER_SIZE	Internal buffer size.
private static long	PHILOX_M0	Philox 64-bit mixing constant for counter 0.
private static long	PHILOX_M1	Philox 64-bit mixing constant for counter 1.
private static long	PHILOX_W0	Philox 64-bit constant for key 0.
private static long	PHILOX_W1	Philox 64-bit constant for key 1.
private static int	STATE_SIZE	Number of state variables.
private static double	TWO_POW_54	2^54.

Constructor Summary

Constructors

Modifier	Constructor	Description
	Philox4x64(long[] seed)	Creates a new instance given 6 long numbers containing, key (first two longs) and the counter (next 4 longs, low bits = first long).
private	Philox4x64(Philox4x64 source)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
private ArbitrarilyJumpableUniformRandomProvider	copyAndJump(int skip, long[] 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 long[]	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.
long	next()	Return the next random value.
private void	rand10()	Perform 10 rounds, using counter0, counter1, counter2, counter3 as starting point.
private void	setState(long[] 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(long[] counter, long key0, long key1)	Performs a single round of philox.

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

PHILOX_M0

private static final long PHILOX_M0

Philox 64-bit mixing constant for counter 0.

See Also:

Constant Field Values

PHILOX_M1

private static final long PHILOX_M1

Philox 64-bit mixing constant for counter 1.

See Also:

Constant Field Values

PHILOX_W0

private static final long PHILOX_W0

Philox 64-bit constant for key 0.

See Also:

Constant Field Values

PHILOX_W1

private static final long PHILOX_W1

Philox 64-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^258 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 long counter0

Counter 0.

counter1

private long counter1

Counter 1.

counter2

private long counter2

Counter 2.

counter3

private long counter3

Counter 3.

buffer

private final long[] buffer

Output buffer.

key0

private long key0

Key low bits.

key1

private long 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

Philox4x64

public Philox4x64(long[] seed)

Creates a new instance given 6 long numbers containing, key (first two longs) and the counter (next 4 longs, low bits = first long). The counter is not scrambled and may be used to create contiguous blocks with size a multiple of 4 longs. 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.

Philox4x64

private Philox4x64(Philox4x64 source)

Copy constructor.

Parameters:

source - Source to copy.

Method Detail

setState

private void setState(long[] 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 LongProvider

Returns:

the internal state.

setStateInternal

protected void setStateInternal(byte[] s)

Resets the RNG to the given state.

Overrides:

setStateInternal in class LongProvider

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.

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(long[] counter,
                                long key0,
                                long 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 nextLong(). 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)

Description copied from interface: ArbitrarilyJumpableUniformRandomProvider

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)

Description copied from interface: ArbitrarilyJumpableUniformRandomProvider

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 long[] 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,
                                                             long[] 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 256-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.