htswanalysis/MACS/lib/gsl/gsl-1.11/doc/specfunc-gamma.texi

   1 The  functions described in this section are declared
   2 in the header file @file{gsl_sf_gamma.h}.
   3
   4 @menu
   5 * Gamma Functions::
   6 * Factorials::
   7 * Pochhammer Symbol::
   8 * Incomplete Gamma Functions::
   9 * Beta Functions::
  10 * Incomplete Beta Function::
  11 @end menu
  12
  13 @node Gamma Functions
  14 @subsection Gamma Functions
  15 @cindex gamma functions
  16
  17 The Gamma function is defined by the following integral,
  18 @tex
  19 \beforedisplay
  20 $$
  21 \Gamma(x) = \int_0^{\infty} dt \, t^{x-1} \exp(-t)
  22 $$
  23 \afterdisplay
  24 @end tex
  25 @ifinfo
  26
  27 @example
  28 \Gamma(x) = \int_0^\infty dt  t^@{x-1@} \exp(-t)
  29 @end example
  30
  31 @end ifinfo
  32 @noindent
  33 It is related to the factorial function by @math{\Gamma(n)=(n-1)!}
  34 for positive integer @math{n}.  Further information on the Gamma function
  35 can be found in Abramowitz & Stegun, Chapter 6.  The functions
  36 described in this section are declared in the header file
  37 @file{gsl_sf_gamma.h}.
  38
  39 @deftypefun double gsl_sf_gamma (double @var{x})
  40 @deftypefunx int gsl_sf_gamma_e (double @var{x}, gsl_sf_result * @var{result})
  41 These routines compute the Gamma function @math{\Gamma(x)}, subject to @math{x}
  42 not being a negative integer or zero.  The function is computed using the real
  43 Lanczos method. The maximum value of @math{x} such that @math{\Gamma(x)} is not
  44 considered an overflow is given by the macro @code{GSL_SF_GAMMA_XMAX}
  45 and is 171.0.
  46 @comment exceptions: GSL_EDOM, GSL_EOVRFLW, GSL_EROUND
  47 @end deftypefun
  48
  49 @deftypefun double gsl_sf_lngamma (double @var{x})
  50 @deftypefunx int gsl_sf_lngamma_e (double @var{x}, gsl_sf_result * @var{result})
  51 @cindex logarithm of Gamma function
  52 These routines compute the logarithm of the Gamma function,
  53 @math{\log(\Gamma(x))}, subject to @math{x} not being a negative
  54 integer or zero.  For @math{x<0} the real part of @math{\log(\Gamma(x))} is
  55 returned, which is equivalent to @math{\log(|\Gamma(x)|)}.  The function
  56 is computed using the real Lanczos method.
  57 @comment exceptions: GSL_EDOM, GSL_EROUND
  58 @end deftypefun
  59
  60 @deftypefun int gsl_sf_lngamma_sgn_e (double @var{x}, gsl_sf_result * @var{result_lg}, double * @var{sgn})
  61 This routine computes the sign of the gamma function and the logarithm of
  62 its magnitude, subject to @math{x} not being a negative integer or zero.  The
  63 function is computed using the real Lanczos method.  The value of the
  64 gamma function can be reconstructed using the relation @math{\Gamma(x) =
  65 sgn * \exp(resultlg)}.
  66 @comment exceptions: GSL_EDOM, GSL_EROUND
  67 @end deftypefun
  68
  69 @deftypefun double gsl_sf_gammastar (double @var{x})
  70 @deftypefunx int gsl_sf_gammastar_e (double @var{x}, gsl_sf_result * @var{result})
  71 @cindex Regulated Gamma function
  72 These routines compute the regulated Gamma Function @math{\Gamma^*(x)}
  73 for @math{x > 0}. The regulated gamma function is given by,
  74 @tex
  75 \beforedisplay
  76 $$
  77 \eqalign{
  78 \Gamma^*(x) &= \Gamma(x)/(\sqrt{2\pi} x^{(x-1/2)} \exp(-x))\cr
  79             &= \left(1 + {1 \over 12x} + ...\right) \quad\hbox{for~} x\to \infty\cr
  80 }
  81 $$
  82 \afterdisplay
  83 @end tex
  84 @ifinfo
  85
  86 @example
  87 \Gamma^*(x) = \Gamma(x)/(\sqrt@{2\pi@} x^@{(x-1/2)@} \exp(-x))
  88             = (1 + (1/12x) + ...)  for x \to \infty
  89 @end example
  90 @end ifinfo
  91 and is a useful suggestion of Temme.
  92 @comment exceptions: GSL_EDOM
  93 @end deftypefun
  94
  95 @deftypefun double gsl_sf_gammainv (double @var{x})
  96 @deftypefunx int gsl_sf_gammainv_e (double @var{x}, gsl_sf_result * @var{result})
  97 @cindex Reciprocal Gamma function
  98 These routines compute the reciprocal of the gamma function,
  99 @math{1/\Gamma(x)} using the real Lanczos method.
 100 @comment exceptions: GSL_EUNDRFLW, GSL_EROUND
 101 @end deftypefun
 102
 103 @deftypefun int gsl_sf_lngamma_complex_e (double @var{zr}, double @var{zi}, gsl_sf_result * @var{lnr}, gsl_sf_result * @var{arg})
 104 @cindex Complex Gamma function
 105 This routine computes @math{\log(\Gamma(z))} for complex @math{z=z_r+i
 106 z_i} and @math{z} not a negative integer or zero, using the complex Lanczos
 107 method.  The returned parameters are @math{lnr = \log|\Gamma(z)|} and
 108 @math{arg = \arg(\Gamma(z))} in @math{(-\pi,\pi]}.  Note that the phase
 109 part (@var{arg}) is not well-determined when @math{|z|} is very large,
 110 due to inevitable roundoff in restricting to @math{(-\pi,\pi]}.  This
 111 will result in a @code{GSL_ELOSS} error when it occurs.  The absolute
 112 value part (@var{lnr}), however, never suffers from loss of precision.
 113 @comment exceptions: GSL_EDOM, GSL_ELOSS
 114 @end deftypefun
 115
 116 @node Factorials
 117 @subsection Factorials
 118 @cindex factorial
 119
 120 Although factorials can be computed from the Gamma function, using
 121 the relation @math{n! = \Gamma(n+1)} for non-negative integer @math{n},
 122 it is usually more efficient to call the functions in this section,
 123 particularly for small values of @math{n}, whose factorial values are
 124 maintained in hardcoded tables.
 125
 126 @deftypefun double gsl_sf_fact (unsigned int @var{n})
 127 @deftypefunx int gsl_sf_fact_e (unsigned int @var{n}, gsl_sf_result * @var{result})
 128 @cindex factorial
 129 These routines compute the factorial @math{n!}.  The factorial is
 130 related to the Gamma function by @math{n! = \Gamma(n+1)}.
 131 The maximum value of @math{n} such that @math{n!} is not
 132 considered an overflow is given by the macro @code{GSL_SF_FACT_NMAX}
 133 and is 170.
 134 @comment exceptions: GSL_EDOM, GSL_OVRFLW
 135 @end deftypefun
 136
 137 @deftypefun double gsl_sf_doublefact (unsigned int @var{n})
 138 @deftypefunx int gsl_sf_doublefact_e (unsigned int @var{n}, gsl_sf_result * @var{result})
 139 @cindex double factorial
 140 These routines compute the double factorial @math{n!! = n(n-2)(n-4) \dots}.
 141 The maximum value of @math{n} such that @math{n!!} is not
 142 considered an overflow is given by the macro @code{GSL_SF_DOUBLEFACT_NMAX}
 143 and is 297.
 144 @comment exceptions: GSL_EDOM, GSL_OVRFLW
 145 @end deftypefun
 146
 147 @deftypefun double gsl_sf_lnfact (unsigned int @var{n})
 148 @deftypefunx int gsl_sf_lnfact_e (unsigned int @var{n}, gsl_sf_result * @var{result})
 149 @cindex logarithm of factorial
 150 These routines compute the logarithm of the factorial of @var{n},
 151 @math{\log(n!)}.  The algorithm is faster than computing
 152 @math{\ln(\Gamma(n+1))} via @code{gsl_sf_lngamma} for @math{n < 170},
 153 but defers for larger @var{n}.
 154 @comment exceptions: none
 155 @end deftypefun
 156
 157 @deftypefun double gsl_sf_lndoublefact (unsigned int @var{n})
 158 @deftypefunx int gsl_sf_lndoublefact_e (unsigned int @var{n}, gsl_sf_result * @var{result})
 159 @cindex logarithm of double factorial
 160 These routines compute the logarithm of the double factorial of @var{n},
 161 @math{\log(n!!)}.
 162 @comment exceptions: none
 163 @end deftypefun
 164
 165 @deftypefun double gsl_sf_choose (unsigned int @var{n}, unsigned int @var{m})
 166 @deftypefunx int gsl_sf_choose_e (unsigned int @var{n}, unsigned int @var{m}, gsl_sf_result * @var{result})
 167 @cindex combinatorial factor C(m,n)
 168 These routines compute the combinatorial factor @code{n choose m}
 169 @math{= n!/(m!(n-m)!)}
 170 @comment exceptions: GSL_EDOM, GSL_EOVRFLW
 171 @end deftypefun
 172
 173
 174 @deftypefun double gsl_sf_lnchoose (unsigned int @var{n}, unsigned int @var{m})
 175 @deftypefunx int gsl_sf_lnchoose_e (unsigned int @var{n}, unsigned int @var{m}, gsl_sf_result * @var{result})
 176 @cindex logarithm of combinatorial factor C(m,n)
 177 These routines compute the logarithm of @code{n choose m}.  This is
 178 equivalent to the sum @math{\log(n!) - \log(m!) - \log((n-m)!)}.
 179 @comment exceptions: GSL_EDOM
 180 @end deftypefun
 181
 182 @deftypefun double gsl_sf_taylorcoeff (int @var{n}, double @var{x})
 183 @deftypefunx int gsl_sf_taylorcoeff_e (int @var{n}, double @var{x}, gsl_sf_result * @var{result})
 184 @cindex Taylor coefficients, computation of
 185 These routines compute the Taylor coefficient @math{x^n / n!} for
 186 @c{$x \ge 0$}
 187 @math{x >= 0},
 188 @c{$n \ge 0$}
 189 @math{n >= 0}.
 190 @comment exceptions: GSL_EDOM, GSL_EOVRFLW, GSL_EUNDRFLW
 191 @end deftypefun
 192
 193 @node Pochhammer Symbol
 194 @subsection Pochhammer Symbol
 195
 196 @deftypefun double gsl_sf_poch (double @var{a}, double @var{x})
 197 @deftypefunx int gsl_sf_poch_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result})
 198 @cindex Pochhammer symbol
 199 @cindex Apell symbol, see Pochammer symbol
 200 These routines compute the Pochhammer symbol @math{(a)_x = \Gamma(a +
 201 x)/\Gamma(a)}, subject to @math{a} and @math{a+x} not being negative
 202 integers or zero. The Pochhammer symbol is also known as the Apell symbol and
 203 sometimes written as @math{(a,x)}.
 204 @comment exceptions:  GSL_EDOM, GSL_EOVRFLW
 205 @end deftypefun
 206
 207
 208 @deftypefun double gsl_sf_lnpoch (double @var{a}, double @var{x})
 209 @deftypefunx int gsl_sf_lnpoch_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result})
 210 @cindex logarithm of Pochhammer symbol
 211 These routines compute the logarithm of the Pochhammer symbol,
 212 @math{\log((a)_x) = \log(\Gamma(a + x)/\Gamma(a))} for @math{a > 0},
 213 @math{a+x > 0}.
 214 @comment exceptions:  GSL_EDOM
 215 @end deftypefun
 216
 217 @deftypefun int gsl_sf_lnpoch_sgn_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result}, double * @var{sgn})
 218 These routines compute the sign of the Pochhammer symbol and the
 219 logarithm of its magnitude.  The computed parameters are @math{result =
 220 \log(|(a)_x|)} and @math{sgn = \sgn((a)_x)} where @math{(a)_x =
 221 \Gamma(a + x)/\Gamma(a)}, subject to @math{a}, @math{a+x} not being
 222 negative integers or zero.
 223 @comment exceptions:  GSL_EDOM
 224 @end deftypefun
 225
 226 @deftypefun double gsl_sf_pochrel (double @var{a}, double @var{x})
 227 @deftypefunx int gsl_sf_pochrel_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result})
 228 @cindex relative Pochhammer symbol
 229 These routines compute the relative Pochhammer symbol @math{((a)_x -
 230 1)/x} where @math{(a)_x = \Gamma(a + x)/\Gamma(a)}.
 231 @comment exceptions:  GSL_EDOM
 232 @end deftypefun
 233
 234
 235 @node Incomplete Gamma Functions
 236 @subsection Incomplete Gamma Functions
 237
 238 @deftypefun double gsl_sf_gamma_inc (double @var{a}, double @var{x})
 239 @deftypefunx int gsl_sf_gamma_inc_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result})
 240 @cindex non-normalized incomplete Gamma function
 241 @cindex unnormalized incomplete Gamma function
 242 These functions compute the unnormalized incomplete Gamma Function
 243 @c{$\Gamma(a,x) = \int_x^\infty dt\, t^{(a-1)} \exp(-t)$}
 244 @math{\Gamma(a,x) = \int_x^\infty dt t^@{a-1@} \exp(-t)}
 245 for @math{a} real and @c{$x \ge 0$}
 246 @math{x >= 0}.
 247 @comment exceptions: GSL_EDOM
 248 @end deftypefun
 249
 250 @deftypefun double gsl_sf_gamma_inc_Q (double @var{a}, double @var{x})
 251 @deftypefunx int gsl_sf_gamma_inc_Q_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result})
 252 @cindex incomplete Gamma function
 253 These routines compute the normalized incomplete Gamma Function
 254 @c{$Q(a,x) = 1/\Gamma(a) \int_x^\infty dt\, t^{(a-1)} \exp(-t)$}
 255 @math{Q(a,x) = 1/\Gamma(a) \int_x^\infty dt t^@{a-1@} \exp(-t)}
 256 for @math{a > 0}, @c{$x \ge 0$}
 257 @math{x >= 0}.
 258 @comment exceptions: GSL_EDOM
 259 @end deftypefun
 260
 261 @deftypefun double gsl_sf_gamma_inc_P (double @var{a}, double @var{x})
 262 @deftypefunx int gsl_sf_gamma_inc_P_e (double @var{a}, double @var{x}, gsl_sf_result * @var{result})
 263 @cindex complementary incomplete Gamma function
 264 These routines compute the complementary normalized incomplete Gamma Function
 265 @c{$P(a,x) = 1 - Q(a,x) = 1/\Gamma(a) \int_0^x dt\, t^{(a-1)} \exp(-t)$}
 266 @math{P(a,x) = 1 - Q(a,x) = 1/\Gamma(a) \int_0^x dt t^@{a-1@} \exp(-t)}
 267 for @math{a > 0}, @c{$x \ge 0$}
 268 @math{x >= 0}.
 269
 270 Note that Abramowitz & Stegun call @math{P(a,x)} the incomplete gamma
 271 function (section 6.5).
 272 @comment exceptions: GSL_EDOM
 273 @end deftypefun
 274
 275 @node Beta Functions
 276 @subsection Beta Functions
 277
 278 @deftypefun double gsl_sf_beta (double @var{a}, double @var{b})
 279 @deftypefunx int gsl_sf_beta_e (double @var{a}, double @var{b}, gsl_sf_result * @var{result})
 280 @cindex Beta function
 281 These routines compute the Beta Function, @math{B(a,b) =
 282 \Gamma(a)\Gamma(b)/\Gamma(a+b)} subject to @math{a} and @math{b} not
 283 being negative integers.
 284 @comment exceptions: GSL_EDOM, GSL_EOVRFLW, GSL_EUNDRFLW
 285 @end deftypefun
 286
 287 @deftypefun double gsl_sf_lnbeta (double @var{a}, double @var{b})
 288 @deftypefunx int gsl_sf_lnbeta_e (double @var{a}, double @var{b}, gsl_sf_result * @var{result})
 289 @cindex logarithm of Beta function
 290 These routines compute the logarithm of the Beta Function, @math{\log(B(a,b))}
 291 subject to @math{a} and @math{b} not
 292 being negative integers.
 293 @comment exceptions: GSL_EDOM
 294 @end deftypefun
 295
 296 @node Incomplete Beta Function
 297 @subsection Incomplete Beta Function
 298
 299 @deftypefun double gsl_sf_beta_inc (double @var{a}, double @var{b}, double @var{x})
 300 @deftypefunx int gsl_sf_beta_inc_e (double @var{a}, double @var{b}, double @var{x}, gsl_sf_result * @var{result})
 301 @cindex incomplete Beta function, normalized
 302 @cindex normalized incomplete Beta function
 303 @cindex Beta function, incomplete normalized
 304 These routines compute the normalized incomplete Beta function
 305 @math{I_x(a,b)=B_x(a,b)/B(a,b)} where @c{$B_x(a,b) = \int_0^x t^{a-1} (1-t)^{b-1} dt$}
 306 @math{B_x(a,b) = \int_0^x t^@{a-1@} (1-t)^@{b-1@} dt}
 307 for @c{$0 \le x \le 1$}
 308 @math{0 <= x <= 1}.   For @math{a > 0}, @math{b > 0} the value is computed using
 309 a continued fraction expansion.  For all other values it is computed using
 310 the relation @c{$I_x(a,b,x) = (1/a) x^a {}_2F_1(a,1-b,a+1,x)/B(a,b)$}
 311 @math{I_x(a,b,x) = (1/a) x^a 2F1(a,1-b,a+1,x)/B(a,b)}.
 312 @end deftypefun
 313
 314
 315
 316
 317