[jira] [Resolved] (RNG-110) Factory methods for Discrete and Continuous distribution samplers

["Alex D Herbert (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/RNG-110?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Alex D Herbert resolved RNG-110.
--------------------------------
    Resolution: Implemented

In master.

> Factory methods for Discrete and Continuous distribution samplers
> -----------------------------------------------------------------
>
>                 Key: RNG-110
>                 URL: https://issues.apache.org/jira/browse/RNG-110
>             Project: Commons RNG
>          Issue Type: Improvement
>          Components: sampling
>    Affects Versions: 1.3
>            Reporter: Alex D Herbert
>            Assignee: Alex D Herbert
>            Priority: Major
>             Fix For: 1.3
>
>          Time Spent: 40m
>  Remaining Estimate: 0h
>
> Many of the Discrete and Continuous samplers use internal classes to select the best algorithm. The outer class is then a simple wrapper for the inner class implementation. All samplers have a very simple public API with a sample method and the ability to create a new instance (SharedStateSampler<R> interface):
> {code:java}
> String toString();
> int/double sample(); 
> SharedStateSampler<R> withUniformRandomProvider(UniformRandomProvider);
> {code}
> This can be encapsulated in a new pair of interfaces:
> {code:java}
> public interface SharedStateDiscreteSampler
>      extends DiscreteSampler,
>              SharedStateSampler<SharedStateDiscreteSampler> {
>      // Marker interface
> }
> public interface SharedStateContinuousSampler
>      extends ContinuousSampler,
>              SharedStateSampler<SharedStateContinuousSampler> {
>      // Marker interface
> }
> {code}
> All distribution samplers should implement one of these new interfaces. This simplifies the implementation of the SharedStateSampler<R> interface and allows to move to a factory constructor code model. Each sampler would have a factory method to create a sampler. The factory method is free to choose the optimal implementation.
> All current released classes must maintain their public constructors. All unreleased classes should remove public constructors and have factory methods to create a sampler. The suggested factory method is {{of}}. E.g.
> {code:java}
> UniformRandomProvider rng = ...;
> double probabilityOfSuccess = ...;
> SharedStateDiscreteSampler sampler =
>     GeometricSampler.of(rng, probabilityOfSuccess);
> {code}
> In the case of classes with existing factory methods these can be moved to inner classes allowing:
> {code:java}
> SharedStateDiscreteSampler sampler =
>     MarsagliaTsangWangDiscreteSampler.Binomial.of(...)
> SharedStateDiscreteSampler sampler = 
>     MarsagliaTsangWangDiscreteSampler.Poisson.of(...)
> SharedStateDiscreteSampler sampler = 
>     MarsagliaTsangWangDiscreteSampler.Enumerated.of(...)
> {code}
> Overall the proposal is to:
>  - Create SharedStateDiscreteSampler and SharedStateContinuousSampler
>  - Simplify the implementation of SharedStateSampler<R> for Discrete and Continuous samplers
>  - Move to factory constructors for unreleased samplers
>  - Add factory constructors to existing samplers to return optimised
>  implementations
> Note: Removal of existing public constructors cannot be done until the next major release. Addition of factory constructors for these classes will allow optimal samplers to be constructed.
> *TBD - Documentation/Deprecated of public constructors*
> A note should be added to the public constructor when the factory method will create a more optimal sampler, for example in the case of the {{PoissonSampler}} which wraps a specialised Small/LargeMeanPoissonSampler.
> {code:java}
> /**
>  * This instance delegates sampling. Use the factory method
>  * {@link #of(UniformRandomProvider, double)} to create an optimal sampler.
>  *
>  * @param rng Generator of uniformly distributed random numbers.
>  * @param mean Mean.
>  * @throws IllegalArgumentException if {@code mean <= 0} or
>  * {@code mean >} {@link Integer#MAX_VALUE}.
>  */
> public PoissonSampler(UniformRandomProvider rng,
>                       double mean) {
> {code}
>  
>  An alternative would be the same message within a deprecated tag.
>  



--
This message was sent by Atlassian JIRA
(v7.6.14#76016)