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, nextLong
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
samples, samples
public 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 DiscreteSampler
public String toString()
toString
in class SamplerBase
public 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.