123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224 |
- [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 constexpr 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.
- This function is `constexpr` only if the compiler supports C++14 constexpr functions.
- 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:
- [equation tangent_numbers]
- Their relation with Bernoulli numbers ['B[sub i]] are defined by
- if i > 0 and i is even then
- [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).
- ]
|