[ https://issues.apache.org/jira/browse/RNG-176?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Alex Herbert updated RNG-176: ----------------------------- Component/s: client-api > 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 > Components: client-api > Affects Versions: 1.4 > Reporter: Alex Herbert > Assignee: Alex Herbert > Priority: Major > Fix For: 1.5 > > Time Spent: 50m > Remaining Estimate: 0h > > 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.10#820010)