Class Gamma


  • public class Gamma
    extends java.lang.Object

    This is a utility class that provides computation methods related to the Γ (Gamma) family of functions.

    Implementation of invGamma1pm1(double) and logGamma1p(double) is based on the algorithms described in

    and implemented in the NSWC Library of Mathematical Functions, available here. This library is "approved for public release", and the Copyright guidance indicates that unless otherwise stated in the code, all FORTRAN functions in this library are license free. Since no such notice appears in the code these functions can safely be ported to Commons-Math.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Gamma()
      Default constructor.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static double digamma​(double x)
      Computes the digamma function of x.
      static double gamma​(double x)
      Returns the value of Γ(x).
      static double invGamma1pm1​(double x)
      Returns the value of 1 / Γ(1 + x) - 1 for -0.5 ≤ x ≤ 1.5.
      static double lanczos​(double x)
      Returns the Lanczos approximation used to compute the gamma function.
      static double logGamma​(double x)
      Returns the value of log Γ(x) for x > 0.
      static double logGamma1p​(double x)
      Returns the value of log Γ(1 + x) for -0.5 ≤ x ≤ 1.5.
      static double regularizedGammaP​(double a, double x)
      Returns the regularized gamma function P(a, x).
      static double regularizedGammaP​(double a, double x, double epsilon, int maxIterations)
      Returns the regularized gamma function P(a, x).
      static double regularizedGammaQ​(double a, double x)
      Returns the regularized gamma function Q(a, x) = 1 - P(a, x).
      static double regularizedGammaQ​(double a, double x, double epsilon, int maxIterations)
      Returns the regularized gamma function Q(a, x) = 1 - P(a, x).
      static double trigamma​(double x)
      Computes the trigamma function of x.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • DEFAULT_EPSILON

        private static final double DEFAULT_EPSILON
        Maximum allowed numerical error.
        See Also:
        Constant Field Values
      • LANCZOS

        private static final double[] LANCZOS
        Lanczos coefficients
      • HALF_LOG_2_PI

        private static final double HALF_LOG_2_PI
        Avoid repeated computation of log of 2 PI in logGamma
      • SQRT_TWO_PI

        private static final double SQRT_TWO_PI
        The constant value of √(2π).
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_A0

        private static final double INV_GAMMA1P_M1_A0
        The constant A0 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_A1

        private static final double INV_GAMMA1P_M1_A1
        The constant A1 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B1

        private static final double INV_GAMMA1P_M1_B1
        The constant B1 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B2

        private static final double INV_GAMMA1P_M1_B2
        The constant B2 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B3

        private static final double INV_GAMMA1P_M1_B3
        The constant B3 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B4

        private static final double INV_GAMMA1P_M1_B4
        The constant B4 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B5

        private static final double INV_GAMMA1P_M1_B5
        The constant B5 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B6

        private static final double INV_GAMMA1P_M1_B6
        The constant B6 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B7

        private static final double INV_GAMMA1P_M1_B7
        The constant B7 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_B8

        private static final double INV_GAMMA1P_M1_B8
        The constant B8 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P0

        private static final double INV_GAMMA1P_M1_P0
        The constant P0 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P1

        private static final double INV_GAMMA1P_M1_P1
        The constant P1 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P2

        private static final double INV_GAMMA1P_M1_P2
        The constant P2 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P3

        private static final double INV_GAMMA1P_M1_P3
        The constant P3 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P4

        private static final double INV_GAMMA1P_M1_P4
        The constant P4 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P5

        private static final double INV_GAMMA1P_M1_P5
        The constant P5 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_P6

        private static final double INV_GAMMA1P_M1_P6
        The constant P6 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_Q1

        private static final double INV_GAMMA1P_M1_Q1
        The constant Q1 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_Q2

        private static final double INV_GAMMA1P_M1_Q2
        The constant Q2 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_Q3

        private static final double INV_GAMMA1P_M1_Q3
        The constant Q3 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_Q4

        private static final double INV_GAMMA1P_M1_Q4
        The constant Q4 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C

        private static final double INV_GAMMA1P_M1_C
        The constant C defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C0

        private static final double INV_GAMMA1P_M1_C0
        The constant C0 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C1

        private static final double INV_GAMMA1P_M1_C1
        The constant C1 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C2

        private static final double INV_GAMMA1P_M1_C2
        The constant C2 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C3

        private static final double INV_GAMMA1P_M1_C3
        The constant C3 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C4

        private static final double INV_GAMMA1P_M1_C4
        The constant C4 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C5

        private static final double INV_GAMMA1P_M1_C5
        The constant C5 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C6

        private static final double INV_GAMMA1P_M1_C6
        The constant C6 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C7

        private static final double INV_GAMMA1P_M1_C7
        The constant C7 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C8

        private static final double INV_GAMMA1P_M1_C8
        The constant C8 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C9

        private static final double INV_GAMMA1P_M1_C9
        The constant C9 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C10

        private static final double INV_GAMMA1P_M1_C10
        The constant C10 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C11

        private static final double INV_GAMMA1P_M1_C11
        The constant C11 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C12

        private static final double INV_GAMMA1P_M1_C12
        The constant C12 defined in DGAM1.
        See Also:
        Constant Field Values
      • INV_GAMMA1P_M1_C13

        private static final double INV_GAMMA1P_M1_C13
        The constant C13 defined in DGAM1.
        See Also:
        Constant Field Values
    • Constructor Detail

      • Gamma

        private Gamma()
        Default constructor. Prohibit instantiation.
    • Method Detail

      • regularizedGammaP

        public static double regularizedGammaP​(double a,
                                               double x)
        Returns the regularized gamma function P(a, x).
        Parameters:
        a - Parameter.
        x - Value.
        Returns:
        the regularized gamma function P(a, x).
        Throws:
        MaxCountExceededException - if the algorithm fails to converge.
      • regularizedGammaP

        public static double regularizedGammaP​(double a,
                                               double x,
                                               double epsilon,
                                               int maxIterations)
        Returns the regularized gamma function P(a, x). The implementation of this method is based on:
        Parameters:
        a - the a parameter.
        x - the value.
        epsilon - When the absolute value of the nth item in the series is less than epsilon the approximation ceases to calculate further elements in the series.
        maxIterations - Maximum number of "iterations" to complete.
        Returns:
        the regularized gamma function P(a, x)
        Throws:
        MaxCountExceededException - if the algorithm fails to converge.
      • regularizedGammaQ

        public static double regularizedGammaQ​(double a,
                                               double x)
        Returns the regularized gamma function Q(a, x) = 1 - P(a, x).
        Parameters:
        a - the a parameter.
        x - the value.
        Returns:
        the regularized gamma function Q(a, x)
        Throws:
        MaxCountExceededException - if the algorithm fails to converge.
      • regularizedGammaQ

        public static double regularizedGammaQ​(double a,
                                               double x,
                                               double epsilon,
                                               int maxIterations)
        Returns the regularized gamma function Q(a, x) = 1 - P(a, x). The implementation of this method is based on:
        Parameters:
        a - the a parameter.
        x - the value.
        epsilon - When the absolute value of the nth item in the series is less than epsilon the approximation ceases to calculate further elements in the series.
        maxIterations - Maximum number of "iterations" to complete.
        Returns:
        the regularized gamma function P(a, x)
        Throws:
        MaxCountExceededException - if the algorithm fails to converge.
      • digamma

        public static double digamma​(double x)

        Computes the digamma function of x.

        This is an independently written implementation of the algorithm described in Jose Bernardo, Algorithm AS 103: Psi (Digamma) Function, Applied Statistics, 1976.

        Some of the constants have been changed to increase accuracy at the moderate expense of run-time. The result should be accurate to within 10^-8 absolute tolerance for x >= 10^-5 and within 10^-8 relative tolerance for x > 0.

        Performance for large negative values of x will be quite expensive (proportional to |x|). Accuracy for negative values of x should be about 10^-8 absolute for results less than 10^5 and 10^-8 relative for results larger than that.

        Parameters:
        x - Argument.
        Returns:
        digamma(x) to within 10-8 relative or absolute error whichever is smaller.
        Since:
        2.0
        See Also:
        Digamma, Bernardo's original article
      • trigamma

        public static double trigamma​(double x)
        Computes the trigamma function of x. This function is derived by taking the derivative of the implementation of digamma.
        Parameters:
        x - Argument.
        Returns:
        trigamma(x) to within 10-8 relative or absolute error whichever is smaller
        Since:
        2.0
        See Also:
        Trigamma, digamma(double)
      • lanczos

        public static double lanczos​(double x)

        Returns the Lanczos approximation used to compute the gamma function. The Lanczos approximation is related to the Gamma function by the following equation

        gamma(x) = sqrt(2 * pi) / x * (x + g + 0.5) ^ (x + 0.5) * exp(-x - g - 0.5) * lanczos(x),
        where g is the Lanczos constant.

        Parameters:
        x - Argument.
        Returns:
        The Lanczos approximation.
        Since:
        3.1
        See Also:
        Lanczos Approximation equations (1) through (5), and Paul Godfrey's Note on the computation of the convergent Lanczos complex Gamma approximation
      • invGamma1pm1

        public static double invGamma1pm1​(double x)
        Returns the value of 1 / Γ(1 + x) - 1 for -0.5 ≤ x ≤ 1.5. This implementation is based on the double precision implementation in the NSWC Library of Mathematics Subroutines, DGAM1.
        Parameters:
        x - Argument.
        Returns:
        The value of 1.0 / Gamma(1.0 + x) - 1.0.
        Throws:
        NumberIsTooSmallException - if x < -0.5
        NumberIsTooLargeException - if x > 1.5
        Since:
        3.1
      • gamma

        public static double gamma​(double x)
        Returns the value of Γ(x). Based on the NSWC Library of Mathematics Subroutines double precision implementation, DGAMMA.
        Parameters:
        x - Argument.
        Returns:
        the value of Gamma(x).
        Since:
        3.1