org.apache.commons.math3.special

## Class Gamma

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

  - Didonato and Morris (1986), Computation of the Incomplete Gamma Function Ratios and their Inverse, TOMS 12(4), 377-393,
  - Didonato and Morris (1992), Algorithm 708: Significant Digit Computation of the Incomplete Beta Function Ratios, TOMS 18(3), 360-373,
  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.
  Version:
    $Id: Gamma.java 1422313 2012-12-15 18:53:41Z psteitz $

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `Gamma()` Default constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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

    - #### GAMMA

          public static final double GAMMA

      Euler-Mascheroni constant
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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

    - #### C_LIMIT

          private static final double C_LIMIT

      C limit.
      See Also:
        Constant Field Values

    - #### S_LIMIT

          private static final double S_LIMIT

      S limit.
      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

    - #### 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

      - Gamma Function, equation (28).
      - Lanczos Approximation, equations (1) through (5).
      - Paul Godfrey, A note on the computation of the convergent Lanczos complex Gamma approximation
      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:
      - Regularized Gamma Function, equation (1)
      - Incomplete Gamma Function, equation (4).
      - Confluent Hypergeometric Function of the First Kind, equation (1).
      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:
      - Regularized Gamma Function, equation (1).
      - Regularized incomplete gamma function: Continued fraction representations (formula 06.08.10.0003)
      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

    - #### 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

Copyright (c) 2003-2013 Apache Software Foundation