Imported Upstream version 1.51.0
[platform/upstream/boost.git] / libs / math / doc / sf_and_dist / html / math_toolkit / special / sf_gamma / igamma.html
1 <html>
2 <head>
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">
11 </head>
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>
20 </tr></table>
21 <hr>
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>
24 </div>
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
28         Functions</a>
29 </h4></div></div></div>
30 <h5>
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>
33         </h5>
34 <p>
35 </p>
36 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</span>
37 </pre>
38 <p>
39         </p>
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>
41
42 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
44
45 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
47
48 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
50
51 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
53
54 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
56
57 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
59
60 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
62
63 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
65
66 <span class="special">}}</span> <span class="comment">// namespaces</span>
67 </pre>
68 <h5>
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>
71         </h5>
72 <p>
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, &#915;(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>.
79         </p>
80 <p>
81           All of these functions require <span class="emphasis"><em>a &gt; 0</em></span> and <span class="emphasis"><em>z
82           &gt;= 0</em></span>, otherwise they return the result of <a class="link" href="../../main_overview/error_handling.html#domain_error">domain_error</a>.
83         </p>
84 <p>
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>.
88         </p>
89 <p>
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.
93         </p>
94 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
96
97 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
99 </pre>
100 <p>
101           Returns the normalised lower incomplete gamma function of a and z:
102         </p>
103 <p>
104           <span class="inlinemediaobject"><img src="../../../../equations/igamma4.png"></span>
105         </p>
106 <p>
107           This function changes rapidly from 0 to 1 around the point z == a:
108         </p>
109 <p>
110           <span class="inlinemediaobject"><img src="../../../../graphs/gamma_p.png" align="middle"></span>
111         </p>
112 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
114
115 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
117 </pre>
118 <p>
119           Returns the normalised upper incomplete gamma function of a and z:
120         </p>
121 <p>
122           <span class="inlinemediaobject"><img src="../../../../equations/igamma3.png"></span>
123         </p>
124 <p>
125           This function changes rapidly from 1 to 0 around the point z == a:
126         </p>
127 <p>
128           <span class="inlinemediaobject"><img src="../../../../graphs/gamma_q.png" align="middle"></span>
129         </p>
130 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
132
133 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
135 </pre>
136 <p>
137           Returns the full (non-normalised) lower incomplete gamma function of a
138           and z:
139         </p>
140 <p>
141           <span class="inlinemediaobject"><img src="../../../../equations/igamma2.png"></span>
142         </p>
143 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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>
145
146 <span class="keyword">template</span> <span class="special">&lt;</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">&gt;</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">&amp;);</span>
148 </pre>
149 <p>
150           Returns the full (non-normalised) upper incomplete gamma function of a
151           and z:
152         </p>
153 <p>
154           <span class="inlinemediaobject"><img src="../../../../equations/igamma1.png"></span>
155         </p>
156 <h5>
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>
159         </h5>
160 <p>
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
166           zero error</a>.
167         </p>
168 <p>
169           Note that errors grow as <span class="emphasis"><em>a</em></span> grows larger.
170         </p>
171 <p>
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.
177         </p>
178 <p>
179           All values are in units of epsilon.
180         </p>
181 <div class="table">
182 <a name="math_toolkit.special.sf_gamma.igamma.errors_in_the_function_gamma_p_a_z_"></a><p class="title"><b>Table&#160;21.&#160;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)">
184 <colgroup>
185 <col>
186 <col>
187 <col>
188 <col>
189 <col>
190 </colgroup>
191 <thead><tr>
192 <th>
193                   <p>
194                     Significand Size
195                   </p>
196                 </th>
197 <th>
198                   <p>
199                     Platform and Compiler
200                   </p>
201                 </th>
202 <th>
203                   <p>
204                     0.5 &lt; a &lt; 100
205                   </p>
206                   <p>
207                     and
208                   </p>
209                   <p>
210                     0.01*a &lt; z &lt; 100*a
211                   </p>
212                 </th>
213 <th>
214                   <p>
215                     1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
216                   </p>
217                   <p>
218                     and
219                   </p>
220                   <p>
221                     0.01*a &lt; z &lt; 100*a
222                   </p>
223                 </th>
224 <th>
225                   <p>
226                     1e-6 &lt; a &lt; 1.7x10<sup>6</sup>
227                   </p>
228                   <p>
229                     and
230                   </p>
231                   <p>
232                     1 &lt; z &lt; 100*a
233                   </p>
234                 </th>
235 </tr></thead>
236 <tbody>
237 <tr>
238 <td>
239                   <p>
240                     53
241                   </p>
242                 </td>
243 <td>
244                   <p>
245                     Win32, Visual C++ 8
246                   </p>
247                 </td>
248 <td>
249                   <p>
250                     Peak=36 Mean=9.1
251                   </p>
252                   <p>
253                     (GSL Peak=342 Mean=46)
254                   </p>
255                   <p>
256                     (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak=491
257                     Mean=102)
258                   </p>
259                 </td>
260 <td>
261                   <p>
262                     Peak=4.5 Mean=1.4
263                   </p>
264                   <p>
265                     (GSL Peak=4.8 Mean=0.76)
266                   </p>
267                   <p>
268                     (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak=21
269                     Mean=5.6)
270                   </p>
271                 </td>
272 <td>
273                   <p>
274                     Peak=244 Mean=21
275                   </p>
276                   <p>
277                     (GSL Peak=1022 Mean=1054)
278                   </p>
279                   <p>
280                     (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak~8x10<sup>6</sup> Mean~7x10<sup>4</sup>)
281                   </p>
282                 </td>
283 </tr>
284 <tr>
285 <td>
286                   <p>
287                     64
288                   </p>
289                 </td>
290 <td>
291                   <p>
292                     RedHat Linux IA32, gcc-3.3
293                   </p>
294                 </td>
295 <td>
296                   <p>
297                     Peak=241 Mean=36
298                   </p>
299                 </td>
300 <td>
301                   <p>
302                     Peak=4.7 Mean=1.5
303                   </p>
304                 </td>
305 <td>
306                   <p>
307                     Peak~30,220 Mean=1929
308                   </p>
309                 </td>
310 </tr>
311 <tr>
312 <td>
313                   <p>
314                     64
315                   </p>
316                 </td>
317 <td>
318                   <p>
319                     Redhat Linux IA64, gcc-3.4
320                   </p>
321                 </td>
322 <td>
323                   <p>
324                     Peak=41 Mean=10
325                   </p>
326                 </td>
327 <td>
328                   <p>
329                     Peak=4.7 Mean=1.4
330                   </p>
331                 </td>
332 <td>
333                   <p>
334                     Peak~30,790 Mean=1864
335                   </p>
336                 </td>
337 </tr>
338 <tr>
339 <td>
340                   <p>
341                     113
342                   </p>
343                 </td>
344 <td>
345                   <p>
346                     HPUX IA64, aCC A.06.06
347                   </p>
348                 </td>
349 <td>
350                   <p>
351                     Peak=40.2 Mean=10.2
352                   </p>
353                 </td>
354 <td>
355                   <p>
356                     Peak=5 Mean=1.6
357                   </p>
358                 </td>
359 <td>
360                   <p>
361                     Peak=5,476 Mean=440
362                   </p>
363                 </td>
364 </tr>
365 </tbody>
366 </table></div>
367 </div>
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&#160;22.&#160;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)">
371 <colgroup>
372 <col>
373 <col>
374 <col>
375 <col>
376 <col>
377 </colgroup>
378 <thead><tr>
379 <th>
380                   <p>
381                     Significand Size
382                   </p>
383                 </th>
384 <th>
385                   <p>
386                     Platform and Compiler
387                   </p>
388                 </th>
389 <th>
390                   <p>
391                     0.5 &lt; a &lt; 100
392                   </p>
393                   <p>
394                     and
395                   </p>
396                   <p>
397                     0.01*a &lt; z &lt; 100*a
398                   </p>
399                 </th>
400 <th>
401                   <p>
402                     1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
403                   </p>
404                   <p>
405                     and
406                   </p>
407                   <p>
408                     0.01*a &lt; z &lt; 100*a
409                   </p>
410                 </th>
411 <th>
412                   <p>
413                     1x10<sup>-6</sup> &lt; a &lt; 1.7x10<sup>6</sup>
414                   </p>
415                   <p>
416                     and
417                   </p>
418                   <p>
419                     1 &lt; z &lt; 100*a
420                   </p>
421                 </th>
422 </tr></thead>
423 <tbody>
424 <tr>
425 <td>
426                   <p>
427                     53
428                   </p>
429                 </td>
430 <td>
431                   <p>
432                     Win32, Visual C++ 8
433                   </p>
434                 </td>
435 <td>
436                   <p>
437                     Peak=28.3 Mean=7.2
438                   </p>
439                   <p>
440                     (GSL Peak=201 Mean=13)
441                   </p>
442                   <p>
443                     (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak=556
444                     Mean=97)
445                   </p>
446                 </td>
447 <td>
448                   <p>
449                     Peak=4.8 Mean=1.6
450                   </p>
451                   <p>
452                     (GSL Peak~1.3x10<sup>10</sup> Mean=1x10<sup>+9</sup>)
453                   </p>
454                   <p>
455                     (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak~3x10<sup>11</sup> Mean=4x10<sup>10</sup>)
456                   </p>
457                 </td>
458 <td>
459                   <p>
460                     Peak=469 Mean=33
461                   </p>
462                   <p>
463                     (GSL Peak=27,050 Mean=2159)
464                   </p>
465                   <p>
466                     (<a href="http://www.netlib.org/cephes/" target="_top">Cephes</a> Peak~8x10<sup>6</sup> Mean~7x10<sup>5</sup>)
467                   </p>
468                 </td>
469 </tr>
470 <tr>
471 <td>
472                   <p>
473                     64
474                   </p>
475                 </td>
476 <td>
477                   <p>
478                     RedHat Linux IA32, gcc-3.3
479                   </p>
480                 </td>
481 <td>
482                   <p>
483                     Peak=280 Mean=33
484                   </p>
485                 </td>
486 <td>
487                   <p>
488                     Peak=4.1 Mean=1.6
489                   </p>
490                 </td>
491 <td>
492                   <p>
493                     Peak=11,490 Mean=732
494                   </p>
495                 </td>
496 </tr>
497 <tr>
498 <td>
499                   <p>
500                     64
501                   </p>
502                 </td>
503 <td>
504                   <p>
505                     Redhat Linux IA64, gcc-3.4
506                   </p>
507                 </td>
508 <td>
509                   <p>
510                     Peak=32 Mean=9.4
511                   </p>
512                 </td>
513 <td>
514                   <p>
515                     Peak=4.7 Mean=1.5
516                   </p>
517                 </td>
518 <td>
519                   <p>
520                     Peak=6815 Mean=414
521                   </p>
522                 </td>
523 </tr>
524 <tr>
525 <td>
526                   <p>
527                     113
528                   </p>
529                 </td>
530 <td>
531                   <p>
532                     HPUX IA64, aCC A.06.06
533                   </p>
534                 </td>
535 <td>
536                   <p>
537                     Peak=37 Mean=10
538                   </p>
539                 </td>
540 <td>
541                   <p>
542                     Peak=11.2 Mean=2.0
543                   </p>
544                 </td>
545 <td>
546                   <p>
547                     Peak=4,999 Mean=298
548                   </p>
549                 </td>
550 </tr>
551 </tbody>
552 </table></div>
553 </div>
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&#160;23.&#160;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)">
557 <colgroup>
558 <col>
559 <col>
560 <col>
561 <col>
562 </colgroup>
563 <thead><tr>
564 <th>
565                   <p>
566                     Significand Size
567                   </p>
568                 </th>
569 <th>
570                   <p>
571                     Platform and Compiler
572                   </p>
573                 </th>
574 <th>
575                   <p>
576                     0.5 &lt; a &lt; 100
577                   </p>
578                   <p>
579                     and
580                   </p>
581                   <p>
582                     0.01*a &lt; z &lt; 100*a
583                   </p>
584                 </th>
585 <th>
586                   <p>
587                     1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
588                   </p>
589                   <p>
590                     and
591                   </p>
592                   <p>
593                     0.01*a &lt; z &lt; 100*a
594                   </p>
595                 </th>
596 </tr></thead>
597 <tbody>
598 <tr>
599 <td>
600                   <p>
601                     53
602                   </p>
603                 </td>
604 <td>
605                   <p>
606                     Win32, Visual C++ 8
607                   </p>
608                 </td>
609 <td>
610                   <p>
611                     Peak=5.5 Mean=1.4
612                   </p>
613                 </td>
614 <td>
615                   <p>
616                     Peak=3.6 Mean=0.78
617                   </p>
618                 </td>
619 </tr>
620 <tr>
621 <td>
622                   <p>
623                     64
624                   </p>
625                 </td>
626 <td>
627                   <p>
628                     RedHat Linux IA32, gcc-3.3
629                   </p>
630                 </td>
631 <td>
632                   <p>
633                     Peak=402 Mean=79
634                   </p>
635                 </td>
636 <td>
637                   <p>
638                     Peak=3.4 Mean=0.8
639                   </p>
640                 </td>
641 </tr>
642 <tr>
643 <td>
644                   <p>
645                     64
646                   </p>
647                 </td>
648 <td>
649                   <p>
650                     Redhat Linux IA64, gcc-3.4
651                   </p>
652                 </td>
653 <td>
654                   <p>
655                     Peak=6.8 Mean=1.4
656                   </p>
657                 </td>
658 <td>
659                   <p>
660                     Peak=3.4 Mean=0.78
661                   </p>
662                 </td>
663 </tr>
664 <tr>
665 <td>
666                   <p>
667                     113
668                   </p>
669                 </td>
670 <td>
671                   <p>
672                     HPUX IA64, aCC A.06.06
673                   </p>
674                 </td>
675 <td>
676                   <p>
677                     Peak=6.1 Mean=1.8
678                   </p>
679                 </td>
680 <td>
681                   <p>
682                     Peak=3.7 Mean=0.89
683                   </p>
684                 </td>
685 </tr>
686 </tbody>
687 </table></div>
688 </div>
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&#160;24.&#160;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)">
692 <colgroup>
693 <col>
694 <col>
695 <col>
696 <col>
697 </colgroup>
698 <thead><tr>
699 <th>
700                   <p>
701                     Significand Size
702                   </p>
703                 </th>
704 <th>
705                   <p>
706                     Platform and Compiler
707                   </p>
708                 </th>
709 <th>
710                   <p>
711                     0.5 &lt; a &lt; 100
712                   </p>
713                   <p>
714                     and
715                   </p>
716                   <p>
717                     0.01*a &lt; z &lt; 100*a
718                   </p>
719                 </th>
720 <th>
721                   <p>
722                     1x10<sup>-12</sup> &lt; a &lt; 5x10<sup>-2</sup>
723                   </p>
724                   <p>
725                     and
726                   </p>
727                   <p>
728                     0.01*a &lt; z &lt; 100*a
729                   </p>
730                 </th>
731 </tr></thead>
732 <tbody>
733 <tr>
734 <td>
735                   <p>
736                     53
737                   </p>
738                 </td>
739 <td>
740                   <p>
741                     Win32, Visual C++ 8
742                   </p>
743                 </td>
744 <td>
745                   <p>
746                     Peak=5.9 Mean=1.5
747                   </p>
748                 </td>
749 <td>
750                   <p>
751                     Peak=1.8 Mean=0.6
752                   </p>
753                 </td>
754 </tr>
755 <tr>
756 <td>
757                   <p>
758                     64
759                   </p>
760                 </td>
761 <td>
762                   <p>
763                     RedHat Linux IA32, gcc-3.3
764                   </p>
765                 </td>
766 <td>
767                   <p>
768                     Peak=596 Mean=116
769                   </p>
770                 </td>
771 <td>
772                   <p>
773                     Peak=3.2 Mean=0.84
774                   </p>
775                 </td>
776 </tr>
777 <tr>
778 <td>
779                   <p>
780                     64
781                   </p>
782                 </td>
783 <td>
784                   <p>
785                     Redhat Linux IA64, gcc-3.4.4
786                   </p>
787                 </td>
788 <td>
789                   <p>
790                     Peak=40.2 Mean=2.5
791                   </p>
792                 </td>
793 <td>
794                   <p>
795                     Peak=3.2 Mean=0.8
796                   </p>
797                 </td>
798 </tr>
799 <tr>
800 <td>
801                   <p>
802                     113
803                   </p>
804                 </td>
805 <td>
806                   <p>
807                     HPUX IA64, aCC A.06.06
808                   </p>
809                 </td>
810 <td>
811                   <p>
812                     Peak=364 Mean=17.6
813                   </p>
814                 </td>
815 <td>
816                   <p>
817                     Peak=12.7 Mean=1.8
818                   </p>
819                 </td>
820 </tr>
821 </tbody>
822 </table></div>
823 </div>
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>
827         </h5>
828 <p>
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.
839         </p>
840 <h5>
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>
843         </h5>
844 <p>
845           These four functions share a common implementation since they are all related
846           via:
847         </p>
848 <p>
849           1) <span class="inlinemediaobject"><img src="../../../../equations/igamma5.png"></span>
850         </p>
851 <p>
852           2) <span class="inlinemediaobject"><img src="../../../../equations/igamma6.png"></span>
853         </p>
854 <p>
855           3) <span class="inlinemediaobject"><img src="../../../../equations/igamma7.png"></span>
856         </p>
857 <p>
858           The lower incomplete gamma is computed from its series representation:
859         </p>
860 <p>
861           4) <span class="inlinemediaobject"><img src="../../../../equations/igamma8.png"></span>
862         </p>
863 <p>
864           Or by subtraction of the upper integral from either &#915;(a) or 1 when <span class="emphasis"><em>x
865           - (1</em></span>(3x)) &gt; a and x &gt; 1.1/.
866         </p>
867 <p>
868           The upper integral is computed from Legendre's continued fraction representation:
869         </p>
870 <p>
871           5) <span class="inlinemediaobject"><img src="../../../../equations/igamma9.png"></span>
872         </p>
873 <p>
874           When <span class="emphasis"><em>(x &gt; 1.1)</em></span> or by subtraction of the lower integral
875           from either &#915;(a) or 1 when <span class="emphasis"><em>x - (1</em></span>(3x)) &lt; a/.
876         </p>
877 <p>
878           For <span class="emphasis"><em>x &lt; 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:
881         </p>
882 <p>
883           6) <span class="inlinemediaobject"><img src="../../../../equations/igamma10.png"></span>
884         </p>
885 <p>
886           That lends itself to calculation of the upper integral via rearrangement
887           to:
888         </p>
889 <p>
890           7) <span class="inlinemediaobject"><img src="../../../../equations/igamma11.png"></span>
891         </p>
892 <p>
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.
901         </p>
902 <p>
903           For <span class="emphasis"><em>x &lt; 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 &lt; a</em></span> as the crossover criterion for <span class="emphasis"><em>0.5 &lt;
906           x &lt;= 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 &lt;=
908           0.5</em></span> then using <span class="emphasis"><em>-0.4 / log(x) &lt; 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).
911         </p>
912 <p>
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 &lt;=
916           a &lt; 30</em></span> then the following finite sum is used:
917         </p>
918 <p>
919           9) <span class="inlinemediaobject"><img src="../../../../equations/igamma1f.png"></span>
920         </p>
921 <p>
922           While for half integers in the range <span class="emphasis"><em>0.5 &lt;= a &lt; 30</em></span>
923           then the following finite sum is used:
924         </p>
925 <p>
926           10) <span class="inlinemediaobject"><img src="../../../../equations/igamma2f.png"></span>
927         </p>
928 <p>
929           These are both more stable and more efficient than the continued fraction
930           alternative.
931         </p>
932 <p>
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:
936         </p>
937 <p>
938           11) <span class="inlinemediaobject"><img src="../../../../equations/igamma16.png"></span>
939         </p>
940 <p>
941           12) <span class="inlinemediaobject"><img src="../../../../equations/igamma17.png"></span>
942         </p>
943 <p>
944           13) <span class="inlinemediaobject"><img src="../../../../equations/igamma18.png"></span>
945         </p>
946 <p>
947           14) <span class="inlinemediaobject"><img src="../../../../equations/igamma19.png"></span>
948         </p>
949 <p>
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
956         </p>
957 <pre class="programlisting"><span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="number">20</span><span class="special">)</span> <span class="special">&amp;&amp;</span> <span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="number">200</span><span class="special">)</span> <span class="special">&amp;&amp;</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">&lt;</span> <span class="number">0.4</span>
958 </pre>
959 <p>
960           And:
961         </p>
962 <pre class="programlisting"><span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;</span> <span class="number">200</span><span class="special">)</span> <span class="special">&amp;&amp;</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">&lt;</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>
963 </pre>
964 <p>
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.
975         </p>
976 <p>
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:
981         </p>
982 <p>
983           15) <span class="inlinemediaobject"><img src="../../../../equations/igamma12.png"></span>
984         </p>
985 <p>
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
988           power term.
989         </p>
990 <p>
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:
995         </p>
996 <p>
997           16) <span class="inlinemediaobject"><img src="../../../../equations/igamma13.png"></span>
998         </p>
999 <p>
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).
1008         </p>
1009 <h5>
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>
1012         </h5>
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.
1017             </li>
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.
1021             </li>
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,
1025               p377.
1026             </li>
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>
1032             </li>
1033 </ul></div>
1034 </div>
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 &#169; 2006-2010 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno
1038       Lalande, Johan R&#229;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>)
1041       </p>
1042 </div></td>
1043 </tr></table>
1044 <hr>
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>
1047 </div>
1048 </body>
1049 </html>