mirror of
https://github.com/boostorg/math.git
synced 2026-01-24 18:12:09 +00:00
123 lines
4.1 KiB
Plaintext
123 lines
4.1 KiB
Plaintext
[section Series Evaluation]
|
|
|
|
[caution __caution ]
|
|
|
|
[h4 Synopsis]
|
|
|
|
``
|
|
#include <boost/math/tools/series.hpp>
|
|
``
|
|
|
|
namespace boost{ namespace math{ namespace tools{
|
|
|
|
template <class Functor>
|
|
typename Functor::result_type sum_series(Functor& func, int bits);
|
|
|
|
template <class Functor>
|
|
typename Functor::result_type sum_series(Functor& func, int bits, boost::uintmax_t& max_terms);
|
|
|
|
template <class Functor, class U>
|
|
typename Functor::result_type sum_series(Functor& func, int bits, U init_value);
|
|
|
|
template <class Functor, class U>
|
|
typename Functor::result_type sum_series(Functor& func, int bits, boost::uintmax_t& max_terms, U init_value);
|
|
|
|
template <class Functor>
|
|
typename Functor::result_type kahan_sum_series(Functor& func, int bits);
|
|
|
|
template <class Functor>
|
|
typename Functor::result_type kahan_sum_series(Functor& func, int bits, boost::uintmax_t& max_terms);
|
|
|
|
}}} // namespaces
|
|
|
|
[h4 Description]
|
|
|
|
These algorithms are intended for the summation of infinite series.
|
|
|
|
Each of the algorithms takes a nullary-function object as the first argument:
|
|
the function object will be repeatedly invoked to pull successive terms from
|
|
the series being summed.
|
|
|
|
The second argument is the number of binary bits of
|
|
precision required, summation will stop when the next term is too small to
|
|
have any effect on the first /bits/ bits of the result.
|
|
|
|
The optional third argument /max_terms/ sets an upper limit on the number
|
|
of terms of the series to evaluate, in addition, on exit the function will
|
|
set /max_terms/ to the actual number of terms of the series that were
|
|
evaluated: this is particularly useful for profiling the convergence
|
|
properties of a new series.
|
|
|
|
The final optional argument /init_value/ is the initial value of the sum
|
|
to which the terms of the series should be added. This is useful in two situations:
|
|
|
|
* Where the first value of the series has a different formula to successive
|
|
terms. In this case the first value in the series can be passed as the
|
|
last argument and the logic of the function object can then be simplified
|
|
to return subsequent terms.
|
|
* Where the series is being added (or subtracted) from some other value:
|
|
termination of the series will likely occur much more rapidly if that other
|
|
value is passed as the last argument. For example there are several functions
|
|
that can be expressed as /1 - S(z)/ where S(z) is an infinite series. In this
|
|
case pass -1 as the last argument and then negate the result of the summation
|
|
to get the result of /1 - S(z)/.
|
|
|
|
The two /kahan_sum_series/ variants of these algorithms maintain a carry term
|
|
that corrects for roundoff error during summation.
|
|
They are inspired by the /Kahan Summation Formula/ that appears in
|
|
[@http://docs.sun.com/source/806-3568/ncg_goldberg.html What Every Computer Scientist Should Know About Floating-Point Arithmetic].
|
|
However, it should be pointed out that there are very few series that require
|
|
summation in this way.
|
|
|
|
[h4 Example]
|
|
|
|
Let's suppose we want to implement /log(1+x)/ via it's infinite series,
|
|
|
|
[$../equations/log1pseries.png]
|
|
|
|
We begin by writing a small function object to return successive terms
|
|
of the series:
|
|
|
|
template <class T>
|
|
struct log1p_series
|
|
{
|
|
// we must define a result_type typedef:
|
|
typedef T result_type;
|
|
|
|
log1p_series(T x)
|
|
: k(0), m_mult(-x), m_prod(-1){}
|
|
|
|
T operator()()
|
|
{
|
|
// This is the function operator invoked by the summation
|
|
// algorithm, the first call to this operator should return
|
|
// the first term of the series, the second call the second
|
|
// term and so on.
|
|
m_prod *= m_mult;
|
|
return m_prod / ++k;
|
|
}
|
|
|
|
private:
|
|
int k;
|
|
const T m_mult;
|
|
T m_prod;
|
|
};
|
|
|
|
Implementing log(1+x) is now fairly trivial:
|
|
|
|
template <class T>
|
|
T log1p(T x)
|
|
{
|
|
// We really should add some error checking on x here!
|
|
assert(std::fabs(x) < 1);
|
|
|
|
// construct the series functor:
|
|
log1p_series<T> s(x);
|
|
// and add it up, with enough digits for full machine precision
|
|
// plus a couple more for luck.... !
|
|
return tools::sum_series(s, tools::digits(x) + 2);
|
|
}
|
|
|
|
[endsect]
|
|
|