[jira] [Created] (RNG-98) LongJumpableUniformRandomProvider

["Alex D Herbert (JIRA)" <ji...@apache.org>]

Alex D Herbert created RNG-98:
---------------------------------

             Summary: LongJumpableUniformRandomProvider
                 Key: RNG-98
                 URL: https://issues.apache.org/jira/browse/RNG-98
             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


The {{JumpableUniformRandomProvider}} allows the state of a generator to be advanced in a large jump of *{{n}}* steps to allow a series of generators to be created at regularly spaced intervals. These can be used in parallel computations without overlap for at least *{{n}}* outputs of the generator.

Extend the interface to allow a larger jump:
{code:java}
/**
 * Applies to generators that can be advanced a very large number of 
 * steps of the output sequence in a single operation.
 */
public interface LongJumpableUniformRandomProvider
    extends JumpableUniformRandomProvider {
    /**
     * 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 m}
     * sequential calls to a method that updates the state of the provider.
     *
     * <p>Note: The output will not overlap with {@code m / n} sequentially
     * created instances of the {@link #jump()} method where {@code n} is the
     * jump length of the {@link #jump()} method.</p>
     *
     * @return the copy with an advanced state
     */
    LongJumpableUniformRandomProvider longJump();
}
{code}
This interface is to support a tiered parallel computation. The top tier is created using long jumps. Each top tier generator can create a large number of generators using the jump method.

A suggestion for how to document an implementation is:
{code:java}
public class LongJumpableRNG implements LongJumpableUniformRandomProvider {
    /**
     * {@inheritDoc}
     *
     * <p>The jump size {@code m} is the equivalent of <pre>2<sup>64</sup></pre>
     * calls to {@link UniformRandomProvider#nextLong() nextLong()}. The output
     * will not overlap with <pre>2<sup>32</sup></pre> sequentially created
     * instances of the {@link #jump()} method.</p>
     */
    @Override
    public LongJumpableUniformRandomProvider longJump() {
        return ...;
    }

    // etc.
}
{code}



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)