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

Class PoissonSamplerCache

  • public class PoissonSamplerCache
extends 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:

    Since:
    1.2

    • Constructor Detail

      • 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 - if maxMean < minMean

    • Method Detail

      • 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 createSharedStateSampler(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:
        IllegalArgumentException - if maxMean < minMean