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

Alex Herbert commented on RNG-178:
----------------------------------

{quote}Why would one write such code rather than "manually" select a generator 
that fits the bill?
{quote}
I do not think a user would do this. So this is not required.

For context in the JDK 17 API the random providers are discovered using a SPI. 
In that context having the ability to stream all implementations and filter 
them based on features may be useful. For example there are properties in the 
RandomGeneratorFactory for:
||Property||Add to RandomSource||
|isDeprecated|Is possible|
|isStatistical|NA. Currently all generators are deterministic|
|isStochastic|NA. Currently no generators use an external source of entropy|
|isHardware|NA. Hardware is not supported|
|isStreamable|Would require a Streamable interface to make sense|
|isJumpable|Already present|
|isSplittable|Would require a Splittable interface to make sense|
|isLeapable|Already present (isLongJumpable)|
|isArbitrarilyJumpable|Not currently supported. Some generators could be (e.g 
linear congrutential generators; Weyl sequence generators) but the arbitrary 
jump distance would be small as these generators have a period of 2^64. Note 
the JDK interface distance is specified using a double or a power of 2. The 
interface recommends to have a period of at least 2^127.|
|stateBits|Is possible|
|period|Unknown for all generators|
|equidistribution|Unknown for all generators|
|group|Is possible|

Some of these are not provided by the JDK (e.g. hardware, ArbitrarilyJumpable). 
So a library may wish to stream all providers to determine for example if there 
is a hardware source of randomness available, or choose the generator with the 
largest period.

When the RandomSource is effectively a static enum with a fixed set of 
implementations then performing filtering for a certain functionality 
(jumpable, jump distance, state period) does not make much sense. A developer 
using the library would know all implementations available at compile time and 
select one  based on statistical robustness, performance, equidistribution, 
jumpability, etc. IMO the more important of these criteria (statistical 
robustness and performance) are not represented in the JDK API, presumably 
because they are not readily definable. Perhaps it would be assumed that all 
non-deprecated generators are robust and performance is proportional to state 
size (which is only a good approximation within a family group).

The only reason to stream generators and filter in Commons RNG is if the 
library is upgraded and the user code is not. Then the code may be written to 
pick a generator based on desired functionality. This could pick up a newer 
implementation if it is a better match. The most likely scenarios are a 
generator with a larger period is available; or a new release has deprecated a 
generator that would previously have been selected.

Note that the isJumpable method in RandomSource is to allow safe inquiry that a 
RNG created from a source can be cast to an interface type before instantiating 
one. This is from the user guide:
{code:java}
public void initialise(RandomSource source) {
    if (!source.isJumpable()) {
        throw new IllegalArgumentException("Require a jumpable random source");
    }
    // ...
}
{code}
So perhaps we just maintain boolean properties for any additional interfaces 
that are added to the library for generators to implement specific 
functionality, e.g. Splittable.

 

> Add stream support to JumpableUniformRandomProvider
> ---------------------------------------------------
>
>                 Key: RNG-178
>                 URL: https://issues.apache.org/jira/browse/RNG-178
>             Project: Commons RNG
>          Issue Type: New Feature
>          Components: client-api
>    Affects Versions: 1.4
>            Reporter: Alex Herbert
>            Priority: Major
>             Fix For: 1.5
>
>
> The JumpableUniformRandomProvider can add default methods to allow a stream 
> of generators to be created:
> {code:java}
>     default Stream<UniformRandomProvider> jumps() {
>         return Stream.generate(this::jump).sequential();
>     }
>     default Stream<UniformRandomProvider> jumps(long streamSize) {
>         return jumps().limit(streamSize);
>     }
> {code}
> A similar method for the LongJumpableRandomGenerator can be provided.
> Note: This method is found in the [JDK 17 
> JumpableGenerator|https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGenerator.JumpableGenerator.html]
>  interface.
> Other methods from that interface cannot be added as they have no default 
> implementation. Note the JDK interface has separated the jump from the copy 
> operation:
> {code:java}
> RandomGenerator.JumpableGenerator copy();
> void jump();
> default RandomGenerator copyAndJump();
> double jumpDistance();
> static RandomGenerator.JumpableGenerator of(String name);
> {code}
> Note the factory method is achieved in Commons RNG using:
> {code:java}
> JumpableUniformRandomProvider rng = (JumpableUniformRandomProvider)
>     Arrays.stream(RandomSource.values())
>           .filter(RandomSource::isJumpable)
>           .findFirst()
>           .get().create();
> {code}
> This involves an explicit cast in user code. It may be desirable to formalise 
> this pattern by adding a Stream method to RandomSource:
> {code:java}
> public static Stream<RandomSource> stream();
> JumpableUniformRandomProvider rng = (JumpableUniformRandomProvider)
>     RandomSource.stream()
>                 .filter(RandomSource::isJumpable)
>                 .findFirst()
>                 .get().create();
> {code}
> Note that the jump distance is not provided by the Commons RNG API. It cannot 
> be added to the interface due to binary compatibility constraints. It could 
> be added to the RandomSource enum. This would allow filtering in a stream by 
> minimum jump distance. This does however add properties to RandomSource for 
> many instances where the property is not relevant (cluttering the API).
> The JDK 17 equivalent feature for this is to create 
> [Stream<RandomGeneratorFactory<RandomGenerator>> 
> all()|https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGeneratorFactory.html#all()]
>  factories and then filter on those. The 
> [RandomGeneratorFactory|https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/RandomGeneratorFactory.html]
>  instances are the equivalent of RandomSource instances as these have 
> properties that can be used for filters. However it does not appear that the 
> Jumpable generators can be filtered on their jump distance as this is not 
> exposed by the factory for use in filtering the stream. The jump distance can 
> be obtained after an instance of the generator has been created.



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

Reply via email to