ceph/src/boost/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.77.1">
   7 <link rel="home" href="../../index.html" title="Math Toolkit 2.5.1">
   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;15.&#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;15.&#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 <p>
  54         <span class="inlinemediaobject"><img src="../../../equations/polygamma1.svg"></span>
  55       </p>
  56 <p>
  57         The following graphs illustrate the behaviour of the function for odd and
  58         even order:
  59       </p>
  60 <p>
  61         <span class="inlinemediaobject"><img src="../../../graphs/polygamma2.svg" align="middle"></span>
  62   <span class="inlinemediaobject"><img src="../../../graphs/polygamma3.svg" align="middle"></span>
  63       </p>
  64 <p>
  65         The final <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">Policy</a> argument is optional and can
  66         be used to control the behaviour of the function: how it handles errors,
  67         what level of precision to use etc. Refer to the <a class="link" href="../../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">policy
  68         documentation for more details</a>.
  69       </p>
  70 <p>
  71         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
  72         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
  73         T otherwise.
  74       </p>
  75 <h5>
  76 <a name="math_toolkit.sf_gamma.polygamma.h2"></a>
  77         <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>
  78       </h5>
  79 <p>
  80         The following table shows the peak errors (in units of epsilon) found on
  81         various platforms with various floating point types. Unless otherwise specified
  82         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>.
  83       </p>
  84 <div class="table">
  85 <a name="math_toolkit.sf_gamma.polygamma.table_polygamma"></a><p class="title"><b>Table&#160;6.6.&#160;Error rates for polygamma</b></p>
  86 <div class="table-contents"><table class="table" summary="Error rates for polygamma">
  87 <colgroup>
  88 <col>
  89 <col>
  90 <col>
  91 <col>
  92 <col>
  93 </colgroup>
  94 <thead><tr>
  95 <th>
  96               </th>
  97 <th>
  98                 <p>
  99                   Microsoft Visual C++ version 12.0<br> Win32<br> double
 100                 </p>
 101               </th>
 102 <th>
 103                 <p>
 104                   GNU C++ version 5.1.0<br> linux<br> double
 105                 </p>
 106               </th>
 107 <th>
 108                 <p>
 109                   GNU C++ version 5.1.0<br> linux<br> long double
 110                 </p>
 111               </th>
 112 <th>
 113                 <p>
 114                   Sun compiler version 0x5130<br> Sun Solaris<br> long double
 115                 </p>
 116               </th>
 117 </tr></thead>
 118 <tbody>
 119 <tr>
 120 <td>
 121                 <p>
 122                   Mathematica Data
 123                 </p>
 124               </td>
 125 <td>
 126                 <p>
 127                   <span class="blue">Max = 6.34&#949; (Mean = 1.53&#949;)</span>
 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>Rmath 3.0.2:</em></span> Max = 108&#949; (Mean = 15.2&#949;))<br>
 134                   (<span class="emphasis"><em>GSL 1.16:</em></span> Max = 62.9&#949; (Mean = 12.8&#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 = 18.3&#949; (Mean = 4.16&#949;)</span>
 145                 </p>
 146               </td>
 147 </tr>
 148 <tr>
 149 <td>
 150                 <p>
 151                   Mathematica Data - large arguments
 152                 </p>
 153               </td>
 154 <td>
 155                 <p>
 156                   <span class="blue">Max = 150&#949; (Mean = 15.1&#949;)</span>
 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>Rmath 3.0.2:</em></span> <span class="red">Max
 163                   = 1.71e+56&#949; (Mean = 1.01e+55&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_Rmath_3_0_2_Mathematica_Data_large_arguments">And
 164                   other failures.</a>)</span><br> (<span class="emphasis"><em>GSL 1.16:</em></span>
 165                   Max = 244&#949; (Mean = 32.8&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_GSL_1_16_Mathematica_Data_large_arguments">And
 166                   other failures.</a>)
 167                 </p>
 168               </td>
 169 <td>
 170                 <p>
 171                   <span class="blue">Max = 2.23&#949; (Mean = 0.323&#949;)</span>
 172                 </p>
 173               </td>
 174 <td>
 175                 <p>
 176                   <span class="blue">Max = 2.35&#949; (Mean = 0.34&#949;)</span>
 177                 </p>
 178               </td>
 179 </tr>
 180 <tr>
 181 <td>
 182                 <p>
 183                   Mathematica Data - negative arguments
 184                 </p>
 185               </td>
 186 <td>
 187                 <p>
 188                   <span class="blue">Max = 497&#949; (Mean = 129&#949;)</span>
 189                 </p>
 190               </td>
 191 <td>
 192                 <p>
 193                   <span class="blue">Max = 0.516&#949; (Mean = 0.022&#949;)</span><br> <br>
 194                   (<span class="emphasis"><em>Rmath 3.0.2:</em></span> <span class="red">Max = +INF&#949; (Mean
 195                   = +INF&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_Rmath_3_0_2_Mathematica_Data_negative_arguments">And
 196                   other failures.</a>)</span><br> (<span class="emphasis"><em>GSL 1.16:</em></span>
 197                   Max = 36.6&#949; (Mean = 3.04&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_GSL_1_16_Mathematica_Data_negative_arguments">And
 198                   other failures.</a>)
 199                 </p>
 200               </td>
 201 <td>
 202                 <p>
 203                   <span class="blue">Max = 269&#949; (Mean = 87.7&#949;)</span>
 204                 </p>
 205               </td>
 206 <td>
 207                 <p>
 208                   <span class="blue">Max = 269&#949; (Mean = 87.9&#949;)</span>
 209                 </p>
 210               </td>
 211 </tr>
 212 <tr>
 213 <td>
 214                 <p>
 215                   Mathematica Data - large negative arguments
 216                 </p>
 217               </td>
 218 <td>
 219                 <p>
 220                   <span class="blue">Max = 162&#949; (Mean = 101&#949;)</span>
 221                 </p>
 222               </td>
 223 <td>
 224                 <p>
 225                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>Rmath
 226                   3.0.2:</em></span> <span class="red">Max = +INF&#949; (Mean = +INF&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_Rmath_3_0_2_Mathematica_Data_large_negative_arguments">And
 227                   other failures.</a>)</span><br> (<span class="emphasis"><em>GSL 1.16:</em></span>
 228                   Max = 1.79&#949; (Mean = 0.197&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_GSL_1_16_Mathematica_Data_large_negative_arguments">And
 229                   other failures.</a>)
 230                 </p>
 231               </td>
 232 <td>
 233                 <p>
 234                   <span class="blue">Max = 155&#949; (Mean = 96.4&#949;)</span>
 235                 </p>
 236               </td>
 237 <td>
 238                 <p>
 239                   <span class="blue">Max = 155&#949; (Mean = 96.4&#949;)</span>
 240                 </p>
 241               </td>
 242 </tr>
 243 <tr>
 244 <td>
 245                 <p>
 246                   Mathematica Data - small arguments
 247                 </p>
 248               </td>
 249 <td>
 250                 <p>
 251                   <span class="blue">Max = 3&#949; (Mean = 0.496&#949;)</span>
 252                 </p>
 253               </td>
 254 <td>
 255                 <p>
 256                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>Rmath
 257                   3.0.2:</em></span> Max = 106&#949; (Mean = 20&#949;))<br> (<span class="emphasis"><em>GSL 1.16:</em></span>
 258                   Max = 15.2&#949; (Mean = 5.03&#949;))
 259                 </p>
 260               </td>
 261 <td>
 262                 <p>
 263                   <span class="blue">Max = 3.33&#949; (Mean = 0.75&#949;)</span>
 264                 </p>
 265               </td>
 266 <td>
 267                 <p>
 268                   <span class="blue">Max = 3.33&#949; (Mean = 0.75&#949;)</span>
 269                 </p>
 270               </td>
 271 </tr>
 272 <tr>
 273 <td>
 274                 <p>
 275                   Mathematica Data - Large orders and other bug cases
 276                 </p>
 277               </td>
 278 <td>
 279                 <p>
 280                   <span class="blue">Max = 200&#949; (Mean = 57.2&#949;)</span>
 281                 </p>
 282               </td>
 283 <td>
 284                 <p>
 285                   <span class="blue">Max = 0&#949; (Mean = 0&#949;)</span><br> <br> (<span class="emphasis"><em>Rmath
 286                   3.0.2:</em></span> <span class="red">Max = +INF&#949; (Mean = +INF&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_Rmath_3_0_2_Mathematica_Data_Large_orders_and_other_bug_cases">And
 287                   other failures.</a>)</span><br> (<span class="emphasis"><em>GSL 1.16:</em></span>
 288                   Max = 151&#949; (Mean = 39.3&#949;) <a class="link" href="../logs_and_tables/logs.html#errors_GNU_C_version_5_1_0_linux_double_polygamma_GSL_1_16_Mathematica_Data_Large_orders_and_other_bug_cases">And
 289                   other failures.</a>)
 290                 </p>
 291               </td>
 292 <td>
 293                 <p>
 294                   <span class="blue">Max = 54.5&#949; (Mean = 13.3&#949;)</span>
 295                 </p>
 296               </td>
 297 <td>
 298                 <p>
 299                   <span class="blue">Max = 90.1&#949; (Mean = 30.6&#949;)</span>
 300                 </p>
 301               </td>
 302 </tr>
 303 </tbody>
 304 </table></div>
 305 </div>
 306 <br class="table-break"><p>
 307         As shown above, error rates are generally very acceptable for moderately
 308         sized arguments. Error rates should stay low for exact inputs, however, please
 309         note that the function becomes exceptionally sensitive to small changes in
 310         input for large n and negative x, indeed for cases where <span class="emphasis"><em>n!</em></span>
 311         would overflow, the function changes directly from -&#8734; to +&#8734; somewhere between
 312         each negative integer - <span class="emphasis"><em>these cases are not handled correctly</em></span>.
 313       </p>
 314 <p>
 315         <span class="bold"><strong>For these reasons results should be treated with extreme
 316         caution when <span class="emphasis"><em>n</em></span> is large and x negative</strong></span>.
 317       </p>
 318 <h5>
 319 <a name="math_toolkit.sf_gamma.polygamma.h3"></a>
 320         <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>
 321       </h5>
 322 <p>
 323         Testing is against Mathematica generated spot values to 35 digit precision.
 324       </p>
 325 <h5>
 326 <a name="math_toolkit.sf_gamma.polygamma.h4"></a>
 327         <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>
 328       </h5>
 329 <p>
 330         For x &lt; 0 the following reflection formula is used:
 331       </p>
 332 <p>
 333         <span class="inlinemediaobject"><img src="../../../equations/polygamma2.svg"></span>
 334       </p>
 335 <p>
 336         The n'th derivative of <span class="emphasis"><em>cot(x)</em></span> is tabulated for small
 337         <span class="emphasis"><em>n</em></span>, and for larger n has the general form:
 338       </p>
 339 <p>
 340         <span class="inlinemediaobject"><img src="../../../equations/polygamma3.svg"></span>
 341       </p>
 342 <p>
 343         The coefficients of the cosine terms can be calculated iteratively starting
 344         from <span class="emphasis"><em>C<sub>1,0</sub> = -1</em></span> and then using
 345       </p>
 346 <p>
 347         <span class="inlinemediaobject"><img src="../../../equations/polygamma7.svg"></span>
 348       </p>
 349 <p>
 350         to generate coefficients for n+1.
 351       </p>
 352 <p>
 353         Note that every other coefficient is zero, and therefore what we have are
 354         even or odd polynomials depending on whether n is even or odd.
 355       </p>
 356 <p>
 357         Once x is positive then we have two methods available to us, for small x
 358         we use the series expansion:
 359       </p>
 360 <p>
 361         <span class="inlinemediaobject"><img src="../../../equations/polygamma4.svg"></span>
 362       </p>
 363 <p>
 364         Note that the evaluation of zeta functions at integer values is essentially
 365         a table lookup as <a class="link" href="../zetas/zeta.html" title="Riemann Zeta Function">zeta</a> is
 366         optimized for those cases.
 367       </p>
 368 <p>
 369         For large x we use the asymptotic expansion:
 370       </p>
 371 <p>
 372         <span class="inlinemediaobject"><img src="../../../equations/polygamma5.svg"></span>
 373       </p>
 374 <p>
 375         For x in-between the two extremes we use the relation:
 376       </p>
 377 <p>
 378         <span class="inlinemediaobject"><img src="../../../equations/polygamma6.svg"></span>
 379       </p>
 380 <p>
 381         to make x large enough for the asymptotic expansion to be used.
 382       </p>
 383 <p>
 384         There are also two special cases:
 385       </p>
 386 <p>
 387         <span class="inlinemediaobject"><img src="../../../equations/polygamma8.svg"></span>
 388       </p>
 389 <p>
 390         <span class="inlinemediaobject"><img src="../../../equations/polygamma9.svg"></span>
 391       </p>
 392 </div>
 393 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 394 <td align="left"></td>
 395 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 396       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 397       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 398       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 399         Distributed under the Boost Software License, Version 1.0. (See accompanying
 400         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>)
 401       </p>
 402 </div></td>
 403 </tr></table>
 404 <hr>
 405 <div class="spirit-nav">
 406 <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>
 407 </div>
 408 </body>
 409 </html>