Gamma (Commons MATH 3.6)

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.

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.

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

Class Gamma

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GAMMA

LANCZOS_G

DEFAULT_EPSILON

LANCZOS

HALF_LOG_2_PI

SQRT_TWO_PI

C_LIMIT

S_LIMIT

INV_GAMMA1P_M1_A0

INV_GAMMA1P_M1_A1

INV_GAMMA1P_M1_B1

INV_GAMMA1P_M1_B2

INV_GAMMA1P_M1_B3

INV_GAMMA1P_M1_B4

INV_GAMMA1P_M1_B5

INV_GAMMA1P_M1_B6

INV_GAMMA1P_M1_B7

INV_GAMMA1P_M1_B8

INV_GAMMA1P_M1_P0

INV_GAMMA1P_M1_P1

INV_GAMMA1P_M1_P2

INV_GAMMA1P_M1_P3

INV_GAMMA1P_M1_P4

INV_GAMMA1P_M1_P5

INV_GAMMA1P_M1_P6

INV_GAMMA1P_M1_Q1

INV_GAMMA1P_M1_Q2

INV_GAMMA1P_M1_Q3

INV_GAMMA1P_M1_Q4

INV_GAMMA1P_M1_C

INV_GAMMA1P_M1_C0

INV_GAMMA1P_M1_C1

INV_GAMMA1P_M1_C2

INV_GAMMA1P_M1_C3

INV_GAMMA1P_M1_C4

INV_GAMMA1P_M1_C5

INV_GAMMA1P_M1_C6

INV_GAMMA1P_M1_C7

INV_GAMMA1P_M1_C8

INV_GAMMA1P_M1_C9

INV_GAMMA1P_M1_C10

INV_GAMMA1P_M1_C11

INV_GAMMA1P_M1_C12

INV_GAMMA1P_M1_C13

Constructor Detail

Gamma

Method Detail

logGamma

regularizedGammaP

regularizedGammaP

regularizedGammaQ

regularizedGammaQ

digamma

trigamma

lanczos

invGamma1pm1

logGamma1p

gamma