Package org.hipparchus.special

Class Gamma

java.lang.Object

org.hipparchus.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

• 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 Hipparchus.

Field Summary

Fields

Modifier and Type	Field	Description
static final double	GAMMA	Euler-Mascheroni constant
static final double	LANCZOS_G	The value of the g constant in the Lanczos approximation, see lanczos(double).

Method Summary

Modifier and Type	Method	Description
static double	digamma(double x)	Computes the digamma function of x.
static <T extends CalculusFieldElement<T>> T	digamma(T x)	Computes the digamma function of x.
static double	gamma(double x)	Returns the value of Γ(x).
static <T extends CalculusFieldElement<T>> T	gamma(T 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 <T extends CalculusFieldElement<T>> T	invGamma1pm1(T 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 <T extends CalculusFieldElement<T>> T	lanczos(T 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 <T extends CalculusFieldElement<T>> T	logGamma(T 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 <T extends CalculusFieldElement<T>> T	logGamma1p(T 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 <T extends CalculusFieldElement<T>> T	regularizedGammaP(T a, T x)	Returns the regularized gamma function P(a, x).
static <T extends CalculusFieldElement<T>> T	regularizedGammaP(T a, T 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 <T extends CalculusFieldElement<T>> T	regularizedGammaQ(T a, T x)	Returns the regularized gamma function Q(a, x) = 1 - P(a, x).
static <T extends CalculusFieldElement<T>> T	regularizedGammaQ(T a, T 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.
static <T extends CalculusFieldElement<T>> T	trigamma(T 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 Details

GAMMA

public static final double GAMMA

Euler-Mascheroni constant

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).

See Also:

• Constant Field Values

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

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

logGamma

public static <T extends CalculusFieldElement<T>> T logGamma(T 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

Type Parameters:

T - Type of the field elements.

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:

MathIllegalStateException - if the algorithm fails to converge.

regularizedGammaP

public static <T extends CalculusFieldElement<T>> T regularizedGammaP(T a,
 T x)

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

Type Parameters:

T - Type of the field elements.

Parameters:

a - Parameter.

x - Value.

Returns:

the regularized gamma function P(a, x).

Throws:

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

MathIllegalStateException - if the algorithm fails to converge.

regularizedGammaP

public static <T extends CalculusFieldElement<T>> T regularizedGammaP(T a,
 T 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).

Type Parameters:

T - Type of the field elements.

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:

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

MathIllegalStateException - if the algorithm fails to converge.

regularizedGammaQ

public static <T extends CalculusFieldElement<T>> T regularizedGammaQ(T a,
 T x)

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

Type Parameters:

T - Type of the field elements.

Parameters:

a - the a parameter.

x - the value.

Returns:

the regularized gamma function Q(a, x)

Throws:

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

MathIllegalStateException - if the algorithm fails to converge.

regularizedGammaQ

public static <T extends CalculusFieldElement<T>> T regularizedGammaQ(T a,
 T 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)

Type Parameters:

T - Type fo the field elements.

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:

MathIllegalStateException - 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.

See Also:

• Digamma
• Bernardo's original article

digamma

public static <T extends CalculusFieldElement<T>> T digamma(T 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.

Type Parameters:

T - Type of the field elements.

Parameters:

x - Argument.

Returns:

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

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

See Also:

• Trigamma
• digamma(double)

trigamma

public static <T extends CalculusFieldElement<T>> T trigamma(T x)

Computes the trigamma function of x. This function is derived by taking the derivative of the implementation of digamma.

Type Parameters:

T - Type of the field elements.

Parameters:

x - Argument.

Returns:

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

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) = \frac{\sqrt{2\pi}}{x} \times (x + g + \frac{1}{2}) ^ (x + \frac{1}{2}) \times e^{-x - g - 0.5} \times \mathrm{lanczos}(x) \] where g is the Lanczos constant.

Parameters:

x - Argument.

Returns:

The Lanczos approximation.

See Also:

• Lanczos Approximation equations (1) through (5), and Paul Godfrey's Note on the computation of the convergent Lanczos complex Gamma approximation

lanczos

public static <T extends CalculusFieldElement<T>> T lanczos(T 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) = \frac{\sqrt{2\pi}}{x} \times (x + g + \frac{1}{2}) ^ (x + \frac{1}{2}) \times e^{-x - g - 0.5} \times \mathrm{lanczos}(x) \] where g is the Lanczos constant.

Type Parameters:

T - Type of the field elements.

Parameters:

x - Argument.

Returns:

The Lanczos approximation.

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:

MathIllegalArgumentException - if x < -0.5

MathIllegalArgumentException - if x > 1.5

invGamma1pm1

public static <T extends CalculusFieldElement<T>> T invGamma1pm1(T 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.

Type Parameters:

T - Type of the field elements.

Parameters:

x - Argument.

Returns:

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

Throws:

MathIllegalArgumentException - if x < -0.5

MathIllegalArgumentException - if x > 1.5

logGamma1p

public static double logGamma1p(double x)
                         throws MathIllegalArgumentException

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:

MathIllegalArgumentException - if x < -0.5.

MathIllegalArgumentException - if x > 1.5.

logGamma1p

public static <T extends CalculusFieldElement<T>> T logGamma1p(T x)
                                                        throws MathIllegalArgumentException

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.

Type Parameters:

T - Type of the field elements.

Parameters:

x - Argument.

Returns:

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

Throws:

MathIllegalArgumentException - if x < -0.5.

MathIllegalArgumentException - if x > 1.5.

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).

gamma

public static <T extends CalculusFieldElement<T>> T gamma(T x)

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

Type Parameters:

T - Type of the field elements.

Parameters:

x - Argument.

Returns:

the value of Gamma(x).