Class InternalUtils


  • final class InternalUtils
    extends java.lang.Object
    Functions used by some of the samplers. This class is not part of the public API, as it would be better to group these utilities in a dedicated component.
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  InternalUtils.FactorialLog
      Class for computing the natural logarithm of the factorial of n.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static int BEGIN_LOG_FACTORIALS
      The first array index with a non-zero log factorial.
      private static double DOUBLE_MULTIPLIER
      The multiplier to convert the least significant 53-bits of a long to a double.
      private static double[] LOG_FACTORIALS
      All long-representable factorials, precomputed as the natural logarithm using Matlab R2023a VPA: log(vpa(x)).
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private InternalUtils()
      Utility class.
    • Field Detail

      • LOG_FACTORIALS

        private static final double[] LOG_FACTORIALS
        All long-representable factorials, precomputed as the natural logarithm using Matlab R2023a VPA: log(vpa(x)).

        Note: This table could be any length. Previously this stored the long value of n!, not log(n!). Using the previous length maintains behaviour.

      • BEGIN_LOG_FACTORIALS

        private static final int BEGIN_LOG_FACTORIALS
        The first array index with a non-zero log factorial.
        See Also:
        Constant Field Values
      • DOUBLE_MULTIPLIER

        private static final double DOUBLE_MULTIPLIER
        The multiplier to convert the least significant 53-bits of a long to a double. Taken from org.apache.commons.rng.core.util.NumberFactory.
        See Also:
        Constant Field Values
    • Constructor Detail

      • InternalUtils

        private InternalUtils()
        Utility class.
    • Method Detail

      • logFactorial

        static double logFactorial​(int n)
        Parameters:
        n - Argument.
        Returns:
        n!
        Throws:
        java.lang.IndexOutOfBoundsException - if the result is too large to be represented by a long (i.e. if n > 20), or n is negative.
      • validateProbabilities

        static double validateProbabilities​(double[] probabilities)
        Validate the probabilities sum to a finite positive number.
        Parameters:
        probabilities - the probabilities
        Returns:
        the sum
        Throws:
        java.lang.IllegalArgumentException - if probabilities is null or empty, a probability is negative, infinite or NaN, or the sum of all probabilities is not strictly positive.
      • requireFinite

        static double requireFinite​(double x,
                                    java.lang.String name)
        Checks the value x is finite.
        Parameters:
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x is non-finite
      • requirePositiveFinite

        static double requirePositiveFinite​(double x,
                                            java.lang.String name)
        Checks the value x >= 0 and is finite. Note: This method allows x == -0.0.
        Parameters:
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x < 0 or is non-finite
      • requireStrictlyPositiveFinite

        static double requireStrictlyPositiveFinite​(double x,
                                                    java.lang.String name)
        Checks the value x > 0 and is finite.
        Parameters:
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x <= 0 or is non-finite
      • requirePositive

        static double requirePositive​(double x,
                                      java.lang.String name)
        Checks the value x >= 0. Note: This method allows x == -0.0.
        Parameters:
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x < 0
      • requireStrictlyPositive

        static double requireStrictlyPositive​(double x,
                                              java.lang.String name)
        Checks the value x > 0.
        Parameters:
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x <= 0
      • requireRange

        static double requireRange​(double min,
                                   double max,
                                   double x,
                                   java.lang.String name)
        Checks the value is within the range: min <= x < max.
        Parameters:
        min - Minimum (inclusive).
        max - Maximum (exclusive).
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x < min || x >= max.
      • requireRangeClosed

        static double requireRangeClosed​(double min,
                                         double max,
                                         double x,
                                         java.lang.String name)
        Checks the value is within the closed range: min <= x <= max.
        Parameters:
        min - Minimum (inclusive).
        max - Maximum (inclusive).
        x - Value.
        name - Name of the value.
        Returns:
        x
        Throws:
        java.lang.IllegalArgumentException - if x < min || x > max.
      • makeDouble

        static double makeDouble​(long v)
        Creates a double in the interval [0, 1) from a long value.
        Parameters:
        v - Number.
        Returns:
        a double value in the interval [0, 1).
      • makeNonZeroDouble

        static double makeNonZeroDouble​(long v)
        Creates a double in the interval (0, 1] from a long value.
        Parameters:
        v - Number.
        Returns:
        a double value in the interval (0, 1].