[ceph.git] / ceph / src / boost / libs / math / doc / sf / polygamma.qbk

[section:polygamma Polygamma]

[h4 Synopsis]

``
#include <boost/math/special_functions/polygamma.hpp>
``

  namespace boost{ namespace math{
  
  template <class T>
  ``__sf_result`` polygamma(int n, T z);
  
  template <class T, class ``__Policy``>
  ``__sf_result`` polygamma(int n, T z, const ``__Policy``&);
  
  }} // namespaces
  
[h4 Description]

Returns the polygamma function of /x/. Polygamma is defined as the n'th
derivative of the digamma function:

[equation polygamma1]

The following graphs illustrate the behaviour of the function for odd and even order:

[graph polygamma2]
[graph polygamma3]

[optional_policy]

The return type of this function is computed using the __arg_promotion_rules:
the result is of type `double` when T is an integer type, and type T otherwise.

[h4 Accuracy]

The following table shows the peak errors (in units of epsilon) 
found on various platforms with various floating point types.
Unless otherwise specified any floating point type that is narrower
than the one shown will have __zero_error.

[table_polygamma]

As shown above, error rates are generally very acceptable for moderately sized
arguments.  Error rates should stay low for exact inputs, however, please note that the
function becomes exceptionally sensitive to small changes in input for large n and negative x,
indeed for cases where ['n!] would overflow, the function changes directly from -[infin] to
+[infin] somewhere between each negative integer - ['these cases are not handled correctly].

[*For these reasons results should be treated with extreme caution when /n/ is large and x negative].

[h4 Testing]

Testing is against Mathematica generated spot values to 35 digit precision.

[h4 Implementation]

For x < 0 the following reflection formula is used:

[equation polygamma2]

The n'th derivative of ['cot(x)] is tabulated for small /n/, and for larger n
has the general form:

[equation polygamma3]

The coefficients of the cosine terms can be calculated iteratively starting
from ['C[sub 1,0] = -1] and then using

[equation polygamma7]

to generate coefficients for n+1.

Note that every other coefficient is zero, and therefore what we have are
even or odd polynomials depending on whether n is even or odd.

Once x is positive then we have two methods available to us, for small x
we use the series expansion:

[equation polygamma4]

Note that the evaluation of zeta functions at integer values is essentially a table lookup
as __zeta is optimized for those cases.

For large x we use the asymptotic expansion:

[equation polygamma5]

For x in-between the two extremes we use the relation:

[equation polygamma6]

to make x large enough for the asymptotic expansion to be used.

There are also two special cases:

[equation polygamma8]

[equation polygamma9]

[endsect][/section:polygamma The Polygamma Function]

[/ 
  Copyright 2014 John Maddock and Paul A. Bristow.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]
Commit	Line	Data
7c673cae FG	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