[
https://issues.apache.org/jira/browse/RNG-189?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18058493#comment-18058493
]
Alex Herbert commented on RNG-189:
----------------------------------
Note that the JDK interface also supports jumping by a power of 2. This would
typically be implemented much faster than jumping by other increments. It also
allows jumping by much further than the limit imposed by a double which is
approximately 2^1024.
I have added the following interface to the master branch using effectively the
same method functionality as the JDK but without explicit method separation of
the copy and jump functionality:
{code:java}
public interface ArbitrarilyJumpableUniformRandomProvider extends
UniformRandomProvider {
ArbitrarilyJumpableUniformRandomProvider jump(double distance);
ArbitrarilyJumpableUniformRandomProvider jumpPowerOfTwo(int logDistance);
default Stream<UniformRandomProvider> jumps(double distance) {
// ...
}
default Stream<UniformRandomProvider> jumps(long streamSize, double
distance) {
// ...
}
}{code}
The JDK javadoc allows to throw an exception if the jump distance is negative
or larger than the period of the generator. So it is possible to copy a
generator by using a jump distance of 0. I have documented the same limits in
the Commons RNG interface for consistency. A user jumping a zero distance will
not be warned of errors in their jump distance calculations.
Note that although you can jump by a power of 2 you cannot stream using power
of 2 jump distance. It would be simple to add this as a default method in the
future. It is implemented as:
{code:java}
Stream.generate(() -> jumpPowerOfTwo(logDistance)) {code}
I imagine that for practical usage jumping with a distance limit of 2^1023 is
enough for parallel applications. Jumping more than this using a larger power
of 2 is more for future compatibility with generators with very large period.
Added in commit:
c7c4db8c9ad0de4a0aa33eaafc9254fd7134352b
> Add interface ArbitrarilyJumpableGenerator
> ------------------------------------------
>
> Key: RNG-189
> URL: https://issues.apache.org/jira/browse/RNG-189
> Project: Commons RNG
> Issue Type: New Feature
> Components: client-api
> Reporter: Alex Herbert
> Priority: Minor
>
> Add an interface to allow a generator to jump an arbitrary distance in its
> output period.
> This would be the equivalent of the interface from JDK 17+
> {{java.util.random}} package:
> [RandomGenerator.ArbitrarilyJumpableGenerator (Javadoc JDK
> 25)|https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/random/RandomGenerator.ArbitrarilyJumpableGenerator.html]
> The jump distance in that interface is specified as a double to avoid the use
> of BigInteger for large jump distances. The JDK interfaces specify copy, jump
> and copyAndJump. However Commons RNG does not support easy copying of a
> generator to avoid common pitfalls of outputting the same sequence in
> multiple threads via a copy.
> The simplest API would be similar to the Commons RNG Jumpable interface with
> the addition of a distance argument:
> {code:java}
> public interface ArbitrarilyJumpableUniformRandomProvider extends
> UniformRandomProvider {
> ArbitrarilyJumpableUniformRandomProvider jump(double distance);
> default Stream<UniformRandomProvider> jumps(double distance) {
> // ...
> }
> default Stream<UniformRandomProvider> jumps(long streamSize, double
> distance) {
> // ...
> }
> }
> {code}
> Note that the return value of a generator from the jump method makes this
> interface incompatible with the JDK's which returns void. However the
> existing Commons RNG jumping interfaces, which predate the JDK 17 release,
> are also incompatible. Any future update with minimum Java 17 support will
> have to address compatibility.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
