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

   1 [section:number_series Number Series]
   2
   3 [section:bernoulli_numbers Bernoulli Numbers]
   4
   5 [@https://en.wikipedia.org/wiki/Bernoulli_number Bernoulli numbers]
   6 are a sequence of rational numbers useful for the Taylor series expansion,
   7 Euler-Maclaurin formula, and the Riemann zeta function.
   8
   9 Bernoulli numbers are used in evaluation of some Boost.Math functions,
  10 including the __tgamma, __lgamma and polygamma functions.
  11
  12 [h4 Single Bernoulli number]
  13
  14 [h4 Synopsis]
  15
  16 ``
  17 #include <boost/math/special_functions/bernoulli.hpp>
  18 ``
  19
  20   namespace boost { namespace math {
  21
  22   template <class T>
  23   T bernoulli_b2n(const int n);  // Single Bernoulli number (default policy).
  24
  25   template <class T, class Policy>
  26   T bernoulli_b2n(const int n, const Policy &pol); // User policy for errors etc.
  27
  28   }} // namespaces
  29
  30 [h4 Description]
  31
  32 Both return the (2 * n)[super th] Bernoulli number B[sub 2n].
  33
  34 Note that since all odd numbered Bernoulli numbers are zero (apart from B[sub 1] which is -[frac12])
  35 the interface will only return the even numbered Bernoulli numbers.
  36
  37 This function uses fast table lookup for low-indexed Bernoulli numbers, while larger values are calculated
  38 as needed and then cached.  The caching mechanism requires a certain amount of thread safety code, so
  39 `unchecked_bernoulli_b2n` may provide a better interface for performance critical code.
  40
  41 The final __Policy argument is optional and can be used to control the behaviour of the function:
  42 how it handles errors, what level of precision to use, etc.
  43
  44 Refer to __policy_section for more details.
  45
  46 [h4 Examples]
  47
  48 [import ../../example/bernoulli_example.cpp]
  49 [bernoulli_example_1]
  50
  51 [bernoulli_output_1]
  52
  53 [h4 Single (unchecked) Bernoulli number]
  54
  55 [h4 Synopsis]
  56 ``
  57 #include <boost/math/special_functions/bernoulli.hpp>
  58
  59 ``
  60
  61   template <>
  62   struct max_bernoulli_b2n<T>;
  63
  64   template<class T>
  65   inline T unchecked_bernoulli_b2n(unsigned n);
  66
  67 `unchecked_bernoulli_b2n` provides access to Bernoulli numbers [*without any checks for overflow or invalid parameters].
  68 It is implemented as a direct (and very fast) table lookup, and while not recommended for general use it can be useful
  69 inside inner loops where the ultimate performance is required, and error checking is moved outside the loop.
  70
  71 The largest value you can pass to `unchecked_bernoulli_b2n<>` is `max_bernoulli_b2n<>::value`: passing values greater than
  72 that will result in a buffer overrun error, so it's clearly important to place the error handling in your own code
  73 when using this direct interface.
  74
  75 The value of `boost::math::max_bernoulli_b2n<T>::value` varies by the type T, for types `float`/`double`/`long double`
  76 it's the largest value which doesn't overflow the target type: for example, `boost::math::max_bernoulli_b2n<double>::value` is 129.
  77 However, for multiprecision types, it's the largest value for which the result can be represented as the ratio of two 64-bit
  78 integers, for example `boost::math::max_bernoulli_b2n<boost::multiprecision::cpp_dec_float_50>::value` is just 17.  Of course
  79 larger indexes can be passed to `bernoulli_b2n<T>(n)`, but then you lose fast table lookup (i.e. values may need to be calculated).
  80
  81 [bernoulli_example_4]
  82 [bernoulli_output_4]
  83
  84 [h4 Multiple Bernoulli Numbers]
  85
  86 [h4 Synopsis]
  87
  88 ``
  89 #include <boost/math/special_functions/bernoulli.hpp>
  90 ``
  91
  92   namespace boost { namespace math {
  93
  94   // Multiple Bernoulli numbers (default policy).
  95   template <class T, class OutputIterator>
  96   OutputIterator bernoulli_b2n(
  97     int start_index,
  98     unsigned number_of_bernoullis_b2n,
  99     OutputIterator out_it);
 100
 101   // Multiple Bernoulli numbers (user policy).
 102   template <class T, class OutputIterator, class Policy>
 103   OutputIterator bernoulli_b2n(
 104     int start_index,
 105     unsigned number_of_bernoullis_b2n,
 106     OutputIterator out_it,
 107     const Policy& pol);
 108   }} // namespaces
 109
 110 [h4 Description]
 111
 112 Two versions of the Bernoulli number function are provided to compute multiple Bernoulli numbers
 113 with one call (one with default policy and the other allowing a user-defined policy).
 114
 115 These return a series of Bernoulli numbers:
 116
 117 [:B[sub 2*start_index],B[sub 2*(start_index+1)],...,B[sub 2*(start_index+number_of_bernoullis_b2n-1)]]
 118
 119 [h4 Examples]
 120 [bernoulli_example_2]
 121 [bernoulli_output_2]
 122 [bernoulli_example_3]
 123 [bernoulli_output_3]
 124
 125 The source of this example is at [@../../example/bernoulli_example.cpp bernoulli_example.cpp]
 126
 127 [h4 Accuracy]
 128
 129 All the functions usually return values within one ULP (unit in the last place) for the floating-point type.
 130
 131 [h4 Implementation]
 132
 133 The implementation details are in [@../../include/boost/math/special_functions/detail/bernoulli_details.hpp bernoulli_details.hpp]
 134 and [@../../include/boost/math/special_functions/detail/unchecked_bernoulli.hpp unchecked_bernoulli.hpp].
 135
 136 For `i <= max_bernoulli_index<T>::value` this is implemented by simple table lookup from a statically initialized table;
 137 for larger values of `i`, this is implemented by the Tangent Numbers algorithm as described in the paper:
 138 Fast Computation of Bernoulli, Tangent and Secant Numbers, Richard P. Brent and David Harvey,
 139 [@http://arxiv.org/pdf/1108.0286v3.pdf] (2011).
 140
 141 [@http://mathworld.wolfram.com/TangentNumber.html Tangent (or Zag) numbers]
 142 (an even alternating permutation number) are defined
 143 and their generating function is also given therein.
 144
 145 The relation of Tangent numbers with Bernoulli numbers  ['B[sub i]]
 146 is given by Brent and Harvey's equation 14:
 147
 148 __spaces[equation tangent_numbers]
 149
 150 Their relation with Bernoulli numbers ['B[sub i]] are defined by
 151
 152 if i > 0 and i is even then
 153 __spaces[equation bernoulli_numbers] [br]
 154 elseif i == 0 then  ['B[sub i]] = 1 [br]
 155 elseif i == 1 then  ['B[sub i]] = -1/2 [br]
 156 elseif i < 0 or i is odd then ['B[sub i]] = 0
 157
 158 Note that computed values are stored in a fixed-size table, access is thread safe via atomic operations (i.e. lock
 159 free programming), this imparts a much lower overhead on access to cached values than might otherwise be expected -
 160 typically for multiprecision types the cost of thread synchronisation is negligible, while for built in types
 161 this code is not normally executed anyway.  For very large arguments which cannot be reasonably computed or
 162 stored in our cache, an asymptotic expansion [@http://www.luschny.de/math/primes/bernincl.html due to Luschny] is used:
 163
 164 [equation bernoulli_numbers2]
 165
 166 [endsect] [/section:bernoulli_numbers Bernoulli Numbers]
 167
 168
 169 [section:tangent_numbers Tangent Numbers]
 170
 171 [@http://en.wikipedia.org/wiki/Tangent_numbers Tangent numbers],
 172 also called a zag function.  See also
 173 [@http://mathworld.wolfram.com/TangentNumber.html Tangent number].
 174
 175 The first few values are 1, 2, 16, 272, 7936, 353792, 22368256, 1903757312 ...
 176 (sequence [@http://oeis.org/A000182 A000182 in OEIS]).
 177 They are called tangent numbers because they appear as
 178 numerators in the Maclaurin series of `tan(x)`.
 179
 180 [*Important:] there are two competing definitions of Tangent numbers in common use
 181 (depending on whether you take the even or odd numbered values as non-zero), we use:
 182
 183 [equation tangent_number_def]
 184
 185 Which gives:
 186
 187 [equation tangent_number_def2]
 188
 189 Tangent numbers are used in the computation of Bernoulli numbers,
 190 but are also made available here.
 191
 192 [h4 Synopsis]
 193 ``
 194 #include <boost/math/special_functions/detail/bernoulli.hpp>
 195 ``
 196
 197   template <class T>
 198   T tangent_t2n(const int i);  // Single tangent number (default policy).
 199
 200   template <class T, class Policy>
 201   T tangent_t2n(const int i, const Policy &pol); // Single tangent number (user policy).
 202
 203   // Multiple tangent numbers (default policy).
 204   template <class T, class OutputIterator>
 205   OutputIterator tangent_t2n(const int start_index,
 206                                       const unsigned number_of_tangent_t2n,
 207                                       OutputIterator out_it);
 208
 209   // Multiple tangent numbers (user policy).
 210   template <class T, class OutputIterator, class Policy>
 211   OutputIterator tangent_t2n(const int start_index,
 212                                       const unsigned number_of_tangent_t2n,
 213                                       OutputIterator out_it,
 214                                       const Policy& pol);
 215
 216 [h4 Examples]
 217
 218 [tangent_example_1]
 219
 220 The output is:
 221 [tangent_output_1]
 222
 223 The source of this example is at [@../../example/bernoulli_example.cpp bernoulli_example.cpp]
 224
 225 [h4 Implementation]
 226
 227 Tangent numbers are calculated as intermediates in the calculation of the __bernoulli_numbers:
 228 refer to the __bernoulli_numbers documentation for details.
 229
 230 [endsect] [/section:tangent_numbers Tangent Numbers]
 231
 232 [section:primes Prime Numbers]
 233
 234 [h4 Synopsis]
 235
 236 ``
 237 #include <boost/math/special_functions/prime.hpp>
 238 ``
 239
 240   namespace boost { namespace math {
 241
 242   template <class Policy>
 243   boost::uint32_t prime(unsigned n, const Policy& pol);
 244
 245   boost::uint32_t prime(unsigned n);
 246
 247   static const unsigned max_prime = 10000;
 248
 249   }} // namespaces
 250
 251 [h4 Description]
 252
 253 The function `prime` provides fast table lookup to the first 10000 prime numbers (starting from 2
 254 as the zeroth prime: as 1 isn't terribly useful in practice).  There are two function signatures
 255 one of which takes an optional __Policy as the second parameter to control error handling.
 256
 257 The constant `max_prime` is the largest value you can pass to `prime` without incurring an error.
 258
 259 Passing a value greater than `max_prime` results in a __domain_error being raised.
 260
 261 [endsect] [/section:primes]
 262
 263 [endsect] [/Number Series]
 264
 265 [/
 266   Copyright 2013, 2014 Nikhar Agrawal, Christopher Kormanyos, John Maddock, Paul A. Bristow.
 267   Distributed under the Boost Software License, Version 1.0.
 268   (See accompanying file LICENSE_1_0.txt or copy at
 269   http://www.boost.org/LICENSE_1_0.txt).
 270 ]