| [section:bernoulli_numbers Bernoulli Numbers] |
| |
| [@https://en.wikipedia.org/wiki/Bernoulli_number Bernoulli numbers] |
| are a sequence of rational numbers useful for the Taylor series expansion, |
| Euler-Maclaurin formula, and the Riemann zeta function. |
| |
| Bernoulli numbers are used in evaluation of some Boost.Math functions, |
| including the __tgamma, __lgamma and polygamma functions. |
| |
| [h4 Single Bernoulli number] |
| |
| [h4 Synopsis] |
| |
| `` |
| #include <boost/math/special_functions/bernoulli.hpp> |
| `` |
| |
| namespace boost { namespace math { |
| |
| template <class T> |
| T bernoulli_b2n(const int n); // Single Bernoulli number (default policy). |
| |
| template <class T, class Policy> |
| T bernoulli_b2n(const int n, const Policy &pol); // User policy for errors etc. |
| |
| }} // namespaces |
| |
| [h4 Description] |
| |
| Both return the (2 * n)[super th] Bernoulli number B[sub 2n]. |
| |
| Note that since all odd numbered Bernoulli numbers are zero (apart from B[sub 1] which is [plusminus][frac12]) |
| the interface will only return the even numbered Bernoulli numbers. |
| |
| This function uses fast table lookup for low-indexed Bernoulli numbers, while larger values are calculated |
| as needed and then cached. The caching mechanism requires a certain amount of thread safety code, so |
| `unchecked_bernoulli_b2n` may provide a better interface for performance critical code. |
| |
| The final __Policy argument is optional and can be used to control the behaviour of the function: |
| how it handles errors, what level of precision to use, etc. |
| |
| Refer to __policy_section for more details. |
| |
| [h4 Examples] |
| |
| [import ../../example/bernoulli_example.cpp] |
| [bernoulli_example_1] |
| |
| [bernoulli_output_1] |
| |
| [h4 Single (unchecked) Bernoulli number] |
| |
| [h4 Synopsis] |
| `` |
| #include <boost/math/special_functions/bernoulli.hpp> |
| |
| `` |
| |
| template <> |
| struct max_bernoulli_b2n<T>; |
| |
| template<class T> |
| inline T unchecked_bernoulli_b2n(unsigned n); |
| |
| `unchecked_bernoulli_b2n` provides access to Bernoulli numbers [*without any checks for overflow or invalid parameters]. |
| It is implemented as a direct (and very fast) table lookup, and while not recommended for general use it can be useful |
| inside inner loops where the ultimate performance is required, and error checking is moved outside the loop. |
| |
| The largest value you can pass to `unchecked_bernoulli_b2n<>` is `max_bernoulli_b2n<>::value`: passing values greater than |
| that will result in a buffer overrun error, so it's clearly important to place the error handling in your own code |
| when using this direct interface. |
| |
| The value of `boost::math::max_bernoulli_b2n<T>::value` varies by the type T, for types `float`/`double`/`long double` |
| it's the largest value which doesn't overflow the target type: for example, `boost::math::max_bernoulli_b2n<double>::value` is 129. |
| However, for multiprecision types, it's the largest value for which the result can be represented as the ratio of two 64-bit |
| integers, for example `boost::math::max_bernoulli_b2n<boost::multiprecision::cpp_dec_float_50>::value` is just 17. Of course |
| 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). |
| |
| [bernoulli_example_4] |
| [bernoulli_output_4] |
| |
| [h4 Multiple Bernoulli Numbers] |
| |
| [h4 Synopsis] |
| |
| `` |
| #include <boost/math/special_functions/bernoulli.hpp> |
| `` |
| |
| namespace boost { namespace math { |
| |
| // Multiple Bernoulli numbers (default policy). |
| template <class T, class OutputIterator> |
| OutputIterator bernoulli_b2n( |
| int start_index, |
| unsigned number_of_bernoullis_b2n, |
| OutputIterator out_it); |
| |
| // Multiple Bernoulli numbers (user policy). |
| template <class T, class OutputIterator, class Policy> |
| OutputIterator bernoulli_b2n( |
| int start_index, |
| unsigned number_of_bernoullis_b2n, |
| OutputIterator out_it, |
| const Policy& pol); |
| }} // namespaces |
| |
| [h4 Description] |
| |
| Two versions of the Bernoulli number function are provided to compute multiple Bernoulli numbers |
| with one call (one with default policy and the other allowing a user-defined policy). |
| |
| These return a series of Bernoulli numbers: |
| |
| [:B[sub 2*start_index],B[sub 2*(start_index+1)],...,B[sub 2*(start_index+number_of_bernoullis_b2n-1)]] |
| |
| [h4 Examples] |
| [bernoulli_example_2] |
| [bernoulli_output_2] |
| [bernoulli_example_3] |
| [bernoulli_output_3] |
| |
| The source of this example is at [@../../example/bernoulli_example.cpp bernoulli_example.cpp] |
| |
| [h4 Accuracy] |
| |
| All the functions usually return values within one ULP (unit in the last place) for the floating-point type. |
| |
| [h4 Implementation] |
| |
| The implementation details are in [@../../include/boost/math/special_functions/detail/bernoulli_details.hpp bernoulli_details.hpp] |
| and [@../../include/boost/math/special_functions/detail/unchecked_bernoulli.hpp unchecked_bernoulli.hpp]. |
| |
| For `i <= max_bernoulli_index<T>::value` this is implemented by simple table lookup from a statically initialized table; |
| for larger values of `i`, this is implemented by the Tangent Numbers algorithm as described in the paper: |
| Fast Computation of Bernoulli, Tangent and Secant Numbers, Richard P. Brent and David Harvey, |
| [@http://arxiv.org/pdf/1108.0286v3.pdf] (2011). |
| |
| [@http://mathworld.wolfram.com/TangentNumber.html Tangent (or Zag) numbers] |
| (an even alternating permutation number) are defined |
| and their generating function is also given therein. |
| |
| The relation of Tangent numbers with Bernoulli numbers ['B[sub i]] |
| is given by Brent and Harvey's equation 14: |
| |
| __spaces[equation tangent_numbers] |
| |
| Their relation with Bernoulli numbers ['B[sub i]] are defined by |
| |
| if i > 0 and i is even then |
| __spaces[equation bernoulli_numbers] [br] |
| elseif i == 0 then ['B[sub i]] = 1 [br] |
| elseif i == 1 then ['B[sub i]] = -1/2 [br] |
| elseif i < 0 or i is odd then ['B[sub i]] = 0 |
| |
| Note that computed values are stored in a fixed-size table, access is thread safe via atomic operations (i.e. lock |
| free programming), this imparts a much lower overhead on access to cached values than might otherwise be expected - |
| typically for multiprecision types the cost of thread synchronisation is negligible, while for built in types |
| this code is not normally executed anyway. For very large arguments which cannot be reasonably computed or |
| stored in our cache, an asymptotic expansion [@http://www.luschny.de/math/primes/bernincl.html due to Luschny] is used: |
| |
| [equation bernoulli_numbers2] |
| |
| [endsect] [/section:bernoulli_numbers Bernoulli Numbers] |
| |
| |
| [section:tangent_numbers Tangent Numbers] |
| |
| [@http://en.wikipedia.org/wiki/Tangent_numbers Tangent numbers], |
| also called a zag function. See also |
| [@http://mathworld.wolfram.com/TangentNumber.html Tangent number]. |
| |
| From the number, An, of alternating permutations of the set {1, ..., n}, |
| the numbers A2n+1 with odd indices are called tangent numbers or zag numbers. |
| The first few values are 1, 2, 16, 272, 7936, 353792, 22368256, 1903757312 ... |
| (sequence [@http://oeis.org/A000182 A000182 in OEIS]). |
| They are called tangent numbers because they appear as |
| numerators in the Maclaurin series of tan x. |
| |
| Tangent numbers are used in the computation of Bernoulli numbers, |
| but are also made available here. |
| |
| [h4 Synopsis] |
| `` |
| #include <boost/math/special_functions/detail/bernoulli.hpp> |
| `` |
| |
| template <class T> |
| T tangent_t2n(const int i); // Single tangent number (default policy). |
| |
| template <class T, class Policy> |
| T tangent_t2n(const int i, const Policy &pol); // Single tangent number (user policy). |
| |
| // Multiple tangent numbers (default policy). |
| template <class T, class OutputIterator> |
| OutputIterator tangent_t2n(const int start_index, |
| const unsigned number_of_tangent_t2n, |
| OutputIterator out_it); |
| |
| // Multiple tangent numbers (user policy). |
| template <class T, class OutputIterator, class Policy> |
| OutputIterator tangent_t2n(const int start_index, |
| const unsigned number_of_tangent_t2n, |
| OutputIterator out_it, |
| const Policy& pol); |
| |
| [h4 Examples] |
| |
| [tangent_example_1] |
| |
| The output is: |
| [tangent_output_1] |
| |
| The source of this example is at [../../example/bernoulli_example.cpp bernoulli_example.cpp] |
| |
| [endsect] [/section:tangent_numbers Tangent Numbers] |
| |
| [/ |
| Copyright 2013, 2014 Nikhar Agrawal, Christopher Kormanyos, John Maddock, 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). |
| ] |