[RNG-98] LongJumpableUniformRandomProvider

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Implemented
• Affects Version/s: 1.3
• Fix Version/s: 1.3
• Component/s: client-api, core
• Assignee: Alex Herbert
• Reporter: Alex Herbert
• Created: 27/Apr/19 12:59
• Updated: 11/Nov/19 14:26
• Resolved: 11/Jun/19 22:35

Description

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:

/**
 * 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();
}

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:

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

Issue Links

• links to: GitHub Pull Request #49