libs/math/doc/sf/tgamma.qbk

   1 [section:tgamma Gamma]
   2
   3 [h4 Synopsis]
   4
   5 ``
   6 #include <boost/math/special_functions/gamma.hpp>
   7 ``
   8
   9   namespace boost{ namespace math{
  10
  11   template <class T>
  12   ``__sf_result`` tgamma(T z);
  13
  14   template <class T, class ``__Policy``>
  15   ``__sf_result`` tgamma(T z, const ``__Policy``&);
  16
  17   template <class T>
  18   ``__sf_result`` tgamma1pm1(T dz);
  19
  20   template <class T, class ``__Policy``>
  21   ``__sf_result`` tgamma1pm1(T dz, const ``__Policy``&);
  22
  23   }} // namespaces
  24
  25 [h4 Description]
  26
  27   template <class T>
  28   ``__sf_result`` tgamma(T z);
  29
  30   template <class T, class ``__Policy``>
  31   ``__sf_result`` tgamma(T z, const ``__Policy``&);
  32
  33 Returns the "true gamma" (hence name tgamma) of value z:
  34
  35 [equation gamm1]
  36
  37 [graph tgamma]
  38
  39 [optional_policy]
  40
  41 The return type of this function is computed using the __arg_promotion_rules:
  42 the result is `double` when T is an integer type, and T otherwise.
  43
  44   template <class T>
  45   ``__sf_result`` tgamma1pm1(T dz);
  46
  47   template <class T, class ``__Policy``>
  48   ``__sf_result`` tgamma1pm1(T dz, const ``__Policy``&);
  49
  50 Returns `tgamma(dz + 1) - 1`.  Internally the implementation does not make
  51 use of the addition and subtraction implied by the definition, leading to
  52 accurate results even for very small `dz`.
  53
  54 The return type of this function is computed using the __arg_promotion_rules:
  55 the result is `double` when T is an integer type, and T otherwise.
  56
  57 [optional_policy]
  58
  59 [h4 Accuracy]
  60
  61 The following table shows the peak errors (in units of epsilon)
  62 found on various platforms with various floating point types,
  63 along with comparisons to other common libraries.
  64 Unless otherwise specified any floating point type that is narrower
  65 than the one shown will have __zero_error.
  66
  67 [table_tgamma]
  68
  69 [table_tgamma1pm1]
  70
  71 The following error plot are based on an exhaustive search of the functions domain, MSVC-15.5 at `double` precision,
  72 and GCC-7.1/Ubuntu for `long double` and `__float128`.
  73
  74 [graph tgamma__double]
  75
  76 [graph tgamma__80_bit_long_double]
  77
  78 [graph tgamma____float128]
  79
  80
  81 [h4 Testing]
  82
  83 The gamma is relatively easy to test: factorials and half-integer factorials
  84 can be calculated exactly by other means and compared with the gamma function.
  85 In addition, some accuracy tests in known tricky areas were computed at high precision
  86 using the generic version of this function.
  87
  88 The function `tgamma1pm1` is tested against values calculated very naively
  89 using the formula `tgamma(1+dz)-1` with a lanczos approximation accurate
  90 to around 100 decimal digits.
  91
  92 [h4 Implementation]
  93
  94 The generic version of the `tgamma` function is implemented Sterling's approximation
  95 for `lgamma` for large z:
  96
  97 [equation gamma6]
  98
  99 Following exponentiation, downward recursion is then used for small values of z.
 100
 101 For types of known precision the __lanczos is used, a traits class
 102 `boost::math::lanczos::lanczos_traits` maps type T to an appropriate
 103 approximation.
 104
 105 For z in the range -20 < z < 1 then recursion is used to shift to z > 1 via:
 106
 107 [equation gamm3]
 108
 109 For very small z, this helps to preserve the identity:
 110
 111 [equation gamm4]
 112
 113 For z < -20 the reflection formula:
 114
 115 [equation gamm5]
 116
 117 is used.  Particular care has to be taken to evaluate the [^ z * sin([pi] * z)] part:
 118 a special routine is used to reduce z prior to multiplying by [pi] to ensure that the
 119 result in is the range [0, [pi]/2]. Without this an excessive amount of error occurs
 120 in this region (which is hard enough already, as the rate of change near a negative pole
 121 is /exceptionally/ high).
 122
 123 Finally if the argument is a small integer then table lookup of the factorial
 124 is used.
 125
 126 The function `tgamma1pm1` is implemented using rational approximations [jm_rationals] in the
 127 region `-0.5 < dz < 2`.  These are the same approximations (and internal routines)
 128 that are used for __lgamma, and so aren't detailed further here.  The result of
 129 the approximation is `log(tgamma(dz+1))` which can fed into __expm1 to give
 130 the desired result.  Outside the range `-0.5 < dz < 2` then the naive formula
 131 `tgamma1pm1(dz) = tgamma(dz+1)-1` can be used directly.
 132
 133 [endsect] [/section:tgamma The Gamma Function]
 134 [/
 135   Copyright 2006 John Maddock and Paul A. Bristow.
 136   Distributed under the Boost Software License, Version 1.0.
 137   (See accompanying file LICENSE_1_0.txt or copy at
 138   http://www.boost.org/LICENSE_1_0.txt).
 139 ]
 140