Alex D Herbert created RNG-97:
---------------------------------
Summary: JumpableUniformRandomProvider
Key: RNG-97
URL: https://issues.apache.org/jira/browse/RNG-97
Project: Commons RNG
Issue Type: New Feature
Components: client-api, core
Affects Versions: 1.3
Reporter: Alex D Herbert
Assignee: Alex D Herbert
Fix For: 1.3
A feature of random number generators is their internal state is updated for
every generation of a new random number. This is a single step. Some generators
have the ability to compute the update to the state that is required to advance
*{{n}}* steps. This is a jump. This can be supported using a new interface:
{code:java}
/**
* Applies to generators that can be advanced a large number of
* steps of the output sequence in a single operation.
*/
public interface JumpableUniformRandomProvider
extends UniformRandomProvider {
/**
* Creates a copy of the UniformRandomProvider and advances the
* state of the copy. The state of the current instance is not altered.
* The state of the copy will be advanced an equivalent of {@code n}
* sequential calls to a method that updates the state of the provider.
*
* @return the copy with an advanced state
*/
JumpableUniformRandomProvider jump();
}
{code}
A suggestion for how to document an implementation is:
{code:java}
public class JumpableRNG implements JumpableUniformRandomProvider {
/**
* {@inheritDoc}
*
* <p>The jump size {@code n} is the equivalent of <pre>2<sup>32</sup></pre>
* calls to {@link UniformRandomProvider#nextLong() nextLong()}.</p>
*/
@Override
public JumpableUniformRandomProvider jump() {
return ...;
}
// etc.
}
{code}
Notes on the interface:
* A copy is returned
* The original is not altered and so multiple calls to jump will return the
same generator with an advanced state
The intended use case is to create multiple copies of a RNG that will not
overlap in sequence for use in parallel computations. A helper method can be
added to {{RandomSource}} to facilitate this:
{code:java}
/**
* Create a series of {@code n} generators by jumping from the source generator
* {@code n} times. The resulting set of generators can be used in parallel
* computations with a guarantee of no sequence overlap for at least the
* length of the jump distance.
*
* <p>Note: The source generator state is not affected. Reuse of this
* generator may overlap with output from the jump series.</p>
*
* @param source The source generator.
* @param n The size of the series.
*/
public static UniformRandomProvider[] createJumpSeries(
JumpableUniformRandomProvider source, int n) {
if (n <= 0) {
throw new IllegalArgumentException("Size must be strictly positive");
}
final UniformRandomProvider[] rngs = new UniformRandomProvider[n];
for (int i = 0; i < n; i++) {
source = source.jump();
// Option to wrap the JumpableUniformRandomProvider to
// restrict to the functionality of UniformRandomProvider
rngs[i] = source;
}
return rngs;
}
{code}
Note: There is the possibility to wrap the jumped RNGs to restrict their
functionality to UniformRandomProvider (or RestorableUniformRandomProvider).
This prevents any of the series from being jumped again.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
