Package org.apache.commons.rng

Interface ArbitrarilyJumpableUniformRandomProvider

All Superinterfaces:

UniformRandomProvider

public interface ArbitrarilyJumpableUniformRandomProvider
extends UniformRandomProvider

Applies to generators that can be advanced an arbitrary number of steps of the output sequence in a single operation.

Implementations must ensure that a jump of a specified distance will advance the state cycle sufficiently that an equivalent number of sequential calls to the original provider will not overlap output from the advanced provider.

For many applications, it suffices to jump forward by a power of two or some small multiple of a power of two, but this power of two may not be representable as a long value. To avoid the use of BigInteger values as jump distances, double values are used instead.

Typical usage in a multithreaded application is to create a single ArbitrarilyJumpableUniformRandomProvider and jump the generator forward while passing each copy generator to a worker thread. The jump distance should be sufficient to cover all expected output by each worker. Since each copy generator is also an ArbitrarilyJumpableUniformRandomProvider with care it is possible to further distribute generators within the original jump distance and use the entire state cycle in different ways.

Since:

1.7

Method Summary

Modifier and Type	Method	Description
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.
default Stream<ArbitrarilyJumpableUniformRandomProvider>	jumps(double distance)	Returns an effectively unlimited stream of new random generators, each of which implements the ArbitrarilyJumpableUniformRandomProvider interface.
default Stream<ArbitrarilyJumpableUniformRandomProvider>	jumps(long streamSize, double distance)	Returns a stream producing the given streamSize number of new random generators, each of which implements the ArbitrarilyJumpableUniformRandomProvider interface.

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

Method Detail

jump

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.

Parameters:

distance - Distance to jump forward with the state cycle.

Returns:

A copy of the current state.

Throws:

IllegalArgumentException - if distance is negative, or is greater than the period of this generator.

jumpPowerOfTwo

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.

Parameters:

logDistance - Base-2 logarithm of the distance to jump forward with the state cycle.

Returns:

A copy of the current state.

Throws:

IllegalArgumentException - if 2^logDistance is greater than the period of this generator.

jumps

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

Parameters:

distance - Distance to jump forward with the state cycle.

Returns:

a stream of random generators.

Throws:

IllegalArgumentException - if distance is negative, or is greater than the period of this generator.

jumps

default Stream<ArbitrarilyJumpableUniformRandomProvider> jumps(long streamSize,
                                                               double distance)

Returns a stream producing the given streamSize number 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.

Parameters:

streamSize - Number of objects to generate.

distance - Distance to jump forward with the state cycle.

Returns:

a stream of random generators; the stream is limited to the given streamSize.

Throws:

IllegalArgumentException - if streamSize is negative; or if distance is negative, or is greater than the period of this generator.