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

Class PoissonSamplerCache

java.lang.Object

org.apache.commons.rng.sampling.distribution.PoissonSamplerCache

public class PoissonSamplerCache
extends java.lang.Object

Create a sampler for the Poisson distribution using a cache to minimise construction cost.

The cache will return a sampler equivalent to PoissonSampler(UniformRandomProvider, double).

The cache allows the PoissonSampler construction cost to be minimised for low size Poisson samples. The cache stores state for a range of integers where integer value n can be used to construct a sampler for the range n <= mean < n+1.

The cache is advantageous under the following conditions:

• The mean of the Poisson distribution falls within a known range.
• The sample size to be made with the same sampler is small.
• The Poisson samples have different means with the same integer value(s) after rounding down.

If the sample size to be made with the same sampler is large then the construction cost is low compared to the sampling time and the cache has minimal benefit.

Performance improvement is dependent on the speed of the UniformRandomProvider. A fast provider can obtain a two-fold speed improvement for a single-use Poisson sampler.

The cache is thread safe. Note that concurrent threads using the cache must ensure a thread safe UniformRandomProvider is used when creating samplers, e.g. a unique sampler per thread.

Sampling uses:

• UniformRandomProvider.nextDouble()
• UniformRandomProvider.nextLong() (large means only)

Since:

1.2

Constructor Summary

Constructors

Constructor	Description
PoissonSamplerCache(double minMean, double maxMean)

Method Summary

Modifier and Type	Method	Description
DiscreteSampler	createPoissonSampler(org.apache.commons.rng.UniformRandomProvider rng, double mean)	Creates a new Poisson sampler.
double	getMaxMean()	Gets the maximum mean covered by the cache.
static double	getMinimumCachedMean()	Gets the minimum mean value that can be cached.
double	getMinMean()	Gets the minimum mean covered by the cache.
boolean	isValidRange()	Checks if the cache covers a valid range of mean values.
boolean	withinRange(double mean)	Check if the mean is within the range where the cache can minimise the construction cost of the PoissonSampler.
PoissonSamplerCache	withRange(double minMean, double maxMean)	Create a new PoissonSamplerCache with the given range reusing the current cache values.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PoissonSamplerCache

public PoissonSamplerCache(double minMean,
                           double maxMean)

Parameters:

minMean - The minimum mean covered by the cache.

maxMean - The maximum mean covered by the cache.

Throws:

java.lang.IllegalArgumentException - if maxMean < minMean

Method Detail

createPoissonSampler

public DiscreteSampler createPoissonSampler(org.apache.commons.rng.UniformRandomProvider rng,
                                            double mean)

Creates a new Poisson sampler.

The returned sampler will function exactly the same as PoissonSampler(UniformRandomProvider, double).

Parameters:

rng - Generator of uniformly distributed random numbers.

mean - Mean.

Returns:

A Poisson sampler

Throws:

java.lang.IllegalArgumentException - if mean <= 0 or mean > Integer.MAX_VALUE.

withinRange

public boolean withinRange(double mean)

Check if the mean is within the range where the cache can minimise the construction cost of the PoissonSampler.

Parameters:

mean - the mean

Returns:

true, if within the cache range

isValidRange

public boolean isValidRange()

Checks if the cache covers a valid range of mean values.

Note that the cache is only valid for one of the Poisson sampling algorithms. In the instance that a range was requested that was too low then there is nothing to cache and this functions returns false.

The cache can still be used to create a PoissonSampler using createPoissonSampler(UniformRandomProvider, double).

This method can be used to determine if the cache has a potential performance benefit.

Returns:

true, if the cache covers a range of mean values

getMinMean

public double getMinMean()

Gets the minimum mean covered by the cache.

This value is the inclusive lower bound and is equal to the lowest integer-valued mean that is covered by the cache.

Note that this value may not match the value passed to the constructor due to the following reasons:

• At small mean values a different algorithm is used for Poisson sampling and the cache is unnecessary.
• The minimum is always an integer so may be below the constructor minimum mean.

If isValidRange() returns true the cache will store state to reduce construction cost of samplers in the range getMinMean() inclusive to getMaxMean() inclusive. Otherwise this method returns 0;

Returns:

The minimum mean covered by the cache.

getMaxMean

public double getMaxMean()

Gets the maximum mean covered by the cache.

This value is the inclusive upper bound and is equal to the double value below the first integer-valued mean that is above range covered by the cache.

Note that this value may not match the value passed to the constructor due to the following reasons:

• At small mean values a different algorithm is used for Poisson sampling and the cache is unnecessary.
• The maximum is always the double value below an integer so may be above the constructor maximum mean.

If isValidRange() returns true the cache will store state to reduce construction cost of samplers in the range getMinMean() inclusive to getMaxMean() inclusive. Otherwise this method returns 0;

Returns:

The maximum mean covered by the cache.

getMinimumCachedMean

public static double getMinimumCachedMean()

Gets the minimum mean value that can be cached.

Any PoissonSampler created with a mean below this level will not have any state that can be cached.

Returns:

the minimum cached mean

withRange

public PoissonSamplerCache withRange(double minMean,
                                     double maxMean)

Create a new PoissonSamplerCache with the given range reusing the current cache values.

This will create a new object even if the range is smaller or the same as the current cache.

Parameters:

minMean - The minimum mean covered by the cache.

maxMean - The maximum mean covered by the cache.

Returns:

the poisson sampler cache

Throws:

java.lang.IllegalArgumentException - if maxMean < minMean