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