[jira] [Commented] (RNG-176) Enhance the UniformRandomProvider interface with extra methods and default implementations

["Gilles Sadowski (Jira)" <ji...@apache.org>]

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

Gilles Sadowski commented on RNG-176:
-------------------------------------

{quote}
I propose to:
# Add the new methods for streams and numbers in a range.
{quote}

This would duplicate non-trivial functionality (e.g. the optimized instances created for specific ranges) defined in "commons-rng-sampling".

bq. [...] Commons RNG interface can avoid the distribution sampling methods.

+1


> Enhance the UniformRandomProvider interface with extra methods and default implementations
> ------------------------------------------------------------------------------------------
>
>                 Key: RNG-176
>                 URL: https://issues.apache.org/jira/browse/RNG-176
>             Project: Commons RNG
>          Issue Type: New Feature
>    Affects Versions: 1.4
>            Reporter: Alex Herbert
>            Assignee: Alex Herbert
>            Priority: Major
>
> JDK 17 introduced the {{RandomGenerator}} interface with the following methods:
> {code:java}
> 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();
> {code}
> 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|
> h3. Note 1
> The UniformRandomProvider also has the method:
> {code:java}
> void nextBytes(byte[] bytes,
>                int start,
>                int len);
> {code}
> This can also have a default implementation using the output from nextLong().
> h3. 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.
>  



--
This message was sent by Atlassian Jira
(v8.20.7#820007)