Class DiscreteUniformSampler
- All Implemented Interfaces:
DiscreteSampler
,SharedStateDiscreteSampler
,SharedStateSampler<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.
- Since:
- 1.0
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
Base class for a sampler from a discrete uniform distribution.private static class
Discrete uniform distribution sampler when the sample value is fixed.private static class
Discrete uniform distribution sampler when the range between lower and upper is too large to fit in a positive integer.private static class
Adds an offset to an underlying discrete sampler.private static class
Discrete uniform distribution sampler when the range is a power of 2 and greater than 1.private static class
Discrete uniform distribution sampler when the range is small enough to fit in a positive integer. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final SharedStateDiscreteSampler
The appropriate uniform sampler for the parameters. -
Constructor Summary
ConstructorsConstructorDescriptionDiscreteUniformSampler
(UniformRandomProvider rng, int lower, int upper) This instance delegates sampling. -
Method Summary
Modifier and TypeMethodDescriptionprivate static DiscreteUniformSampler.AbstractDiscreteUniformSampler
createZeroBoundedSampler
(UniformRandomProvider rng, int upper) Create a new sampler for the range0
inclusive toupper
inclusive.private static boolean
isPowerOf2
(int value) Checks if the value is a power of 2.static SharedStateDiscreteSampler
of
(UniformRandomProvider rng, int lower, int upper) Creates a new discrete uniform distribution sampler.int
sample()
Creates anint
sample.toString()
Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.Methods inherited from class org.apache.commons.rng.sampling.distribution.SamplerBase
nextDouble, nextInt, nextInt, nextLong
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.apache.commons.rng.sampling.distribution.DiscreteSampler
samples, samples
-
Field Details
-
delegate
The appropriate uniform sampler for the parameters.
-
-
Constructor Details
-
DiscreteUniformSampler
This instance delegates sampling. Use the factory methodof(UniformRandomProvider, int, int)
to create an optimal sampler.- Parameters:
rng
- Generator of uniformly distributed random numbers.lower
- Lower bound (inclusive) of the distribution.upper
- Upper bound (inclusive) of the distribution.- Throws:
IllegalArgumentException
- iflower > upper
.
-
-
Method Details
-
sample
public int sample()Creates anint
sample.- Specified by:
sample
in interfaceDiscreteSampler
- Returns:
- a sample.
-
toString
- Overrides:
toString
in classSamplerBase
-
withUniformRandomProvider
Create a new instance of the sampler with the same underlying state using the given uniform random provider as the source of randomness.- Specified by:
withUniformRandomProvider
in interfaceSharedStateSampler<SharedStateDiscreteSampler>
- Parameters:
rng
- Generator of uniformly distributed random numbers.- Returns:
- the sampler
- Since:
- 1.3
-
of
Creates a new discrete uniform distribution sampler.- Parameters:
rng
- Generator of uniformly distributed random numbers.lower
- Lower bound (inclusive) of the distribution.upper
- Upper bound (inclusive) of the distribution.- Returns:
- the sampler
- Throws:
IllegalArgumentException
- iflower > upper
.- Since:
- 1.3
-
createZeroBoundedSampler
private static DiscreteUniformSampler.AbstractDiscreteUniformSampler createZeroBoundedSampler(UniformRandomProvider rng, int upper) Create a new sampler for the range0
inclusive toupper
inclusive.This can handle any positive
upper
.- Parameters:
rng
- Generator of uniformly distributed random numbers.upper
- Upper bound (inclusive) of the distribution. Must be positive.- Returns:
- the sampler
-
isPowerOf2
private static boolean isPowerOf2(int value) Checks if the value is a power of 2.This returns
true
for the valueInteger.MIN_VALUE
which can be handled as an unsigned integer of 2^31.- Parameters:
value
- Value.- Returns:
true
if a power of 2
-