Permalink
Browse files

Extend sphinx documentation of series module.

In particular add a short description of the gruntz algorithm.
  • Loading branch information...
1 parent b65d248 commit 6a6a54d60fa60406efd2a8b7a272a935b82dfb7f Tom Bachmann committed Apr 28, 2011
Showing with 119 additions and 6 deletions.
  1. +119 −6 doc/src/modules/series.txt
View
@@ -3,19 +3,132 @@ Series Expansions
.. module:: sympy.series
-The series module implements series expansions as a function. This is achieved
+The series module implements series expansions as a function and many related
+functions.
+
+Limits
+------
+
+The main purpose of this module is the computation of limits.
+
+.. autofunction:: sympy.series.limits.limit
+
+As is explained above, the workhorse for limit computations is the
+function gruntz() which implements Gruntz' algorithm for computing limits.
+
+The Gruntz Algorithm
+^^^^^^^^^^^^^^^^^^^^
+
+This section explains the basics of the algorithm used for computing limits.
+Most of the time the limit() function should just work. However it is still
+useful to keep in mind how it is implemented in case something does not work
+as expected.
+
+First we define an ordering on functions. Suppose $f(x)$ and $g(x)$ are two
+real-valued functions such that $\lim_{x \to \infty} f(x) = \infty$ and
+similarly $\lim_{x \to \infty} g(x) = \infty$. We shall say that $f(x)$
+*dominates*
+$g(x)$, written $f(x) \succ g(x)$, if for all $a, b \in \mathbb{R}_{>0}$ we have
+$\lim_{x \to \infty} \frac{f(x)^a}{g(x)^b} = \infty$.
+We also say that $f(x)$ and
+$g(x)$ are *of the same comparability class* if neither $f(x) \succ g(x)$ nor
+$g(x) \succ f(x)$ and shall denote it as $f(x) \asymp g(x)$.
+
+Note that whenever $a, b \in \mathbb{R}_{>0}$ then
+$a f(x)^b \asymp f(x)$, and we shall use this to extend the definition of
+$\succ$ to all functions which tend to $0$ or $\pm \infty$ as $x \to \infty$.
+Thus we declare that $f(x) \asymp 1/f(x)$ and $f(x) \asymp -f(x)$.
+
+It is easy to show the following examples:
+
+* $e^x \succ x^m$
+* $e^{x^2} \succ e^{mx}$
+* $e^{e^x} \succ e^{x^m}$
+* $x^m \asymp x^n$
+* $e^{x + \frac{1}{x}} \asymp e^{x + \log{x}} \asymp e^x$.
+
+From the above definition, it is possible to prove the following property:
+
+ Suppose $\omega$, $g_1, g_2, \dots$ are functions of $x$,
+ $\lim_{x \to \infty} \omega = 0$ and $\omega \succ g_i$ for
+ all $i$. Let $c_1, c_2, \dots \in \mathbb{R}$ with $c_1 < c_2 < \dots$.
+
+ Then $\lim_{x \to \infty} \sum_i g_i \omega^{c_i} = \lim_{x \to \infty} g_1 \omega^{c_1}$.
+
+For $g_1 = g$ and $\omega$ as above we also have the following easy result:
+
+ * $\lim_{x \to \infty} g \omega^c = 0$ for $c > 0$
+ * $\lim_{x \to \infty} g \omega^c = \pm \infty$ for $c < 0$,
+ where the sign is determined by the (eventual) sign of $g$
+ * $\lim_{x \to \infty} g \omega^0 = \lim_{x \to \infty} g$.
+
+
+Using these results yields the following strategy for computing
+$\lim_{x \to \infty} f(x)$:
+
+1. Find the set of *most rapidly varying subexpressions* (MRV set) of $f(x)$.
+ That is, from the set of all subexpressions of $f(x)$, find the elements that
+ are maximal under the relation $\succ$.
+2. Choose a function $\omega$ that is in the same comparability class as
+ the elements in the MRV set, such that $\lim_{x \to \infty} \omega = 0$.
+3. Expand $f(x)$ as a series in $\omega$ in such a way that the antecedents of
+ the above theorem are satisfied.
+4. Apply the theorem and conclude the computation of
+ $\lim_{x \to \infty} f(x)$, possibly by recursively working on $g_1(x)$.
+
+
+Notes
+"""""
+
+This exposition glossed over several details. Many are described in the file
+gruntz.py, and all can be found in Gruntz' very readable thesis. The most
+important points that have not been explained are:
+
+1. Given f(x) and g(x), how do we determine if $f(x) \succ g(x)$,
+ $g(x) \succ f(x)$ or $g(x) \asymp f(x)$?
+2. How do we find the MRV set of an expression?
+3. How do we compute series expansions?
+4. Why does the algorithm terminate?
+
+If you are interested, be sure to take a look at
+`Gruntz Thesis <http://www.cybertester.com/data/gruntz.pdf>`_.
+
+
+More Intuitive Series Expansion
+-------------------------------
+
+This is achieved
by creating a wrapper around Basic.series(). This allows for the use of
series(x*cos(x),x), which is possibly more intuative than (x*cos(x)).series(x).
Examples
---------
+^^^^^^^^
>>> from sympy import Symbol, cos, series
>>> x = Symbol('x')
>>> series(cos(x),x)
1 - x**2/2 + x**4/24 + O(x**6)
+Order Terms
+-----------
+
+This module also implements automatic keeping track of the order of your
+expansion.
+
+Examples
+^^^^^^^^
+ >>> from sympy import Symbol, Order
+ >>> x = Symbol('x')
+ >>> Order(x) + x**2
+ O(x)
+ >>> Order(x) + 1
+ 1 + O(x)
+
+Series Acceleration
+-------------------
+
+TODO
+
+Residues
+--------
-TODO and Bugs
--------------
-The series expansion about a point other than x=0 does not work. This is a bug in Basic.series() (issue 1334). When fixed there, the bug will
-also be automatically fixed here.
+TODO

0 comments on commit 6a6a54d

Please sign in to comment.