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 42These algorithms are intended for the 43[@http://en.wikipedia.org/wiki/Series_%28mathematics%29 summation of infinite series]. 44 45Each of the algorithms takes a nullary-function object as the first argument: 46the function object will be repeatedly invoked to pull successive terms from 47the series being summed. 48 49The second argument is the precision required, 50summation will stop when the next term is less than 51/tolerance/ times the result. The deprecated versions of `sum_series` 52take an integer number of bits here - internally they just convert this to 53a tolerance and forward the call. 54 55The third argument /max_terms/ sets an upper limit on the number 56of terms of the series to evaluate. In addition, on exit the function will 57set /max_terms/ to the actual number of terms of the series that were 58evaluated: this is particularly useful for profiling the convergence 59properties of a new series. 60 61The final optional argument /init_value/ is the initial value of the sum 62to 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 65terms. In this case the first value in the series can be passed as the 66last argument and the logic of the function object can then be simplified 67to return subsequent terms. 68* Where the series is being added (or subtracted) from some other value: 69termination of the series will likely occur much more rapidly if that other 70value is passed as the last argument. For example, there are several functions 71that can be expressed as /1 - S(z)/ where S(z) is an infinite series. In this 72case, pass -1 as the last argument and then negate the result of the summation 73to get the result of /1 - S(z)/. 74 75The two /kahan_sum_series/ variants of these algorithms maintain a carry term 76that corrects for roundoff error during summation. 77They are inspired by the 78[@http://en.wikipedia.org/wiki/Kahan_Summation_Algorithm /Kahan Summation Formula/] 79that appears in 80[@http://docs.sun.com/source/806-3568/ncg_goldberg.html What Every Computer Scientist Should Know About Floating-Point Arithmetic]. 81However, it should be pointed out that there are very few series that require 82summation in this way. 83 84[h4 Examples] 85 86[import ../../example/series.cpp] 87 88These examples are all in [@../../example/series.cpp] 89 90Let's suppose we want to implement /log(1+x)/ via its infinite series, 91 92[equation log1pseries] 93 94We begin by writing a small function object to return successive terms 95of the series: 96 97[series_log1p] 98 99Implementing log(1+x) is now fairly trivial: 100 101[series_log1p_func] 102 103We can almost use the code above for complex numbers as well - unfortunately we need a slightly different 104definition for epsilon, and within the functor, mixed complex and integer arithmetic is sadly not supported 105(as of C++17), so we need to cast out integers to floats: 106 107[series_clog1p_func] 108 109Of course with a few traits classes and a bit of meta-programming we could fold these two implementations into one, but that's beyond the scope of these examples. 110 111[endsect] [/section Series Evaluation] 112 113[/ 114 Copyright 2006 John Maddock and Paul A. Bristow. 115 Distributed under the Boost Software License, Version 1.0. 116 (See accompanying file LICENSE_1_0.txt or copy at 117 http://www.boost.org/LICENSE_1_0.txt). 118] 119