ceph/src/boost/libs/math/doc/internals/series.qbk

   1 [section:series_evaluation Series Evaluation]
   2
   3 [h4 Synopsis]
   4
   5 ``
   6 #include <boost/math/tools/series.hpp>
   7 ``
   8
   9    namespace boost{ namespace math{ namespace tools{
  10
  11    template <class Functor, class U, class V>
  12    inline typename Functor::result_type sum_series(Functor& func, const U& tolerance, boost::uintmax_t& max_terms, const V& init_value);
  13
  14    template <class Functor, class U, class V>
  15    inline typename Functor::result_type sum_series(Functor& func, const U& tolerance, boost::uintmax_t& max_terms);
  16
  17    //
  18    // The following interfaces are now deprecated:
  19    //
  20    template <class Functor>
  21    typename Functor::result_type sum_series(Functor& func, int bits);
  22
  23    template <class Functor>
  24    typename Functor::result_type sum_series(Functor& func, int bits, boost::uintmax_t& max_terms);
  25
  26    template <class Functor, class U>
  27    typename Functor::result_type sum_series(Functor& func, int bits, U init_value);
  28
  29    template <class Functor, class U>
  30    typename Functor::result_type sum_series(Functor& func, int bits, boost::uintmax_t& max_terms, U init_value);
  31
  32    template <class Functor>
  33    typename Functor::result_type kahan_sum_series(Functor& func, int bits);
  34
  35    template <class Functor>
  36    typename Functor::result_type kahan_sum_series(Functor& func, int bits, boost::uintmax_t& max_terms);
  37
  38    }}} // namespaces
  39
  40 [h4 Description]
  41
  42 These algorithms are intended for the
  43 [@http://en.wikipedia.org/wiki/Series_%28mathematics%29 summation of infinite series].
  44
  45 Each of the algorithms takes a nullary-function object as the first argument:
  46 the function object will be repeatedly invoked to pull successive terms from
  47 the series being summed.
  48
  49 The second argument is the precision required,
  50 summation will stop when the next term is less than
  51 /tolerance/ times the result.  The deprecated versions of sum_series
  52 take an integer number of bits here - internally they just convert this to
  53 a tolerance and forward the call.
  54
  55 The third argument /max_terms/ sets an upper limit on the number
  56 of terms of the series to evaluate. In addition, on exit the function will
  57 set /max_terms/ to the actual number of terms of the series that were
  58 evaluated: this is particularly useful for profiling the convergence
  59 properties of a new series.
  60
  61 The final optional argument /init_value/ is the initial value of the sum
  62 to which the terms of the series should be added.  This is useful in two situations:
  63
  64 * Where the first value of the series has a different formula to successive
  65 terms.  In this case the first value in the series can be passed as the
  66 last argument and the logic of the function object can then be simplified
  67 to return subsequent terms.
  68 * Where the series is being added (or subtracted) from some other value:
  69 termination of the series will likely occur much more rapidly if that other
  70 value is passed as the last argument.  For example, there are several functions
  71 that can be expressed as /1 - S(z)/ where S(z) is an infinite series.  In this
  72 case, pass -1 as the last argument and then negate the result of the summation
  73 to get the result of /1 - S(z)/.
  74
  75 The two /kahan_sum_series/ variants of these algorithms maintain a carry term
  76 that corrects for roundoff error during summation.
  77 They are inspired by the
  78 [@http://en.wikipedia.org/wiki/Kahan_Summation_Algorithm /Kahan Summation Formula/]
  79 that appears in
  80 [@http://docs.sun.com/source/806-3568/ncg_goldberg.html What Every Computer Scientist Should Know About Floating-Point Arithmetic].
  81 However, it should be pointed out that there are very few series that require
  82 summation in this way.
  83
  84 [h4 Example]
  85
  86 Let's suppose we want to implement /log(1+x)/ via its infinite series,
  87
  88 [equation log1pseries]
  89
  90 We begin by writing a small function object to return successive terms
  91 of the series:
  92
  93    template <class T>
  94    struct log1p_series
  95    {
  96       // we must define a result_type typedef:
  97       typedef T result_type;
  98
  99       log1p_series(T x)
 100          : k(0), m_mult(-x), m_prod(-1){}
 101
 102       T operator()()
 103       {
 104          // This is the function operator invoked by the summation
 105          // algorithm, the first call to this operator should return
 106          // the first term of the series, the second call the second
 107          // term and so on.
 108          m_prod *= m_mult;
 109          return m_prod / ++k;
 110       }
 111
 112    private:
 113       int k;
 114       const T m_mult;
 115       T m_prod;
 116    };
 117
 118 Implementing log(1+x) is now fairly trivial:
 119
 120    template <class T>
 121    T log1p(T x)
 122    {
 123       // We really should add some error checking on x here!
 124       assert(std::fabs(x) < 1);
 125
 126       // Construct the series functor:
 127       log1p_series<T> s(x);
 128       // Set a limit on how many iterations we permit:
 129       boost::uintmax_t max_iter = 1000;
 130       // Add it up, with enough precision for full machine precision:
 131       return tools::sum_series(s, std::numeric_limits<T>::epsilon(), max_iter);
 132    }
 133
 134 [endsect][/section Series Evaluation]
 135
 136 [/
 137   Copyright 2006 John Maddock and Paul A. Bristow.
 138   Distributed under the Boost Software License, Version 1.0.
 139   (See accompanying file LICENSE_1_0.txt or copy at
 140   http://www.boost.org/LICENSE_1_0.txt).
 141 ]