Class PoissonSamplerCache
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
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final int
The maximum N covered by the cache whereN = (int)Math.floor(mean)
.private final int
The minimum N covered by the cache whereN = (int)Math.floor(mean)
.private final LargeMeanPoissonSampler.LargeMeanPoissonSamplerState[]
-
Constructor Summary
ConstructorsModifierConstructorDescriptionPoissonSamplerCache
(double minMean, double maxMean) Create an instance.private
PoissonSamplerCache
(double minMean, double maxMean, boolean ignored) private
PoissonSamplerCache
(int minN, int maxN, LargeMeanPoissonSampler.LargeMeanPoissonSamplerState[] states) -
Method Summary
Modifier and TypeMethodDescriptionprivate static double
checkMeanRange
(double minMean, double maxMean) Check the mean range.createPoissonSampler
(UniformRandomProvider rng, double mean) Deprecated.createSharedStateSampler
(UniformRandomProvider rng, double mean) Creates a new Poisson sampler.double
Gets the maximum mean covered by the cache.static double
Gets the minimum mean value that can be cached.double
Gets the minimum mean covered by the cache.boolean
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 thePoissonSampler
.withRange
(double minMean, double maxMean) Create a newPoissonSamplerCache
with the given range reusing the current cache values.
-
Field Details
-
minN
private final int minNThe minimum N covered by the cache whereN = (int)Math.floor(mean)
. -
maxN
private final int maxNThe maximum N covered by the cache whereN = (int)Math.floor(mean)
. -
values
-
-
Constructor Details
-
PoissonSamplerCache
public PoissonSamplerCache(double minMean, double maxMean) Create an instance.- Parameters:
minMean
- The minimum mean covered by the cache.maxMean
- The maximum mean covered by the cache.- Throws:
IllegalArgumentException
- ifmaxMean < minMean
-
PoissonSamplerCache
private PoissonSamplerCache(double minMean, double maxMean, boolean ignored) - Parameters:
minMean
- The minimum mean covered by the cache.maxMean
- The maximum mean covered by the cache.ignored
- Ignored value.
-
PoissonSamplerCache
private PoissonSamplerCache(int minN, int maxN, LargeMeanPoissonSampler.LargeMeanPoissonSamplerState[] states) - Parameters:
minN
- The minimum N covered by the cache whereN = (int)Math.floor(mean)
.maxN
- The maximum N covered by the cache whereN = (int)Math.floor(mean)
.states
- The precomputed states.
-
-
Method Details
-
checkMeanRange
private static double checkMeanRange(double minMean, double maxMean) Check the mean range.This method exists to raise an exception before invocation of the private constructor; this mitigates Finalizer attacks (see SpotBugs CT_CONSTRUCTOR_THROW).
- Parameters:
minMean
- The minimum mean covered by the cache.maxMean
- The maximum mean covered by the cache.- Returns:
- the minimum mean
- Throws:
IllegalArgumentException
- ifmaxMean < minMean
-
createPoissonSampler
Deprecated.Creates a new Poisson sampler.The returned sampler will function exactly the same as
PoissonSampler.of(UniformRandomProvider, double)
.- Parameters:
rng
- Generator of uniformly distributed random numbers.mean
- Mean.- Returns:
- A Poisson sampler
- Throws:
IllegalArgumentException
- ifmean <= 0
ormean >
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 thePoissonSampler
.- 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
usingcreateSharedStateSampler(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()
returnstrue
the cache will store state to reduce construction cost of samplers in the rangegetMinMean()
inclusive togetMaxMean()
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()
returnstrue
the cache will store state to reduce construction cost of samplers in the rangegetMinMean()
inclusive togetMaxMean()
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
Create a newPoissonSamplerCache
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:
IllegalArgumentException
- ifmaxMean < minMean
-
createSharedStateSampler(UniformRandomProvider, double)
.