public class DiscreteUniformSampler extends SamplerBase implements SharedStateDiscreteSampler
Sampling uses UniformRandomProvider.nextInt().
When the range is a power of two the number of calls is 1 per sample.
Otherwise a rejection algorithm is used to ensure uniformity. In the worst
case scenario where the range spans half the range of an int
(231 + 1) the expected number of calls is 2 per sample.
This sampler can be used as a replacement for UniformRandomProvider.nextInt()
with appropriate adjustment of the upper bound to be inclusive and will outperform that
method when the range is not a power of two. The advantage is gained by pre-computation
of the rejection threshold.
The sampling algorithm is described in:
Lemire, D (2019). Fast Random Integer Generation in an Interval. ACM Transactions on Modeling and Computer Simulation 29 (1).
The number of int values required per sample follows a geometric distribution with
a probability of success p of 1 - ((2^32 % n) / 2^32). This requires on average 1/p random
int values per sample.
| Constructor and Description |
|---|
DiscreteUniformSampler(UniformRandomProvider rng,
int lower,
int upper)
This instance delegates sampling.
|
| Modifier and Type | Method and Description |
|---|---|
static SharedStateDiscreteSampler |
of(UniformRandomProvider rng,
int lower,
int upper)
Creates a new discrete uniform distribution sampler.
|
int |
sample()
Creates an
int sample. |
String |
toString() |
SharedStateDiscreteSampler |
withUniformRandomProvider(UniformRandomProvider rng)
Create a new instance of the sampler with the same underlying state using the given
uniform random provider as the source of randomness.
|
nextDouble, nextInt, nextInt, nextLongclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitsamples, samplespublic DiscreteUniformSampler(UniformRandomProvider rng, int lower, int upper)
of(UniformRandomProvider, int, int) to create an optimal sampler.rng - Generator of uniformly distributed random numbers.lower - Lower bound (inclusive) of the distribution.upper - Upper bound (inclusive) of the distribution.IllegalArgumentException - if lower > upper.public int sample()
int sample.sample in interface DiscreteSamplerpublic String toString()
toString in class SamplerBasepublic SharedStateDiscreteSampler withUniformRandomProvider(UniformRandomProvider rng)
withUniformRandomProvider in interface SharedStateSampler<SharedStateDiscreteSampler>rng - Generator of uniformly distributed random numbers.public static SharedStateDiscreteSampler of(UniformRandomProvider rng, int lower, int upper)
rng - Generator of uniformly distributed random numbers.lower - Lower bound (inclusive) of the distribution.upper - Upper bound (inclusive) of the distribution.IllegalArgumentException - if lower > upper.Copyright © 2016–2022 The Apache Software Foundation. All rights reserved.