272 lines
9.5 KiB
Plaintext
272 lines
9.5 KiB
Plaintext
[section:number_series Number Series]
|
|
|
|
[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 -[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:
|
|
|
|
[expression [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 [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].
|
|
|
|
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)`.
|
|
|
|
[*Important:] there are two competing definitions of Tangent numbers in common use
|
|
(depending on whether you take the even or odd numbered values as non-zero), we use:
|
|
|
|
[equation tangent_number_def]
|
|
|
|
Which gives:
|
|
|
|
[equation tangent_number_def2]
|
|
|
|
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]
|
|
|
|
[h4 Implementation]
|
|
|
|
Tangent numbers are calculated as intermediates in the calculation of the __bernoulli_numbers:
|
|
refer to the __bernoulli_numbers documentation for details.
|
|
|
|
[endsect] [/section:tangent_numbers Tangent Numbers]
|
|
|
|
[section:primes Prime Numbers]
|
|
|
|
[h4 Synopsis]
|
|
|
|
``
|
|
#include <boost/math/special_functions/prime.hpp>
|
|
``
|
|
|
|
namespace boost { namespace math {
|
|
|
|
template <class Policy>
|
|
constexpr boost::uint32_t prime(unsigned n, const Policy& pol);
|
|
|
|
constexpr boost::uint32_t prime(unsigned n);
|
|
|
|
static const unsigned max_prime = 10000;
|
|
|
|
}} // namespaces
|
|
|
|
[h4 Description]
|
|
|
|
The function `prime` provides fast table lookup to the first 10000 prime numbers (starting from 2
|
|
as the zeroth prime: as 1 isn't terribly useful in practice). There are two function signatures
|
|
one of which takes an optional __Policy as the second parameter to control error handling.
|
|
|
|
The constant `max_prime` is the largest value you can pass to `prime` without incurring an error.
|
|
|
|
Passing a value greater than `max_prime` results in a __domain_error being raised.
|
|
|
|
This function is `constexpr` only if the compiler supports C++14 constexpr functions.
|
|
|
|
[endsect] [/section:primes]
|
|
|
|
[endsect] [/Number Series]
|
|
|
|
[/
|
|
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).
|
|
]
|