ceph/src/boost/libs/math/doc/sf/polygamma.qbk

   1 [section:polygamma Polygamma]
   2
   3 [h4 Synopsis]
   4
   5 ``
   6 #include <boost/math/special_functions/polygamma.hpp>
   7 ``
   8
   9   namespace boost{ namespace math{
  10
  11   template <class T>
  12   ``__sf_result`` polygamma(int n, T z);
  13
  14   template <class T, class ``__Policy``>
  15   ``__sf_result`` polygamma(int n, T z, const ``__Policy``&);
  16
  17   }} // namespaces
  18
  19 [h4 Description]
  20
  21 Returns the polygamma function of /x/. Polygamma is defined as the n'th
  22 derivative of the digamma function:
  23
  24 [equation polygamma1]
  25
  26 The following graphs illustrate the behaviour of the function for odd and even order:
  27
  28 [graph polygamma2]
  29 [graph polygamma3]
  30
  31 [optional_policy]
  32
  33 The return type of this function is computed using the __arg_promotion_rules:
  34 the result is of type `double` when T is an integer type, and type T otherwise.
  35
  36 [h4 Accuracy]
  37
  38 The following table shows the peak errors (in units of epsilon)
  39 found on various platforms with various floating point types.
  40 Unless otherwise specified any floating point type that is narrower
  41 than the one shown will have __zero_error.
  42
  43 [table_polygamma]
  44
  45 As shown above, error rates are generally very acceptable for moderately sized
  46 arguments.  Error rates should stay low for exact inputs, however, please note that the
  47 function becomes exceptionally sensitive to small changes in input for large n and negative x,
  48 indeed for cases where ['n!] would overflow, the function changes directly from -[infin] to
  49 +[infin] somewhere between each negative integer - ['these cases are not handled correctly].
  50
  51 [*For these reasons results should be treated with extreme caution when /n/ is large and x negative].
  52
  53 [h4 Testing]
  54
  55 Testing is against Mathematica generated spot values to 35 digit precision.
  56
  57 [h4 Implementation]
  58
  59 For x < 0 the following reflection formula is used:
  60
  61 [equation polygamma2]
  62
  63 The n'th derivative of ['cot(x)] is tabulated for small /n/, and for larger n
  64 has the general form:
  65
  66 [equation polygamma3]
  67
  68 The coefficients of the cosine terms can be calculated iteratively starting
  69 from ['C[sub 1,0] = -1] and then using
  70
  71 [equation polygamma7]
  72
  73 to generate coefficients for n+1.
  74
  75 Note that every other coefficient is zero, and therefore what we have are
  76 even or odd polynomials depending on whether n is even or odd.
  77
  78 Once x is positive then we have two methods available to us, for small x
  79 we use the series expansion:
  80
  81 [equation polygamma4]
  82
  83 Note that the evaluation of zeta functions at integer values is essentially a table lookup
  84 as __zeta is optimized for those cases.
  85
  86 For large x we use the asymptotic expansion:
  87
  88 [equation polygamma5]
  89
  90 For x in-between the two extremes we use the relation:
  91
  92 [equation polygamma6]
  93
  94 to make x large enough for the asymptotic expansion to be used.
  95
  96 There are also two special cases:
  97
  98 [equation polygamma8]
  99
 100 [equation polygamma9]
 101
 102 [endsect][/section:polygamma The Polygamma Function]
 103
 104 [/
 105   Copyright 2014 John Maddock and Paul A. Bristow.
 106   Distributed under the Boost Software License, Version 1.0.
 107   (See accompanying file LICENSE_1_0.txt or copy at
 108   http://www.boost.org/LICENSE_1_0.txt).
 109 ]
 110