1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Polygamma</title> 5<link rel="stylesheet" href="../../math.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Math Toolkit 2.12.0"> 8<link rel="up" href="../sf_gamma.html" title="Gamma Functions"> 9<link rel="prev" href="trigamma.html" title="Trigamma"> 10<link rel="next" href="gamma_ratios.html" title="Ratios of Gamma Functions"> 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="trigamma.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="gamma_ratios.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="math_toolkit.sf_gamma.polygamma"></a><a class="link" href="polygamma.html" title="Polygamma">Polygamma</a> 28</h3></div></div></div> 29<h5> 30<a name="math_toolkit.sf_gamma.polygamma.h0"></a> 31 <span class="phrase"><a name="math_toolkit.sf_gamma.polygamma.synopsis"></a></span><a class="link" href="polygamma.html#math_toolkit.sf_gamma.polygamma.synopsis">Synopsis</a> 32 </h5> 33<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">polygamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 34</pre> 35<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> 36 37<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 38<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">polygamma</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z</span><span class="special">);</span> 39 40<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">></span> 41<a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>calculated-result-type</em></span></a> <span class="identifier">polygamma</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">n</span><span class="special">,</span> <span class="identifier">T</span> <span class="identifier">z</span><span class="special">,</span> <span class="keyword">const</span> <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&);</span> 42 43<span class="special">}}</span> <span class="comment">// namespaces</span> 44</pre> 45<h5> 46<a name="math_toolkit.sf_gamma.polygamma.h1"></a> 47 <span class="phrase"><a name="math_toolkit.sf_gamma.polygamma.description"></a></span><a class="link" href="polygamma.html#math_toolkit.sf_gamma.polygamma.description">Description</a> 48 </h5> 49<p> 50 Returns the polygamma function of <span class="emphasis"><em>x</em></span>. Polygamma is defined 51 as the n'th derivative of the digamma function: 52 </p> 53<div class="blockquote"><blockquote class="blockquote"><p> 54 <span class="inlinemediaobject"><img src="../../../equations/polygamma1.svg"></span> 55 56 </p></blockquote></div> 57<p> 58 The following graphs illustrate the behaviour of the function for odd and 59 even order: 60 </p> 61<div class="blockquote"><blockquote class="blockquote"><p> 62 <span class="inlinemediaobject"><img src="../../../graphs/polygamma2.svg" align="middle"></span> 63 64 </p></blockquote></div> 65<div class="blockquote"><blockquote class="blockquote"><p> 66 <span class="inlinemediaobject"><img src="../../../graphs/polygamma3.svg" align="middle"></span> 67 68 </p></blockquote></div> 69<p> 70 The final <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can 71 be used to control the behaviour of the function: how it handles errors, 72 what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter 21. Policies: Controlling Precision, Error Handling etc">policy 73 documentation for more details</a>. 74 </p> 75<p> 76 The return type of this function is computed using the <a class="link" href="../result_type.html" title="Calculation of the Type of the Result"><span class="emphasis"><em>result 77 type calculation rules</em></span></a>: the result is of type <code class="computeroutput"><span class="keyword">double</span></code> when T is an integer type, and type 78 T otherwise. 79 </p> 80<h5> 81<a name="math_toolkit.sf_gamma.polygamma.h2"></a> 82 <span class="phrase"><a name="math_toolkit.sf_gamma.polygamma.accuracy"></a></span><a class="link" href="polygamma.html#math_toolkit.sf_gamma.polygamma.accuracy">Accuracy</a> 83 </h5> 84<p> 85 The following table shows the peak errors (in units of epsilon) found on 86 various platforms with various floating point types. Unless otherwise specified 87 any floating point type that is narrower than the one shown will have <a class="link" href="../relative_error.html#math_toolkit.relative_error.zero_error">effectively zero error</a>. 88 </p> 89<div class="table"> 90<a name="math_toolkit.sf_gamma.polygamma.table_polygamma"></a><p class="title"><b>Table 8.6. Error rates for polygamma</b></p> 91<div class="table-contents"><table class="table" summary="Error rates for polygamma"> 92<colgroup> 93<col> 94<col> 95<col> 96<col> 97<col> 98</colgroup> 99<thead><tr> 100<th> 101 </th> 102<th> 103 <p> 104 GNU C++ version 7.1.0<br> linux<br> double 105 </p> 106 </th> 107<th> 108 <p> 109 GNU C++ version 7.1.0<br> linux<br> long double 110 </p> 111 </th> 112<th> 113 <p> 114 Sun compiler version 0x5150<br> Sun Solaris<br> long double 115 </p> 116 </th> 117<th> 118 <p> 119 Microsoft Visual C++ version 14.1<br> Win32<br> double 120 </p> 121 </th> 122</tr></thead> 123<tbody> 124<tr> 125<td> 126 <p> 127 Mathematica Data 128 </p> 129 </td> 130<td> 131 <p> 132 <span class="blue">Max = 0.824ε (Mean = 0.0574ε)</span><br> 133 <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 62.9ε (Mean = 12.8ε))<br> 134 (<span class="emphasis"><em>Rmath 3.2.3:</em></span> Max = 108ε (Mean = 15.2ε)) 135 </p> 136 </td> 137<td> 138 <p> 139 <span class="blue">Max = 7.38ε (Mean = 1.84ε)</span> 140 </p> 141 </td> 142<td> 143 <p> 144 <span class="blue">Max = 34.3ε (Mean = 7.65ε)</span> 145 </p> 146 </td> 147<td> 148 <p> 149 <span class="blue">Max = 9.32ε (Mean = 1.95ε)</span> 150 </p> 151 </td> 152</tr> 153<tr> 154<td> 155 <p> 156 Mathematica Data - large arguments 157 </p> 158 </td> 159<td> 160 <p> 161 <span class="blue">Max = 0.998ε (Mean = 0.0592ε)</span><br> 162 <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 244ε (Mean = 32.8ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_GSL_2_1_Mathematica_Data_large_arguments">And 163 other failures.</a>)<br> (<span class="emphasis"><em>Rmath 3.2.3:</em></span> 164 <span class="red">Max = 1.71e+56ε (Mean = 1.01e+55ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_Rmath_3_2_3_Mathematica_Data_large_arguments">And 165 other failures.</a>)</span> 166 </p> 167 </td> 168<td> 169 <p> 170 <span class="blue">Max = 2.23ε (Mean = 0.323ε)</span> 171 </p> 172 </td> 173<td> 174 <p> 175 <span class="blue">Max = 11.1ε (Mean = 0.848ε)</span> 176 </p> 177 </td> 178<td> 179 <p> 180 <span class="blue">Max = 150ε (Mean = 13.9ε)</span> 181 </p> 182 </td> 183</tr> 184<tr> 185<td> 186 <p> 187 Mathematica Data - negative arguments 188 </p> 189 </td> 190<td> 191 <p> 192 <span class="blue">Max = 0.516ε (Mean = 0.022ε)</span><br> <br> 193 (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 36.6ε (Mean = 3.04ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_GSL_2_1_Mathematica_Data_negative_arguments">And 194 other failures.</a>)<br> (<span class="emphasis"><em>Rmath 3.2.3:</em></span> 195 Max = 0ε (Mean = 0ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_Rmath_3_2_3_Mathematica_Data_negative_arguments">And 196 other failures.</a>) 197 </p> 198 </td> 199<td> 200 <p> 201 <span class="blue">Max = 269ε (Mean = 87.7ε)</span> 202 </p> 203 </td> 204<td> 205 <p> 206 <span class="blue">Max = 269ε (Mean = 88.4ε)</span> 207 </p> 208 </td> 209<td> 210 <p> 211 <span class="blue">Max = 497ε (Mean = 129ε)</span> 212 </p> 213 </td> 214</tr> 215<tr> 216<td> 217 <p> 218 Mathematica Data - large negative arguments 219 </p> 220 </td> 221<td> 222 <p> 223 <span class="blue">Max = 0ε (Mean = 0ε)</span><br> <br> (<span class="emphasis"><em>GSL 224 2.1:</em></span> Max = 1.79ε (Mean = 0.197ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_GSL_2_1_Mathematica_Data_large_negative_arguments">And 225 other failures.</a>)<br> (<span class="emphasis"><em>Rmath 3.2.3:</em></span> 226 Max = 0ε (Mean = 0ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_Rmath_3_2_3_Mathematica_Data_large_negative_arguments">And 227 other failures.</a>) 228 </p> 229 </td> 230<td> 231 <p> 232 <span class="blue">Max = 155ε (Mean = 96.4ε)</span> 233 </p> 234 </td> 235<td> 236 <p> 237 <span class="blue">Max = 155ε (Mean = 96.4ε)</span> 238 </p> 239 </td> 240<td> 241 <p> 242 <span class="blue">Max = 162ε (Mean = 101ε)</span> 243 </p> 244 </td> 245</tr> 246<tr> 247<td> 248 <p> 249 Mathematica Data - small arguments 250 </p> 251 </td> 252<td> 253 <p> 254 <span class="blue">Max = 0ε (Mean = 0ε)</span><br> <br> (<span class="emphasis"><em>GSL 255 2.1:</em></span> Max = 15.2ε (Mean = 5.03ε))<br> (<span class="emphasis"><em>Rmath 256 3.2.3:</em></span> Max = 106ε (Mean = 20ε)) 257 </p> 258 </td> 259<td> 260 <p> 261 <span class="blue">Max = 3.33ε (Mean = 0.75ε)</span> 262 </p> 263 </td> 264<td> 265 <p> 266 <span class="blue">Max = 3.33ε (Mean = 0.75ε)</span> 267 </p> 268 </td> 269<td> 270 <p> 271 <span class="blue">Max = 3ε (Mean = 0.496ε)</span> 272 </p> 273 </td> 274</tr> 275<tr> 276<td> 277 <p> 278 Mathematica Data - Large orders and other bug cases 279 </p> 280 </td> 281<td> 282 <p> 283 <span class="blue">Max = 0ε (Mean = 0ε)</span><br> <br> (<span class="emphasis"><em>GSL 284 2.1:</em></span> Max = 151ε (Mean = 39.3ε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_GSL_2_1_Mathematica_Data_Large_orders_and_other_bug_cases">And 285 other failures.</a>)<br> (<span class="emphasis"><em>Rmath 3.2.3:</em></span> 286 <span class="red">Max = +INFε (Mean = +INFε) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_7_1_0_linux_double_polygamma_Rmath_3_2_3_Mathematica_Data_Large_orders_and_other_bug_cases">And 287 other failures.</a>)</span> 288 </p> 289 </td> 290<td> 291 <p> 292 <span class="blue">Max = 54.5ε (Mean = 13.3ε)</span> 293 </p> 294 </td> 295<td> 296 <p> 297 <span class="blue">Max = 145ε (Mean = 55.9ε)</span> 298 </p> 299 </td> 300<td> 301 <p> 302 <span class="blue">Max = 200ε (Mean = 57.2ε)</span> 303 </p> 304 </td> 305</tr> 306</tbody> 307</table></div> 308</div> 309<br class="table-break"><p> 310 As shown above, error rates are generally very acceptable for moderately 311 sized arguments. Error rates should stay low for exact inputs, however, please 312 note that the function becomes exceptionally sensitive to small changes in 313 input for large n and negative x, indeed for cases where <span class="emphasis"><em>n!</em></span> 314 would overflow, the function changes directly from -∞ to +∞ somewhere between 315 each negative integer - <span class="emphasis"><em>these cases are not handled correctly</em></span>. 316 </p> 317<p> 318 <span class="bold"><strong>For these reasons results should be treated with extreme 319 caution when <span class="emphasis"><em>n</em></span> is large and x negative</strong></span>. 320 </p> 321<h5> 322<a name="math_toolkit.sf_gamma.polygamma.h3"></a> 323 <span class="phrase"><a name="math_toolkit.sf_gamma.polygamma.testing"></a></span><a class="link" href="polygamma.html#math_toolkit.sf_gamma.polygamma.testing">Testing</a> 324 </h5> 325<p> 326 Testing is against Mathematica generated spot values to 35 digit precision. 327 </p> 328<h5> 329<a name="math_toolkit.sf_gamma.polygamma.h4"></a> 330 <span class="phrase"><a name="math_toolkit.sf_gamma.polygamma.implementation"></a></span><a class="link" href="polygamma.html#math_toolkit.sf_gamma.polygamma.implementation">Implementation</a> 331 </h5> 332<p> 333 For x < 0 the following reflection formula is used: 334 </p> 335<div class="blockquote"><blockquote class="blockquote"><p> 336 <span class="inlinemediaobject"><img src="../../../equations/polygamma2.svg"></span> 337 338 </p></blockquote></div> 339<p> 340 The n'th derivative of <span class="emphasis"><em>cot(x)</em></span> is tabulated for small 341 <span class="emphasis"><em>n</em></span>, and for larger n has the general form: 342 </p> 343<div class="blockquote"><blockquote class="blockquote"><p> 344 <span class="inlinemediaobject"><img src="../../../equations/polygamma3.svg"></span> 345 346 </p></blockquote></div> 347<p> 348 The coefficients of the cosine terms can be calculated iteratively starting 349 from <span class="emphasis"><em>C<sub>1,0</sub> = -1</em></span> and then using 350 </p> 351<div class="blockquote"><blockquote class="blockquote"><p> 352 <span class="inlinemediaobject"><img src="../../../equations/polygamma7.svg"></span> 353 354 </p></blockquote></div> 355<p> 356 to generate coefficients for n+1. 357 </p> 358<p> 359 Note that every other coefficient is zero, and therefore what we have are 360 even or odd polynomials depending on whether n is even or odd. 361 </p> 362<p> 363 Once x is positive then we have two methods available to us, for small x 364 we use the series expansion: 365 </p> 366<div class="blockquote"><blockquote class="blockquote"><p> 367 <span class="inlinemediaobject"><img src="../../../equations/polygamma4.svg"></span> 368 369 </p></blockquote></div> 370<p> 371 Note that the evaluation of zeta functions at integer values is essentially 372 a table lookup as <a class="link" href="../zetas/zeta.html" title="Riemann Zeta Function">zeta</a> is 373 optimized for those cases. 374 </p> 375<p> 376 For large x we use the asymptotic expansion: 377 </p> 378<div class="blockquote"><blockquote class="blockquote"><p> 379 <span class="inlinemediaobject"><img src="../../../equations/polygamma5.svg"></span> 380 381 </p></blockquote></div> 382<p> 383 For x in-between the two extremes we use the relation: 384 </p> 385<div class="blockquote"><blockquote class="blockquote"><p> 386 <span class="inlinemediaobject"><img src="../../../equations/polygamma6.svg"></span> 387 388 </p></blockquote></div> 389<p> 390 to make x large enough for the asymptotic expansion to be used. 391 </p> 392<p> 393 There are also two special cases: 394 </p> 395<div class="blockquote"><blockquote class="blockquote"><p> 396 <span class="inlinemediaobject"><img src="../../../equations/polygamma8.svg"></span> 397 398 </p></blockquote></div> 399<div class="blockquote"><blockquote class="blockquote"><p> 400 <span class="inlinemediaobject"><img src="../../../equations/polygamma9.svg"></span> 401 402 </p></blockquote></div> 403</div> 404<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 405<td align="left"></td> 406<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 407 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 408 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 409 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 410 Daryle Walker and Xiaogang Zhang<p> 411 Distributed under the Boost Software License, Version 1.0. (See accompanying 412 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>) 413 </p> 414</div></td> 415</tr></table> 416<hr> 417<div class="spirit-nav"> 418<a accesskey="p" href="trigamma.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="gamma_ratios.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 419</div> 420</body> 421</html> 422
