Major Description
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):
String toString(); int/double sample(); SharedStateSampler<R> withUniformRandomProvider(UniformRandomProvider);
This can be encapsulated in a new pair of interfaces:
public interface SharedStateDiscreteSampler extends DiscreteSampler, SharedStateSampler<SharedStateDiscreteSampler> { // Marker interface } public interface SharedStateContinuousSampler extends ContinuousSampler, SharedStateSampler<SharedStateContinuousSampler> { // Marker interface }
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.
UniformRandomProvider rng = ...;
double probabilityOfSuccess = ...;
SharedStateDiscreteSampler sampler =
GeometricSampler.of(rng, probabilityOfSuccess);
In the case of classes with existing factory methods these can be moved to inner classes allowing:
SharedStateDiscreteSampler sampler =
MarsagliaTsangWangDiscreteSampler.Binomial.of(...)
SharedStateDiscreteSampler sampler =
MarsagliaTsangWangDiscreteSampler.Poisson.of(...)
SharedStateDiscreteSampler sampler =
MarsagliaTsangWangDiscreteSampler.Enumerated.of(...)
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.
/**
* 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) {
An alternative would be the same message within a deprecated tag.
Attachments
Issue Links
- links to
