Details
-
New Feature
-
Status: Closed
-
Major
-
Resolution: Implemented
-
1.4
-
None
-
Easy
Description
JDK 17 introduced the RandomGenerator interface with the following methods:
DoubleStream doubles(); DoubleStream doubles(double randomNumberOrigin, double randomNumberBound); DoubleStream doubles(long streamSize); DoubleStream doubles(long streamSize, double randomNumberOrigin, double randomNumberBound); IntStream ints(); IntStream ints(int randomNumberOrigin, int randomNumberBound); IntStream ints(long streamSize); IntStream ints(long streamSize, int randomNumberOrigin, int randomNumberBound); LongStream longs(); LongStream longs(long randomNumberOrigin, long randomNumberBound); LongStream longs(long streamSize); LongStream longs(long streamSize, long randomNumberOrigin, long randomNumberBound); boolean nextBoolean(); void nextBytes(byte[] bytes); float nextFloat(); float nextFloat(float bound); float nextFloat(float origin, float bound); double nextDouble(); double nextDouble(double bound); double nextDouble(double origin, double bound); int nextInt(); int nextInt(int bound); int nextInt(int origin, int bound); long nextLong(); long nextLong(long bound); long nextLong(long origin, long bound); double nextGaussian(); double nextGaussian(double mean, double stddev); double nextExponential();
The only method that is non-default is nextLong. This allows a new generator to be simply implemented by providing the source of randomness as 64-bit longs.
The UniformRandomProvider interface can be expanded to include these generation methods. Using Java 8 default interface methods will not require any changes to generators currently implementing the interface.
I propose to:
- Add the new methods for streams and numbers in a range.
- Add default implementations of the current API. These can be extracted from the o.a.c.rng.core.BaseProvider implementations.
- Remove the implementations in o.a.c.rng.core.BaseProvider. This change would be binary compatible.
The base classes in commons core for 32-bit and 64-bit sources of randomness, IntProvider and LongProvider, can be updated suitably to only override the default interface methods where they can be more efficiently implemented given the source of randomness. This applies to:
| Source | Update | Details |
|---|---|---|
| int | nextBytes | Use nextInt() for the source of bytes |
| nextBoolean | Use a cached int for the randomness | |
| nextInt | Directly supply the int rather than using 32-bits from nextLong() | |
| nextDouble | Optimise the bits used from two ints for the 53-bits required for the double. | |
| long | nextInt; nextBoolean | Use a cached long for the randomness |
Note 1
The UniformRandomProvider also has the method:
void nextBytes(byte[] bytes, int start, int len);
This can also have a default implementation using the output from nextLong().
Note 2
The methods to generate an exponential and Gaussian are already implemented in the commons-rng-sampling module.
java.util.Random has a nextGaussian() method and so this method appears to be for backward compatibility with legacy Java code. The method is implemented using a modified Ziggurat sampler which uses an exponential sampler for the long tail. The API has thus exposed the exponential sampling method that is used internally in the nextGaussian implementation.
With no backward compatibility requirements the Commons RNG interface can avoid the distribution sampling methods. Users should select an appropriate sampler from the sampling module.
