[ 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)