3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Incomplete Gamma Functions</title>
5 <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="../../../index.html" title="Math Toolkit">
8 <link rel="up" href="../sf_gamma.html" title="Gamma Functions">
9 <link rel="prev" href="gamma_ratios.html" title="Ratios of Gamma Functions">
10 <link rel="next" href="igamma_inv.html" title="Incomplete Gamma Function Inverses">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="gamma_ratios.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="igamma_inv.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
25 <div class="section math_toolkit_special_sf_gamma_igamma">
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="math_toolkit.special.sf_gamma.igamma"></a><a class="link" href="igamma.html" title="Incomplete Gamma Functions">Incomplete Gamma
29 </h4></div></div></div>
31 <a name="math_toolkit.special.sf_gamma.igamma.h0"></a>
32 <span><a name="math_toolkit.special.sf_gamma.igamma.synopsis"></a></span><a class="link" href="igamma.html#math_toolkit.special.sf_gamma.igamma.synopsis">Synopsis</a>
36 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
40 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
42 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
43 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
45 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
46 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
48 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
49 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
51 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
52 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
54 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
55 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
57 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
58 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
60 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
61 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
63 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
64 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
66 <span class="special">}}</span> <span class="comment">// namespaces</span>
69 <a name="math_toolkit.special.sf_gamma.igamma.h1"></a>
70 <span><a name="math_toolkit.special.sf_gamma.igamma.description"></a></span><a class="link" href="igamma.html#math_toolkit.special.sf_gamma.igamma.description">Description</a>
73 There are four <a href="http://mathworld.wolfram.com/IncompleteGammaFunction.html" target="_top">incomplete
74 gamma functions</a>: two are normalised versions (also known as <span class="emphasis"><em>regularized</em></span>
75 incomplete gamma functions) that return values in the range [0, 1], and
76 two are non-normalised and return values in the range [0, Γ(a)]. Users interested
77 in statistical applications should use the <a href="http://mathworld.wolfram.com/RegularizedGammaFunction.html" target="_top">normalised
78 versions (gamma_p and gamma_q)</a>.
81 All of these functions require <span class="emphasis"><em>a > 0</em></span> and <span class="emphasis"><em>z
82 >= 0</em></span>, otherwise they return the result of <a class="link" href="../../main_overview/error_handling.html#domain_error">domain_error</a>.
85 The final <a class="link" href="../../policy.html" title="Policies">Policy</a> argument is
86 optional and can be used to control the behaviour of the function: how
87 it handles errors, what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Policies">policy documentation for more details</a>.
90 The return type of these functions is computed using the <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result
91 type calculation rules</em></span></a> when T1 and T2 are different types,
92 otherwise the return type is simply T1.
94 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
95 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
97 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">></span>
98 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
101 Returns the normalised lower incomplete gamma function of a and z:
104 <span class="inlinemediaobject"><img src="../../../../equations/igamma4.png"></span>
107 This function changes rapidly from 0 to 1 around the point z == a:
110 <span class="inlinemediaobject"><img src="../../../../graphs/gamma_p.png" align="middle"></span>
112 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
113 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
115 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
116 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">gamma_q</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
119 Returns the normalised upper incomplete gamma function of a and z:
122 <span class="inlinemediaobject"><img src="../../../../equations/igamma3.png"></span>
125 This function changes rapidly from 1 to 0 around the point z == a:
128 <span class="inlinemediaobject"><img src="../../../../graphs/gamma_q.png" align="middle"></span>
130 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
131 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
133 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
134 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma_lower</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
137 Returns the full (non-normalised) lower incomplete gamma function of a
141 <span class="inlinemediaobject"><img src="../../../../equations/igamma2.png"></span>
143 <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">></span>
144 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">);</span>
146 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T1</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T2</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">></span>
147 <a class="link" href="../../main_overview/result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">T1</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">T2</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Policies">Policy</a><span class="special">&);</span>
150 Returns the full (non-normalised) upper incomplete gamma function of a
154 <span class="inlinemediaobject"><img src="../../../../equations/igamma1.png"></span>
157 <a name="math_toolkit.special.sf_gamma.igamma.h2"></a>
158 <span><a name="math_toolkit.special.sf_gamma.igamma.accuracy"></a></span><a class="link" href="igamma.html#math_toolkit.special.sf_gamma.igamma.accuracy">Accuracy</a>
161 The following tables give peak and mean relative errors in over various
162 domains of a and z, along with comparisons to the <a href="http://www.gnu.org/software/gsl/" target="_top">GSL-1.9</a>
163 and <a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> libraries.
164 Note that only results for the widest floating point type on the system
165 are given as narrower types have <a class="link" href="../../backgrounders/relative_error.html#zero_error">effectively
169 Note that errors grow as <span class="emphasis"><em>a</em></span> grows larger.
172 Note also that the higher error rates for the 80 and 128 bit long double
173 results are somewhat misleading: expected results that are zero at 64-bit
174 double precision may be non-zero - but exceptionally small - with the larger
175 exponent range of a long double. These results therefore reflect the more
176 extreme nature of the tests conducted for these types.
179 All values are in units of epsilon.
182 <a name="math_toolkit.special.sf_gamma.igamma.errors_in_the_function_gamma_p_a_z_"></a><p class="title"><b>Table 21. Errors In the Function gamma_p(a,z)</b></p>
183 <div class="table-contents"><table class="table" summary="Errors In the Function gamma_p(a,z)">
199 Platform and Compiler
210 0.01*a < z < 100*a
215 1x10<sup>-12</sup> < a < 5x10<sup>-2</sup>
221 0.01*a < z < 100*a
226 1e-6 < a < 1.7x10<sup>6</sup>
253 (GSL Peak=342 Mean=46)
256 (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak=491
265 (GSL Peak=4.8 Mean=0.76)
268 (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak=21
277 (GSL Peak=1022 Mean=1054)
280 (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak~8x10<sup>6</sup> Mean~7x10<sup>4</sup>)
292 RedHat Linux IA32, gcc-3.3
307 Peak~30,220 Mean=1929
319 Redhat Linux IA64, gcc-3.4
334 Peak~30,790 Mean=1864
346 HPUX IA64, aCC A.06.06
368 <br class="table-break"><div class="table">
369 <a name="math_toolkit.special.sf_gamma.igamma.errors_in_the_function_gamma_q_a_z_"></a><p class="title"><b>Table 22. Errors In the Function gamma_q(a,z)</b></p>
370 <div class="table-contents"><table class="table" summary="Errors In the Function gamma_q(a,z)">
386 Platform and Compiler
397 0.01*a < z < 100*a
402 1x10<sup>-12</sup> < a < 5x10<sup>-2</sup>
408 0.01*a < z < 100*a
413 1x10<sup>-6</sup> < a < 1.7x10<sup>6</sup>
440 (GSL Peak=201 Mean=13)
443 (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak=556
452 (GSL Peak~1.3x10<sup>10</sup> Mean=1x10<sup>+9</sup>)
455 (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak~3x10<sup>11</sup> Mean=4x10<sup>10</sup>)
463 (GSL Peak=27,050 Mean=2159)
466 (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak~8x10<sup>6</sup> Mean~7x10<sup>5</sup>)
478 RedHat Linux IA32, gcc-3.3
505 Redhat Linux IA64, gcc-3.4
532 HPUX IA64, aCC A.06.06
554 <br class="table-break"><div class="table">
555 <a name="math_toolkit.special.sf_gamma.igamma.errors_in_the_function_tgamma_lower_a_z_"></a><p class="title"><b>Table 23. Errors In the Function tgamma_lower(a,z)</b></p>
556 <div class="table-contents"><table class="table" summary="Errors In the Function tgamma_lower(a,z)">
571 Platform and Compiler
582 0.01*a < z < 100*a
587 1x10<sup>-12</sup> < a < 5x10<sup>-2</sup>
593 0.01*a < z < 100*a
628 RedHat Linux IA32, gcc-3.3
650 Redhat Linux IA64, gcc-3.4
672 HPUX IA64, aCC A.06.06
689 <br class="table-break"><div class="table">
690 <a name="math_toolkit.special.sf_gamma.igamma.errors_in_the_function_tgamma_a_z_"></a><p class="title"><b>Table 24. Errors In the Function tgamma(a,z)</b></p>
691 <div class="table-contents"><table class="table" summary="Errors In the Function tgamma(a,z)">
706 Platform and Compiler
717 0.01*a < z < 100*a
722 1x10<sup>-12</sup> < a < 5x10<sup>-2</sup>
728 0.01*a < z < 100*a
763 RedHat Linux IA32, gcc-3.3
785 Redhat Linux IA64, gcc-3.4.4
807 HPUX IA64, aCC A.06.06
824 <br class="table-break"><h5>
825 <a name="math_toolkit.special.sf_gamma.igamma.h3"></a>
826 <span><a name="math_toolkit.special.sf_gamma.igamma.testing"></a></span><a class="link" href="igamma.html#math_toolkit.special.sf_gamma.igamma.testing">Testing</a>
829 There are two sets of tests: spot tests compare values taken from <a href="http://functions.wolfram.com/GammaBetaErf/" target="_top">Mathworld's online evaluator</a>
830 with this implementation to perform a basic "sanity check". Accuracy
831 tests use data generated at very high precision (using NTL's RR class set
832 at 1000-bit precision) using this implementation with a very high precision
833 60-term <a class="link" href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos approximation</a>,
834 and some but not all of the special case handling disabled. This is less
835 than satisfactory: an independent method should really be used, but apparently
836 a complete lack of such methods are available. We can't even use a deliberately
837 naive implementation without special case handling since Legendre's continued
838 fraction (see below) is unstable for small a and z.
841 <a name="math_toolkit.special.sf_gamma.igamma.h4"></a>
842 <span><a name="math_toolkit.special.sf_gamma.igamma.implementation"></a></span><a class="link" href="igamma.html#math_toolkit.special.sf_gamma.igamma.implementation">Implementation</a>
845 These four functions share a common implementation since they are all related
849 1) <span class="inlinemediaobject"><img src="../../../../equations/igamma5.png"></span>
852 2) <span class="inlinemediaobject"><img src="../../../../equations/igamma6.png"></span>
855 3) <span class="inlinemediaobject"><img src="../../../../equations/igamma7.png"></span>
858 The lower incomplete gamma is computed from its series representation:
861 4) <span class="inlinemediaobject"><img src="../../../../equations/igamma8.png"></span>
864 Or by subtraction of the upper integral from either Γ(a) or 1 when <span class="emphasis"><em>x
865 - (1</em></span>(3x)) > a and x > 1.1/.
868 The upper integral is computed from Legendre's continued fraction representation:
871 5) <span class="inlinemediaobject"><img src="../../../../equations/igamma9.png"></span>
874 When <span class="emphasis"><em>(x > 1.1)</em></span> or by subtraction of the lower integral
875 from either Γ(a) or 1 when <span class="emphasis"><em>x - (1</em></span>(3x)) < a/.
878 For <span class="emphasis"><em>x < 1.1</em></span> computation of the upper integral is
879 more complex as the continued fraction representation is unstable in this
880 area. However there is another series representation for the lower integral:
883 6) <span class="inlinemediaobject"><img src="../../../../equations/igamma10.png"></span>
886 That lends itself to calculation of the upper integral via rearrangement
890 7) <span class="inlinemediaobject"><img src="../../../../equations/igamma11.png"></span>
893 Refer to the documentation for <a class="link" href="../powers/powm1.html" title="powm1">powm1</a>
894 and <a class="link" href="tgamma.html" title="Gamma">tgamma1pm1</a>
895 for details of their implementation. Note however that the precision of
896 <a class="link" href="tgamma.html" title="Gamma">tgamma1pm1</a>
897 is capped to either around 35 digits, or to that of the <a class="link" href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
898 approximation</a> associated with type T - if there is one - whichever
899 of the two is the greater. That therefore imposes a similar limit on the
900 precision of this function in this region.
903 For <span class="emphasis"><em>x < 1.1</em></span> the crossover point where the result
904 is ~0.5 no longer occurs for <span class="emphasis"><em>x ~ y</em></span>. Using <span class="emphasis"><em>x
905 * 0.75 < a</em></span> as the crossover criterion for <span class="emphasis"><em>0.5 <
906 x <= 1.1</em></span> keeps the maximum value computed (whether it's the
907 upper or lower interval) to around 0.75. Likewise for <span class="emphasis"><em>x <=
908 0.5</em></span> then using <span class="emphasis"><em>-0.4 / log(x) < a</em></span> as
909 the crossover criterion keeps the maximum value computed to around 0.7
910 (whether it's the upper or lower interval).
913 There are two special cases used when a is an integer or half integer,
914 and the crossover conditions listed above indicate that we should compute
915 the upper integral Q. If a is an integer in the range <span class="emphasis"><em>1 <=
916 a < 30</em></span> then the following finite sum is used:
919 9) <span class="inlinemediaobject"><img src="../../../../equations/igamma1f.png"></span>
922 While for half integers in the range <span class="emphasis"><em>0.5 <= a < 30</em></span>
923 then the following finite sum is used:
926 10) <span class="inlinemediaobject"><img src="../../../../equations/igamma2f.png"></span>
929 These are both more stable and more efficient than the continued fraction
933 When the argument <span class="emphasis"><em>a</em></span> is large, and <span class="emphasis"><em>x ~ a</em></span>
934 then the series (4) and continued fraction (5) above are very slow to converge.
935 In this area an expansion due to Temme is used:
938 11) <span class="inlinemediaobject"><img src="../../../../equations/igamma16.png"></span>
941 12) <span class="inlinemediaobject"><img src="../../../../equations/igamma17.png"></span>
944 13) <span class="inlinemediaobject"><img src="../../../../equations/igamma18.png"></span>
947 14) <span class="inlinemediaobject"><img src="../../../../equations/igamma19.png"></span>
950 The double sum is truncated to a fixed number of terms - to give a specific
951 target precision - and evaluated as a polynomial-of-polynomials. There
952 are versions for up to 128-bit long double precision: types requiring greater
953 precision than that do not use these expansions. The coefficients C<sub>k</sub><sup>n</sup> are
954 computed in advance using the recurrence relations given by Temme. The
955 zone where these expansions are used is
957 <pre class="programlisting"><span class="special">(</span><span class="identifier">a</span> <span class="special">></span> <span class="number">20</span><span class="special">)</span> <span class="special">&&</span> <span class="special">(</span><span class="identifier">a</span> <span class="special"><</span> <span class="number">200</span><span class="special">)</span> <span class="special">&&</span> <span class="identifier">fabs</span><span class="special">(</span><span class="identifier">x</span><span class="special">-</span><span class="identifier">a</span><span class="special">)/</span><span class="identifier">a</span> <span class="special"><</span> <span class="number">0.4</span>
962 <pre class="programlisting"><span class="special">(</span><span class="identifier">a</span> <span class="special">></span> <span class="number">200</span><span class="special">)</span> <span class="special">&&</span> <span class="special">(</span><span class="identifier">fabs</span><span class="special">(</span><span class="identifier">x</span><span class="special">-</span><span class="identifier">a</span><span class="special">)/</span><span class="identifier">a</span> <span class="special"><</span> <span class="number">4.5</span><span class="special">/</span><span class="identifier">sqrt</span><span class="special">(</span><span class="identifier">a</span><span class="special">))</span>
965 The latter range is valid for all types up to 128-bit long doubles, and
966 is designed to ensure that the result is larger than 10<sup>-6</sup>, the first range
967 is used only for types up to 80-bit long doubles. These domains are narrower
968 than the ones recommended by either Temme or Didonato and Morris. However,
969 using a wider range results in large and inexact (i.e. computed) values
970 being passed to the <code class="computeroutput"><span class="identifier">exp</span></code>
971 and <code class="computeroutput"><span class="identifier">erfc</span></code> functions resulting
972 in significantly larger error rates. In other words there is a fine trade
973 off here between efficiency and error. The current limits should keep the
974 number of terms required by (4) and (5) to no more than ~20 at double precision.
977 For the normalised incomplete gamma functions, calculation of the leading
978 power terms is central to the accuracy of the function. For smallish a
979 and x combining the power terms with the <a class="link" href="../../backgrounders/lanczos.html" title="The Lanczos Approximation">Lanczos
980 approximation</a> gives the greatest accuracy:
983 15) <span class="inlinemediaobject"><img src="../../../../equations/igamma12.png"></span>
986 In the event that this causes underflow/overflow then the exponent can
987 be reduced by a factor of <span class="emphasis"><em>a</em></span> and brought inside the
991 When a and x are large, we end up with a very large exponent with a base
992 near one: this will not be computed accurately via the pow function, and
993 taking logs simply leads to cancellation errors. The worst of the errors
994 can be avoided by using:
997 16) <span class="inlinemediaobject"><img src="../../../../equations/igamma13.png"></span>
1000 when <span class="emphasis"><em>a-x</em></span> is small and a and x are large. There is
1001 still a subtraction and therefore some cancellation errors - but the terms
1002 are small so the absolute error will be small - and it is absolute rather
1003 than relative error that counts in the argument to the <span class="emphasis"><em>exp</em></span>
1004 function. Note that for sufficiently large a and x the errors will still
1005 get you eventually, although this does delay the inevitable much longer
1006 than other methods. Use of <span class="emphasis"><em>log(1+x)-x</em></span> here is inspired
1007 by Temme (see references below).
1010 <a name="math_toolkit.special.sf_gamma.igamma.h5"></a>
1011 <span><a name="math_toolkit.special.sf_gamma.igamma.references"></a></span><a class="link" href="igamma.html#math_toolkit.special.sf_gamma.igamma.references">References</a>
1013 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
1014 <li class="listitem">
1015 N. M. Temme, A Set of Algorithms for the Incomplete Gamma Functions,
1016 Probability in the Engineering and Informational Sciences, 8, 1994.
1018 <li class="listitem">
1019 N. M. Temme, The Asymptotic Expansion of the Incomplete Gamma Functions,
1020 Siam J. Math Anal. Vol 10 No 4, July 1979, p757.
1022 <li class="listitem">
1023 A. R. Didonato and A. H. Morris, Computation of the Incomplete Gamma
1024 Function Ratios and their Inverse. ACM TOMS, Vol 12, No 4, Dec 1986,
1027 <li class="listitem">
1028 W. Gautschi, The Incomplete Gamma Functions Since Tricomi, In Tricomi's
1029 Ideas and Contemporary Applied Mathematics, Atti dei Convegni Lincei,
1030 n. 147, Accademia Nazionale dei Lincei, Roma, 1998, pp. 203--237.
1031 <a href="http://citeseer.ist.psu.edu/gautschi98incomplete.html" target="_top">http://citeseer.ist.psu.edu/gautschi98incomplete.html</a>
1035 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
1036 <td align="left"></td>
1037 <td align="right"><div class="copyright-footer">Copyright © 2006-2010 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno
1038 Lalande, Johan Råde, Gautam Sewani, Thijs van den Berg and Benjamin Sobotta<p>
1039 Distributed under the Boost Software License, Version 1.0. (See accompanying
1040 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
1045 <div class="spirit-nav">
1046 <a accesskey="p" href="gamma_ratios.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../sf_gamma.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="igamma_inv.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>