bump version to 12.2.2-pve1

[ceph.git] / ceph / src / boost / libs / math / doc / sf / number_series.qbk

[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:

[: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].

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>
  boost::uint32_t prime(unsigned n, const Policy& pol);

  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.

[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).
]