Package org.apache.commons.rng.sampling.distribution

Class DiscreteUniformSampler

java.lang.Object

org.apache.commons.rng.sampling.distribution.SamplerBase

org.apache.commons.rng.sampling.distribution.DiscreteUniformSampler

All Implemented Interfaces:

DiscreteSampler, SharedStateDiscreteSampler, SharedStateSampler<SharedStateDiscreteSampler>

public class DiscreteUniformSampler
extends SamplerBase
implements SharedStateDiscreteSampler

Discrete uniform distribution sampler.

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 (2³¹ + 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:

Fast Random Integer Generation in an Interval

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	DiscreteUniformSampler.AbstractDiscreteUniformSampler	Base class for a sampler from a discrete uniform distribution.
private static class	DiscreteUniformSampler.FixedDiscreteUniformSampler	Discrete uniform distribution sampler when the sample value is fixed.
private static class	DiscreteUniformSampler.LargeRangeDiscreteUniformSampler	Discrete uniform distribution sampler when the range between lower and upper is too large to fit in a positive integer.
private static class	DiscreteUniformSampler.OffsetDiscreteUniformSampler	Adds an offset to an underlying discrete sampler.
private static class	DiscreteUniformSampler.PowerOf2RangeDiscreteUniformSampler	Discrete uniform distribution sampler when the range is a power of 2 and greater than 1.
private static class	DiscreteUniformSampler.SmallRangeDiscreteUniformSampler	Discrete uniform distribution sampler when the range is small enough to fit in a positive integer.

Field Summary

Fields

Modifier and Type	Field	Description
private SharedStateDiscreteSampler	delegate	The appropriate uniform sampler for the parameters.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	DiscreteUniformSampler(SharedStateDiscreteSampler delegate)	Private constructor used by to prevent partially initialized object if the construction of the delegate throws.
	DiscreteUniformSampler(UniformRandomProvider rng, int lower, int upper)	This instance delegates sampling.

Method Summary

Modifier and Type	Method	Description
private static DiscreteUniformSampler.AbstractDiscreteUniformSampler	createZeroBoundedSampler(UniformRandomProvider rng, int upper)	Create a new sampler for the range 0 inclusive to upper 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 an int sample.
java.lang.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.

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 Detail

delegate

private final SharedStateDiscreteSampler delegate

The appropriate uniform sampler for the parameters.

Constructor Detail

DiscreteUniformSampler

public DiscreteUniformSampler(UniformRandomProvider rng,
                              int lower,
                              int upper)

This instance delegates sampling. Use the factory method of(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:

java.lang.IllegalArgumentException - if lower > upper.

DiscreteUniformSampler

private DiscreteUniformSampler(SharedStateDiscreteSampler delegate)

Private constructor used by to prevent partially initialized object if the construction of the delegate throws. In future versions the public constructor should be removed.

Parameters:

delegate - Delegate.

Method Detail

sample

public int sample()

Creates an int sample.

Specified by:

sample in interface DiscreteSampler

Returns:

a sample.

toString

public java.lang.String toString()

Overrides:

toString in class SamplerBase

withUniformRandomProvider

public 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.

Specified by:

withUniformRandomProvider in interface SharedStateSampler<SharedStateDiscreteSampler>

Parameters:

rng - Generator of uniformly distributed random numbers.

Returns:

the sampler

Since:

1.3

of

public static SharedStateDiscreteSampler of(UniformRandomProvider rng,
                                            int lower,
                                            int upper)

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:

java.lang.IllegalArgumentException - if lower > upper.

Since:

1.3

createZeroBoundedSampler

private static DiscreteUniformSampler.AbstractDiscreteUniformSampler createZeroBoundedSampler(UniformRandomProvider rng,
                                                                                              int upper)

Create a new sampler for the range 0 inclusive to upper 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 value Integer.MIN_VALUE which can be handled as an unsigned integer of 2^31.

Parameters:

value - Value.

Returns:

true if a power of 2