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] [Commented] (RNG-97) JumpableUniformRandomProvider
Date Sat, 27 Apr 2019 20:24:00 GMT

    [ https://issues.apache.org/jira/browse/RNG-97?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16827748#comment-16827748
] 

Alex D Herbert commented on RNG-97:
-----------------------------------

All valid points.

Having formalised the ideas from the dev mailing list to form this ticket I am not sure this
is the best implementation. The need to create a series by chaining the return values has
resulted in a helper method in RandomSource to create a series of known length. This does
not support creating an open ended series of unknown size (as if a Java 8 function Supplier<UniformRandomProvider>)
or creating two series from the same parent without extra code to regain the reference to
the terminal jump point.

I'll take the discussion back to the mailing list.

> 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
>            Priority: Major
>             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