• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[section:bernoulli_numbers Bernoulli Numbers]
2
3[@https://en.wikipedia.org/wiki/Bernoulli_number Bernoulli numbers]
4are a sequence of rational numbers useful for the Taylor series expansion,
5Euler-Maclaurin formula, and the Riemann zeta function.
6
7Bernoulli numbers are used in evaluation of some Boost.Math functions,
8including the __tgamma, __lgamma and polygamma functions.
9
10[h4 Single Bernoulli number]
11
12[h4 Synopsis]
13
14``
15#include <boost/math/special_functions/bernoulli.hpp>
16``
17
18  namespace boost { namespace math {
19
20  template <class T>
21  T bernoulli_b2n(const int n);  // Single Bernoulli number (default policy).
22
23  template <class T, class Policy>
24  T bernoulli_b2n(const int n, const Policy &pol); // User policy for errors etc.
25
26  }} // namespaces
27
28[h4 Description]
29
30Both return the (2 * n)[super th] Bernoulli number B[sub 2n].
31
32Note that since all odd numbered Bernoulli numbers are zero (apart from B[sub 1] which is [plusminus][frac12])
33the interface will only return the even numbered Bernoulli numbers.
34
35This function uses fast table lookup for low-indexed Bernoulli numbers, while larger values are calculated
36as needed and then cached.  The caching mechanism requires a certain amount of thread safety code, so
37`unchecked_bernoulli_b2n` may provide a better interface for performance critical code.
38
39The final __Policy argument is optional and can be used to control the behaviour of the function:
40how it handles errors, what level of precision to use, etc.
41
42Refer to __policy_section for more details.
43
44[h4 Examples]
45
46[import ../../example/bernoulli_example.cpp]
47[bernoulli_example_1]
48
49[bernoulli_output_1]
50
51[h4 Single (unchecked) Bernoulli number]
52
53[h4 Synopsis]
54``
55#include <boost/math/special_functions/bernoulli.hpp>
56
57``
58
59  template <>
60  struct max_bernoulli_b2n<T>;
61
62  template<class T>
63  inline constexpr T unchecked_bernoulli_b2n(unsigned n);
64
65`unchecked_bernoulli_b2n` provides access to Bernoulli numbers [*without any checks for overflow or invalid parameters].
66It is implemented as a direct (and very fast) table lookup, and while not recommended for general use it can be useful
67inside inner loops where the ultimate performance is required, and error checking is moved outside the loop.
68
69The largest value you can pass to `unchecked_bernoulli_b2n<>` is `max_bernoulli_b2n<>::value`: passing values greater than
70that will result in a buffer overrun error, so it's clearly important to place the error handling in your own code
71when using this direct interface.
72
73This function is `constexpr` only if the compiler supports C++14 constexpr functions.
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[: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[equation tangent_numbers]
149
150Their relation with Bernoulli numbers ['B[sub i]] are defined by
151
152if i > 0 and i is even then
153[equation bernoulli_numbers] [br]
154elseif i == 0 then  ['B[sub i]] = 1 [br]
155elseif i == 1 then  ['B[sub i]] = -1/2 [br]
156elseif i < 0 or i is odd then ['B[sub i]] = 0
157
158Note that computed values are stored in a fixed-size table, access is thread safe via atomic operations (i.e. lock
159free programming), this imparts a much lower overhead on access to cached values than might otherwise be expected -
160typically for multiprecision types the cost of thread synchronisation is negligible, while for built in types
161this code is not normally executed anyway.  For very large arguments which cannot be reasonably computed or
162stored in our cache, an asymptotic expansion [@http://www.luschny.de/math/primes/bernincl.html due to Luschny] is used:
163
164[equation bernoulli_numbers2]
165
166[endsect] [/section:bernoulli_numbers Bernoulli Numbers]
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
174From the number, An, of alternating permutations of the set {1, ..., n},
175the numbers A2n+1 with odd indices are called tangent numbers or zag numbers.
176The first few values are 1, 2, 16, 272, 7936, 353792, 22368256, 1903757312 ...
177(sequence [@http://oeis.org/A000182 A000182 in OEIS]).
178They are called tangent numbers because they appear as
179numerators in the Maclaurin series of tan x.
180
181Tangent numbers are used in the computation of Bernoulli numbers,
182but are also made available here.
183
184[h4 Synopsis]
185``
186#include <boost/math/special_functions/detail/bernoulli.hpp>
187``
188
189  template <class T>
190  T tangent_t2n(const int i);  // Single tangent number (default policy).
191
192  template <class T, class Policy>
193  T tangent_t2n(const int i, const Policy &pol); // Single tangent number (user policy).
194
195  // Multiple tangent numbers (default policy).
196  template <class T, class OutputIterator>
197  OutputIterator tangent_t2n(const int start_index,
198                                      const unsigned number_of_tangent_t2n,
199                                      OutputIterator out_it);
200
201  // Multiple tangent numbers (user policy).
202  template <class T, class OutputIterator, class Policy>
203  OutputIterator tangent_t2n(const int start_index,
204                                      const unsigned number_of_tangent_t2n,
205                                      OutputIterator out_it,
206                                      const Policy& pol);
207
208[h4 Examples]
209
210[tangent_example_1]
211
212The output is:
213[tangent_output_1]
214
215The source of this example is at [../../example/bernoulli_example.cpp bernoulli_example.cpp]
216
217[endsect] [/section:tangent_numbers Tangent Numbers]
218
219[/
220  Copyright 2013, 2014 Nikhar Agrawal, Christopher Kormanyos, John Maddock, Paul A. Bristow.
221  Distributed under the Boost Software License, Version 1.0.
222  (See accompanying file LICENSE_1_0.txt or copy at
223  http://www.boost.org/LICENSE_1_0.txt).
224]
225