libs/math/doc/html/math_toolkit/sf_gamma/polygamma.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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.11.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">&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">polygamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</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">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</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">&lt;</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&gt;</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&#160;20.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a><span class="special">&amp;);</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&#160;20.&#160;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&#160;20.&#160;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&#160;8.6.&#160;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&#949; (Mean = 0.0574&#949;)</span><br>
 133                   <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 62.9&#949; (Mean = 12.8&#949;))<br>
 134                   (<span class="emphasis"><em>Rmath 3.2.3:</em></span> Max = 108&#949; (Mean = 15.2&#949;))
 135                 </p>
 136               </td>
 137 <td>
 138                 <p>
 139                   <span class="blue">Max = 7.38&#949; (Mean = 1.84&#949;)</span>
 140                 </p>
 141               </td>
 142 <td>
 143                 <p>
 144                   <span class="blue">Max = 34.3&#949; (Mean = 7.65&#949;)</span>
 145                 </p>
 146               </td>
 147 <td>
 148                 <p>
 149                   <span class="blue">Max = 9.32&#949; (Mean = 1.95&#949;)</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&#949; (Mean = 0.0592&#949;)</span><br>
 162                   <br> (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 244&#949; (Mean = 32.8&#949;) <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&#949; (Mean = 1.01e+55&#949;) <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&#949; (Mean = 0.323&#949;)</span>
 171                 </p>
 172               </td>
 173 <td>
 174                 <p>
 175                   <span class="blue">Max = 11.1&#949; (Mean = 0.848&#949;)</span>
 176                 </p>
 177               </td>
 178 <td>
 179                 <p>
 180                   <span class="blue">Max = 150&#949; (Mean = 13.9&#949;)</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&#949; (Mean = 0.022&#949;)</span><br> <br>
 193                   (<span class="emphasis"><em>GSL 2.1:</em></span> Max = 36.6&#949; (Mean = 3.04&#949;) <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&#949; (Mean = 0&#949;) <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&#949; (Mean = 87.7&#949;)</span>
 202                 </p>
 203               </td>
 204 <td>
 205                 <p>
 206                   <span class="blue">Max = 269&#949; (Mean = 88.4&#949;)</span>
 207                 </p>
 208               </td>
 209 <td>
 210                 <p>
 211                   <span class="blue">Max = 497&#949; (Mean = 129&#949;)</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&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 224                   2.1:</em></span> Max = 1.79&#949; (Mean = 0.197&#949;) <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&#949; (Mean = 0&#949;) <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&#949; (Mean = 96.4&#949;)</span>
 233                 </p>
 234               </td>
 235 <td>
 236                 <p>
 237                   <span class="blue">Max = 155&#949; (Mean = 96.4&#949;)</span>
 238                 </p>
 239               </td>
 240 <td>
 241                 <p>
 242                   <span class="blue">Max = 162&#949; (Mean = 101&#949;)</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&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 255                   2.1:</em></span> Max = 15.2&#949; (Mean = 5.03&#949;))<br> (<span class="emphasis"><em>Rmath
 256                   3.2.3:</em></span> Max = 106&#949; (Mean = 20&#949;))
 257                 </p>
 258               </td>
 259 <td>
 260                 <p>
 261                   <span class="blue">Max = 3.33&#949; (Mean = 0.75&#949;)</span>
 262                 </p>
 263               </td>
 264 <td>
 265                 <p>
 266                   <span class="blue">Max = 3.33&#949; (Mean = 0.75&#949;)</span>
 267                 </p>
 268               </td>
 269 <td>
 270                 <p>
 271                   <span class="blue">Max = 3&#949; (Mean = 0.496&#949;)</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&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>GSL
 284                   2.1:</em></span> Max = 151&#949; (Mean = 39.3&#949;) <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&#949; (Mean = +INF&#949;) <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&#949; (Mean = 13.3&#949;)</span>
 293                 </p>
 294               </td>
 295 <td>
 296                 <p>
 297                   <span class="blue">Max = 145&#949; (Mean = 55.9&#949;)</span>
 298                 </p>
 299               </td>
 300 <td>
 301                 <p>
 302                   <span class="blue">Max = 200&#949; (Mean = 57.2&#949;)</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 -&#8734; to +&#8734; 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 &lt; 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 &#169; 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&#229;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>