\chapter[\protect\module{pygsl.sum} --- Series acceleration]{
  \protect\module{pygsl.sum} \\ Series acceleration}
\label{cha:sum-module}

\declaremodule{extension}{pygsl.sum}
\modulesynopsis{Series acceleration.}

This chapter describes the use of the series acceleration tools based
on the Levin $u$-transform.  This method takes a small number of terms
from the start of a series and uses a systematic approximation to
compute an extrapolated value and an estimate of its error. The
$u$-transform works for both convergent and divergent series,
including asymptotic series.

\begin{equation}
  \label{eq:levin}
  \function{levin_sum}\code{(a)} = (A, \epsilon)
  \qquad\text{where}
  \qquad
  A \approx \sum_{n=0}^{\infty} a_{n} \pm \epsilon, 
\end{equation}
$\code{a} = [a_{0}, a_{1}, \ldots, a_{n}]$, and $\epsilon$ is an
estimate of the absolute error.

Note: This function is intended for summing analytic series where each
term is known to high accuracy, and the rounding errors are assumed to
originate from finite precision. They are taken to be relative errors
of order \constant{GSL_DBL_EPSILON} for each term (as defined in the
\GSL{} source code).

\section{Function list}
\begin{funcdesc}{levin_sum}{a, truncate=False, info_dict=None}
  Return ($A, \epsilon$) where $A$ is the approximated sum of the
  series~(\ref{eq:levin}) and $\epsilon$ is its absolute error
  estimate.

  The calculation of the error in the extrapolated value is an
  O$(N^2)$ process, which is expensive in time and memory.  A full
  table of intermediate values and derivatives through to O$(N)$ must
  be computed and stored, but this does give a reliable error
  estimate.

  A faster but less reliable method which estimates the error from the
  convergence of the extrapolated value is employed if \var{truncate}
  is \code{True}.  This attempts to estimate the error from the
  ``truncation error'' in the extrapolation, the difference between
  the final two approximations. Using this method avoids the need to
  compute an intermediate table of derivatives because the error is
  estimated from the behavior of the extrapolated value
  itself. Consequently this algorithm is an O$(N)$ process and only
  requires O$(N)$ terms of storage. If the series converges sufficiently
  fast then this procedure can be acceptable. It is appropriate to use
  this method when there is a need to compute many extrapolations of
  series with similar convergence properties at high-speed. For
  example, when numerically integrating a function defined by a
  parameterized series where the parameter varies only slightly. A
  reliable error estimate should be computed first using the full
  algorithm described above in order to verify the consistency of the
  results.

  If a dictionary is passed as \var{info_dict}, then two entries will
  be added: \var{info_dict}\code{['terms_used']} will be the number of
  terms used\footnote{Note that it appears that this is the number of
    terms \emph{beyond} the first term that are used.  I.e.\ there are
    a total of $\var{terms_used}+1$ terms:
    \begin{equation}
      \var{sum_plain} = 
      \sum_{n=0}^{\var{terms_used}}
      a_{n}
    \end{equation}}
  and \var{info_dict}\code{['sum_plain']} will be the sum of these terms without
  acceleration.
\end{funcdesc}

\section{Further Reading}
For details on the underlying implementation of these functions please
consult the \GSL{} reference manual.  The algorithms used by these
functions are described Fessler \textit{et al.} (1983).  The theory of
the $u$-transform was presented Levin in 1973, and a review paper from
2000 by Homeier is available online.

\begin{seealso}
  \seetext{T.~Fessler, W.~F.~Ford, D.~A.~Smith, \textit{hurry: An
      acceleration algorithm for scalar sequences and series}. ACM
    Transactions on Mathematical Software, \textbf{9}(3):346--354,
    (1983), and Algorithm 602 9(3):355--357, 1983.}
  \seetext{D.~Levin, \textit{Development of Non-Linear Transformations
      for Improving Convergence of Sequences,} Intern.~J.~Computer
    Math. \textbf{B3}:371--388, (1973).}
  \seetitle[http://arXiv.org/abs/math/0005209]{Herbert H.~H.~Homeier,
    \textit{Scalar Levin-Type Sequence Transformations.}}{}
\end{seealso}
%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "ref"
%%% End: 
