org.apache.commons.math3.special
Class Gamma

java.lang.Object
  extended by 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.

Version:
$Id: Gamma.java 1422313 2012-12-15 18:53:41Z psteitz $

Field Summary
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
private Gamma()
          Default constructor.
 
Method Summary
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

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