LGAMMA_R 3CW "09 March 2006" "mathcw-1.00"

Table of contents


NAME

lgammaf_r, lgamma_r, lgammal_r, lgammaw_r, lgammaq_r, lgammall_r, lgammadf_r, lgammad_r, lgammadl_r, lgammadll_r - log of Gamma function with sign result

SYNOPSIS

cc [ flags ] -I/usr/local/include file(s) -L/usr/local/lib -lmcw [ ... ]

#include <mathcw.h>

extern double lgammaf_r (double x, /*@out@*/ int *psign);

extern double lgamma_r (double x, /*@out@*/ int *psign);

extern double lgammal_r (double x, /*@out@*/ int *psign);

extern double lgammaw_r (double x, /*@out@*/ int *psign);

extern double lgammaq_r (double x, /*@out@*/ int *psign);

extern long_long_double lgammall_r (long_long_double x, /*@out@*/ int *psign);

extern decimal_float lgammadf_r (decimal_float x, /*@out@*/ int *psign);

extern decimal_double lgammad_r (decimal_double x, /*@out@*/ int *psign);

extern decimal_long_double lgammadl_r (decimal_long_double x, /*@out@*/ int *psign);

extern decimal_long_long_double lgammadll_r (decimal_long_long_double x, /*@out@*/ int *psign);

NB: Functions with prototypes containing underscores in type names may be available only with certain extended compilers.


DESCRIPTION

Compute the natural logarithm of the absolute value of Gamma of x.

The Gamma function, the generalized factorial function, is defined by the integral

Gamma(x) = integral(t = 0:infinity) t**(x-1) exp(-t) dt
In traditional mathematical notation, Gamma is spelled as the uppercase Greek letter, and the lowercase Greek letter gamma refers either to the Euler constant, gamma = 0.57721566489... or when followed by two arguments, as in gamma(a,x), to the incomplete Gamma function, a function not currently provided by this library.

The Gamma function satisfies this simple recursion relation:

Gamma(x + 1) = x Gamma(x)
For positive integral arguments, the Gamma function is related to the factorial function by
Gamma(n + 1) = n! = n * (n - 1) * (n - 2) * ... * 1,

and

Gamma(1) = 0! = 1 (by definition).

This function was not standardized in the C language until the 1999 ISO C Standard, and because some historical implementations of the language had unfortunately used gamma(x) for the logarithm of the Gamma function, the C99 function was named tgamma(x) (for true Gamma), rather than Gamma(x), because Standard C library functions must be defined with only lowercase names.

Although the Gamma function grows so quickly that the overflow limit is quickly reached, the log of its absolute value is representable for arguments almost up to the overflow limit.

Because the Gamma function alternates in sign as it crosses the asymptotes at negative integer arguments, and lgamma_r() uses its absolute value, the sign of Gamma is recorded in the object pointed to by the second argument (provided that it is non-NULL): -1 if Gamma is negative, and +1 if Gamma is positive. If Gamma underflows to zero, a strong possibility for negative arguments of even modest magnitude, then the sign is -1 if Gamma tends to more negative values around the argument, and otherwise, +1.

Caution: Although lgamma_r(x,&sign) allows representation of tgamma(x) over a much wider range than is possible with tgamma(x) alone, there is mathematically-unavoidable accuracy loss when tgamma(x) is computed from exp(lgamma_r(x,&sign)), so you should avoid the logarithmic form unless you really need large arguments that would cause overflow in tgamma(x).

Caution: Because evaluation order in C is flexible, you should not incorporate the sign in a direct computation to recover Gamma as, e.g., exp((double)sign * lgamma_r(x,&sign)), but instead, compute the inner function first, temp = lgamma_r(x,&sign), then compute the outer function, exp((double)sign * temp).


RETURN VALUES

Return the natural logarithm of the absolute value of Gamma of x, and if the second argument is non-NULL, store the sign of Gamma in the object that it points to (-1 for negative, +1 for positive).

ERRORS

If the argument is +Infinity or -Infinity, the return value is that argument, and errno is set to ERANGE. If the argument is a NaN, the return value is that argument, and errno is set to EDOM. If the argument is zero or a negative integer, the return value is +Infinity, and errno is set to EDOM. In each of these cases, the sign, if set, is +1.

SEE ALSO

exp(3CW), lgamma(3CW), log(3CW), tgamma(3CW).