Class Gamma

java.lang.Object
org.apache.commons.math3.special.Gamma
public class Gamma extends 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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final double
    C_LIMIT
    C limit.
    private static final double
    DEFAULT_EPSILON
    Maximum allowed numerical error.
    static final double
    GAMMA
    Euler-Mascheroni constant
    private static final double
    HALF_LOG_2_PI
    Avoid repeated computation of log of 2 PI in logGamma
    private static final double
    INV_GAMMA1P_M1_A0
    The constant A0 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_A1
    The constant A1 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B1
    The constant B1 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B2
    The constant B2 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B3
    The constant B3 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B4
    The constant B4 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B5
    The constant B5 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B6
    The constant B6 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B7
    The constant B7 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_B8
    The constant B8 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C
    The constant C defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C0
    The constant C0 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C1
    The constant C1 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C10
    The constant C10 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C11
    The constant C11 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C12
    The constant C12 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C13
    The constant C13 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C2
    The constant C2 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C3
    The constant C3 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C4
    The constant C4 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C5
    The constant C5 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C6
    The constant C6 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C7
    The constant C7 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C8
    The constant C8 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_C9
    The constant C9 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P0
    The constant P0 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P1
    The constant P1 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P2
    The constant P2 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P3
    The constant P3 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P4
    The constant P4 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P5
    The constant P5 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_P6
    The constant P6 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_Q1
    The constant Q1 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_Q2
    The constant Q2 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_Q3
    The constant Q3 defined in DGAM1.
    private static final double
    INV_GAMMA1P_M1_Q4
    The constant Q4 defined in DGAM1.
    private static final double[]
    LANCZOS
    Lanczos coefficients
    static final double
    LANCZOS_G
    The value of the g constant in the Lanczos approximation, see lanczos(double).
    private static final double
    S_LIMIT
    S limit.
    private static final double
    SQRT_TWO_PI
    The constant value of √(2π).

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Gamma()
    Default constructor.

  • Method Summary

    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 Object

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

  • Field Details

    • GAMMA

      public static final double GAMMA
      Euler-Mascheroni constant
      Since:
      2.0
      See Also:

    • LANCZOS_G

      public static final double LANCZOS_G
      The value of the g constant in the Lanczos approximation, see lanczos(double).
      Since:
      3.1
      See Also:

    • DEFAULT_EPSILON

      private static final double DEFAULT_EPSILON
      Maximum allowed numerical error.
      See Also:

    • 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:

    • C_LIMIT

      private static final double C_LIMIT
      C limit.
      See Also:

    • S_LIMIT

      private static final double S_LIMIT
      S limit.
      See Also:

    • INV_GAMMA1P_M1_A0

      private static final double INV_GAMMA1P_M1_A0
      The constant A0 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_A1

      private static final double INV_GAMMA1P_M1_A1
      The constant A1 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B1

      private static final double INV_GAMMA1P_M1_B1
      The constant B1 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B2

      private static final double INV_GAMMA1P_M1_B2
      The constant B2 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B3

      private static final double INV_GAMMA1P_M1_B3
      The constant B3 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B4

      private static final double INV_GAMMA1P_M1_B4
      The constant B4 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B5

      private static final double INV_GAMMA1P_M1_B5
      The constant B5 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B6

      private static final double INV_GAMMA1P_M1_B6
      The constant B6 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B7

      private static final double INV_GAMMA1P_M1_B7
      The constant B7 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_B8

      private static final double INV_GAMMA1P_M1_B8
      The constant B8 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P0

      private static final double INV_GAMMA1P_M1_P0
      The constant P0 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P1

      private static final double INV_GAMMA1P_M1_P1
      The constant P1 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P2

      private static final double INV_GAMMA1P_M1_P2
      The constant P2 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P3

      private static final double INV_GAMMA1P_M1_P3
      The constant P3 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P4

      private static final double INV_GAMMA1P_M1_P4
      The constant P4 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P5

      private static final double INV_GAMMA1P_M1_P5
      The constant P5 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_P6

      private static final double INV_GAMMA1P_M1_P6
      The constant P6 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_Q1

      private static final double INV_GAMMA1P_M1_Q1
      The constant Q1 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_Q2

      private static final double INV_GAMMA1P_M1_Q2
      The constant Q2 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_Q3

      private static final double INV_GAMMA1P_M1_Q3
      The constant Q3 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_Q4

      private static final double INV_GAMMA1P_M1_Q4
      The constant Q4 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C

      private static final double INV_GAMMA1P_M1_C
      The constant C defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C0

      private static final double INV_GAMMA1P_M1_C0
      The constant C0 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C1

      private static final double INV_GAMMA1P_M1_C1
      The constant C1 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C2

      private static final double INV_GAMMA1P_M1_C2
      The constant C2 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C3

      private static final double INV_GAMMA1P_M1_C3
      The constant C3 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C4

      private static final double INV_GAMMA1P_M1_C4
      The constant C4 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C5

      private static final double INV_GAMMA1P_M1_C5
      The constant C5 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C6

      private static final double INV_GAMMA1P_M1_C6
      The constant C6 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C7

      private static final double INV_GAMMA1P_M1_C7
      The constant C7 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C8

      private static final double INV_GAMMA1P_M1_C8
      The constant C8 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C9

      private static final double INV_GAMMA1P_M1_C9
      The constant C9 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C10

      private static final double INV_GAMMA1P_M1_C10
      The constant C10 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C11

      private static final double INV_GAMMA1P_M1_C11
      The constant C11 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C12

      private static final double INV_GAMMA1P_M1_C12
      The constant C12 defined in DGAM1.
      See Also:

    • INV_GAMMA1P_M1_C13

      private static final double INV_GAMMA1P_M1_C13
      The constant C13 defined in DGAM1.
      See Also:

  • Constructor Details

    • Gamma

      private Gamma()
      Default constructor. Prohibit instantiation.

  • Method Details

    • logGamma

      public static double logGamma(double x)

      Returns the value of log Γ(x) for x > 0.

      For x ≤ 8, the implementation is based on the double precision implementation in the NSWC Library of Mathematics Subroutines, DGAMLN. For x > 8, the implementation is based on

      Parameters:
      x - Argument.
      Returns:
      the value of log(Gamma(x)), Double.NaN if x <= 0.0.

    • 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:

    • 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:

    • 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:

    • 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

    • logGamma1p

      public static double logGamma1p(double x) throws NumberIsTooSmallException, NumberIsTooLargeException
      Returns the value of log Γ(1 + x) for -0.5 ≤ x ≤ 1.5. This implementation is based on the double precision implementation in the NSWC Library of Mathematics Subroutines, DGMLN1.
      Parameters:
      x - Argument.
      Returns:
      The value of log(Gamma(1 + x)).
      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