commons-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Alex D Herbert (JIRA)" <j...@apache.org>
Subject [jira] [Created] (RNG-97) JumpableUniformRandomProvider
Date Sat, 27 Apr 2019 12:36:00 GMT
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)

Mime
View raw message