Top Description Fields Constructors Methods
org.apache.commons.math3.special

public Class Gamma

extends Object
Class Inheritance
Imports
org.apache.commons.math3.exception.MaxCountExceededException, .NumberIsTooLargeException, .NumberIsTooSmallException, org.apache.commons.math3.util.ContinuedFraction, .FastMath

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

Modifier and TypeField and Description
private static final double
C_LIMIT

C limit.

private static final double
DEFAULT_EPSILON

Maximum allowed numerical error.

public 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

public 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

AccessConstructor and Description
private
Gamma()

Default constructor.

Method Summary

Modifier and TypeMethod and Description
public static double

Returns:

digamma(x) to within 10-8 relative or absolute error whichever is smaller.
digamma(double
Argument.
x)

Computes the digamma function of x.

public static double

Returns:

the value of Gamma(x).
gamma(final double
Argument.
x)

Returns the value of Γ(x).

public static double

Returns:

The value of 1.0 / Gamma(1.0 + x) - 1.0.
invGamma1pm1(final double
Argument.
x)

Returns the value of 1 / Γ(1 + x) - 1 for -0.5 ≤ x ≤ 1.5.

public static double

Returns:

The Lanczos approximation.
lanczos(final double
Argument.
x)

Returns the Lanczos approximation used to compute the gamma function.</center>

public static double

Returns:

the value of log(Gamma(x)), Double.NaN if x <= 0.0.
logGamma(double
Argument.
x)

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

public static double

Returns:

The value of log(Gamma(1 + x)).
logGamma1p(final double
Argument.
x)

Returns the value of log Γ(1 + x) for -0.5 ≤ x ≤ 1.5.

public static double

Returns:

the regularized gamma function P(a, x).
regularizedGammaP(double
Parameter.
a, double
Value.
x)

Returns the regularized gamma function P(a, x).

public static double

Returns:

the regularized gamma function P(a, x)
regularizedGammaP(double
the a parameter.
a, double
the value.
x, double
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.
epsilon, int
Maximum number of "iterations" to complete.
maxIterations)

Returns the regularized gamma function P(a, x).

public static double

Returns:

the regularized gamma function Q(a, x)
regularizedGammaQ(double
the a parameter.
a, double
the value.
x)

Returns the regularized gamma function Q(a, x) = 1 - P(a, x).

public static double

Returns:

the regularized gamma function P(a, x)
regularizedGammaQ(final double
the a parameter.
a, double
the value.
x, double
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.
epsilon, int
Maximum number of "iterations" to complete.
maxIterations)

Returns the regularized gamma function Q(a, x) = 1 - P(a, x).

public static double

Returns:

trigamma(x) to within 10-8 relative or absolute error whichever is smaller
trigamma(double
Argument.
x)

Computes the trigamma function of x.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

C_LIMITback to summary
private static final double C_LIMIT

C limit.

DEFAULT_EPSILONback to summary
private static final double DEFAULT_EPSILON

Maximum allowed numerical error.

GAMMAback to summary
public static final double GAMMA

Euler-Mascheroni constant

Since
2.0
HALF_LOG_2_PIback to summary
private static final double HALF_LOG_2_PI

Avoid repeated computation of log of 2 PI in logGamma

INV_GAMMA1P_M1_A0back to summary
private static final double INV_GAMMA1P_M1_A0

The constant A0 defined in DGAM1.

INV_GAMMA1P_M1_A1back to summary
private static final double INV_GAMMA1P_M1_A1

The constant A1 defined in DGAM1.

INV_GAMMA1P_M1_B1back to summary
private static final double INV_GAMMA1P_M1_B1

The constant B1 defined in DGAM1.

INV_GAMMA1P_M1_B2back to summary
private static final double INV_GAMMA1P_M1_B2

The constant B2 defined in DGAM1.

INV_GAMMA1P_M1_B3back to summary
private static final double INV_GAMMA1P_M1_B3

The constant B3 defined in DGAM1.

INV_GAMMA1P_M1_B4back to summary
private static final double INV_GAMMA1P_M1_B4

The constant B4 defined in DGAM1.

INV_GAMMA1P_M1_B5back to summary
private static final double INV_GAMMA1P_M1_B5

The constant B5 defined in DGAM1.

INV_GAMMA1P_M1_B6back to summary
private static final double INV_GAMMA1P_M1_B6

The constant B6 defined in DGAM1.

INV_GAMMA1P_M1_B7back to summary
private static final double INV_GAMMA1P_M1_B7

The constant B7 defined in DGAM1.

INV_GAMMA1P_M1_B8back to summary
private static final double INV_GAMMA1P_M1_B8

The constant B8 defined in DGAM1.

INV_GAMMA1P_M1_Cback to summary
private static final double INV_GAMMA1P_M1_C

The constant C defined in DGAM1.

INV_GAMMA1P_M1_C0back to summary
private static final double INV_GAMMA1P_M1_C0

The constant C0 defined in DGAM1.

INV_GAMMA1P_M1_C1back to summary
private static final double INV_GAMMA1P_M1_C1

The constant C1 defined in DGAM1.

INV_GAMMA1P_M1_C10back to summary
private static final double INV_GAMMA1P_M1_C10

The constant C10 defined in DGAM1.

INV_GAMMA1P_M1_C11back to summary
private static final double INV_GAMMA1P_M1_C11

The constant C11 defined in DGAM1.

INV_GAMMA1P_M1_C12back to summary
private static final double INV_GAMMA1P_M1_C12

The constant C12 defined in DGAM1.

INV_GAMMA1P_M1_C13back to summary
private static final double INV_GAMMA1P_M1_C13

The constant C13 defined in DGAM1.

INV_GAMMA1P_M1_C2back to summary
private static final double INV_GAMMA1P_M1_C2

The constant C2 defined in DGAM1.

INV_GAMMA1P_M1_C3back to summary
private static final double INV_GAMMA1P_M1_C3

The constant C3 defined in DGAM1.

INV_GAMMA1P_M1_C4back to summary
private static final double INV_GAMMA1P_M1_C4

The constant C4 defined in DGAM1.

INV_GAMMA1P_M1_C5back to summary
private static final double INV_GAMMA1P_M1_C5

The constant C5 defined in DGAM1.

INV_GAMMA1P_M1_C6back to summary
private static final double INV_GAMMA1P_M1_C6

The constant C6 defined in DGAM1.

INV_GAMMA1P_M1_C7back to summary
private static final double INV_GAMMA1P_M1_C7

The constant C7 defined in DGAM1.

INV_GAMMA1P_M1_C8back to summary
private static final double INV_GAMMA1P_M1_C8

The constant C8 defined in DGAM1.

INV_GAMMA1P_M1_C9back to summary
private static final double INV_GAMMA1P_M1_C9

The constant C9 defined in DGAM1.

INV_GAMMA1P_M1_P0back to summary
private static final double INV_GAMMA1P_M1_P0

The constant P0 defined in DGAM1.

INV_GAMMA1P_M1_P1back to summary
private static final double INV_GAMMA1P_M1_P1

The constant P1 defined in DGAM1.

INV_GAMMA1P_M1_P2back to summary
private static final double INV_GAMMA1P_M1_P2

The constant P2 defined in DGAM1.

INV_GAMMA1P_M1_P3back to summary
private static final double INV_GAMMA1P_M1_P3

The constant P3 defined in DGAM1.

INV_GAMMA1P_M1_P4back to summary
private static final double INV_GAMMA1P_M1_P4

The constant P4 defined in DGAM1.

INV_GAMMA1P_M1_P5back to summary
private static final double INV_GAMMA1P_M1_P5

The constant P5 defined in DGAM1.

INV_GAMMA1P_M1_P6back to summary
private static final double INV_GAMMA1P_M1_P6

The constant P6 defined in DGAM1.

INV_GAMMA1P_M1_Q1back to summary
private static final double INV_GAMMA1P_M1_Q1

The constant Q1 defined in DGAM1.

INV_GAMMA1P_M1_Q2back to summary
private static final double INV_GAMMA1P_M1_Q2

The constant Q2 defined in DGAM1.

INV_GAMMA1P_M1_Q3back to summary
private static final double INV_GAMMA1P_M1_Q3

The constant Q3 defined in DGAM1.

INV_GAMMA1P_M1_Q4back to summary
private static final double INV_GAMMA1P_M1_Q4

The constant Q4 defined in DGAM1.

LANCZOSback to summary
private static final double[] LANCZOS

Lanczos coefficients

LANCZOS_Gback to summary
public static final double LANCZOS_G

The value of the g constant in the Lanczos approximation, see lanczos(double).

Since
3.1
S_LIMITback to summary
private static final double S_LIMIT

S limit.

SQRT_TWO_PIback to summary
private static final double SQRT_TWO_PI

The constant value of √(2π).

Constructor Detail

Gammaback to summary
private Gamma()

Default constructor. Prohibit instantiation.

Method Detail

digammaback to summary
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:double

Argument.

Returns:double

digamma(x) to within 10-8 relative or absolute error whichever is smaller.

Since
2.0
See Also
Digamma, Bernardo's original article
gammaback to summary
public static double gamma(final double x)

Returns the value of Γ(x). Based on the NSWC Library of Mathematics Subroutines double precision implementation, DGAMMA.

Parameters
x:double

Argument.

Returns:double

the value of Gamma(x).

Since
3.1
invGamma1pm1back to summary
public static double invGamma1pm1(final 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:double

Argument.

Returns:double

The value of 1.0 / Gamma(1.0 + x) - 1.0.

Exceptions
NumberIsTooSmallException:
if x < -0.5
NumberIsTooLargeException:
if x > 1.5
Since
3.1
lanczosback to summary
public static double lanczos(final 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:double

Argument.

Returns:double

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
logGammaback to summary
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:double

Argument.

Returns:double

the value of log(Gamma(x)), Double.NaN if x <= 0.0.

logGamma1pback to summary
public static double logGamma1p(final 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:double

Argument.

Returns:double

The value of log(Gamma(1 + x)).

Exceptions
NumberIsTooSmallException:
if x < -0.5.
NumberIsTooLargeException:
if x > 1.5.
Since
3.1
regularizedGammaPback to summary
public static double regularizedGammaP(double a, double x)

Returns the regularized gamma function P(a, x).

Parameters
a:double

Parameter.

x:double

Value.

Returns:double

the regularized gamma function P(a, x).

Exceptions
MaxCountExceededException:
if the algorithm fails to converge.
regularizedGammaPback to summary
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:double

the a parameter.

x:double

the value.

epsilon:double

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

Maximum number of "iterations" to complete.

Returns:double

the regularized gamma function P(a, x)

Exceptions
MaxCountExceededException:
if the algorithm fails to converge.
regularizedGammaQback to summary
public static double regularizedGammaQ(double a, double x)

Returns the regularized gamma function Q(a, x) = 1 - P(a, x).

Parameters
a:double

the a parameter.

x:double

the value.

Returns:double

the regularized gamma function Q(a, x)

Exceptions
MaxCountExceededException:
if the algorithm fails to converge.
regularizedGammaQback to summary
public static double regularizedGammaQ(final 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:double

the a parameter.

x:double

the value.

epsilon:double

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

Maximum number of "iterations" to complete.

Returns:double

the regularized gamma function P(a, x)

Exceptions
MaxCountExceededException:
if the algorithm fails to converge.
trigammaback to summary
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:double

Argument.

Returns:double

trigamma(x) to within 10-8 relative or absolute error whichever is smaller

Since
2.0
See Also
Trigamma, Gamma#digamma(double)