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 33Returns the "true gamma" (hence name tgamma) of value z: 34 35[equation gamm1] 36 37[graph tgamma] 38 39[optional_policy] 40 41The return type of this function is computed using the __arg_promotion_rules: 42the 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 50Returns `tgamma(dz + 1) - 1`. Internally the implementation does not make 51use of the addition and subtraction implied by the definition, leading to 52accurate results even for very small `dz`. 53 54The return type of this function is computed using the __arg_promotion_rules: 55the result is `double` when T is an integer type, and T otherwise. 56 57[optional_policy] 58 59[h4 Accuracy] 60 61The following table shows the peak errors (in units of epsilon) 62found on various platforms with various floating point types, 63along with comparisons to other common libraries. 64Unless otherwise specified any floating point type that is narrower 65than the one shown will have __zero_error. 66 67[table_tgamma] 68 69[table_tgamma1pm1] 70 71The following error plot are based on an exhaustive search of the functions domain, MSVC-15.5 at `double` precision, 72and 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 83The gamma is relatively easy to test: factorials and half-integer factorials 84can be calculated exactly by other means and compared with the gamma function. 85In addition, some accuracy tests in known tricky areas were computed at high precision 86using the generic version of this function. 87 88The function `tgamma1pm1` is tested against values calculated very naively 89using the formula `tgamma(1+dz)-1` with a lanczos approximation accurate 90to around 100 decimal digits. 91 92[h4 Implementation] 93 94The generic version of the `tgamma` function is implemented Sterling's approximation 95for `lgamma` for large z: 96 97[equation gamma6] 98 99Following exponentiation, downward recursion is then used for small values of z. 100 101For types of known precision the __lanczos is used, a traits class 102`boost::math::lanczos::lanczos_traits` maps type T to an appropriate 103approximation. 104 105For z in the range -20 < z < 1 then recursion is used to shift to z > 1 via: 106 107[equation gamm3] 108 109For very small z, this helps to preserve the identity: 110 111[equation gamm4] 112 113For z < -20 the reflection formula: 114 115[equation gamm5] 116 117is used. Particular care has to be taken to evaluate the [^ z * sin([pi] * z)] part: 118a special routine is used to reduce z prior to multiplying by [pi] to ensure that the 119result in is the range [0, [pi]/2]. Without this an excessive amount of error occurs 120in this region (which is hard enough already, as the rate of change near a negative pole 121is /exceptionally/ high). 122 123Finally if the argument is a small integer then table lookup of the factorial 124is used. 125 126The function `tgamma1pm1` is implemented using rational approximations [jm_rationals] in the 127region `-0.5 < dz < 2`. These are the same approximations (and internal routines) 128that are used for __lgamma, and so aren't detailed further here. The result of 129the approximation is `log(tgamma(dz+1))` which can fed into __expm1 to give 130the 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 141