]> www.ginac.de Git - ginac.git/blobdiff - doc/tutorial/ginac.texi
added documentation for const_iterator
[ginac.git] / doc / tutorial / ginac.texi
index e76c162346591fd4dae08affd517d198090f6fc4..cbcd183975a64ffde62ceb317c683573447917ab 100644 (file)
@@ -23,7 +23,7 @@
 This is a tutorial that documents GiNaC @value{VERSION}, an open
 framework for symbolic computation within the C++ programming language.
 
-Copyright (C) 1999-2003 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2004 Johannes Gutenberg University Mainz, Germany
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -48,11 +48,11 @@ notice identical to this one.
 @subtitle An open framework for symbolic computation within the C++ programming language
 @subtitle @value{UPDATED}
 @author The GiNaC Group:
-@author Christian Bauer, Alexander Frink, Richard Kreckel
+@author Christian Bauer, Alexander Frink, Richard Kreckel, Jens Vollinga
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2003 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2004 Johannes Gutenberg University Mainz, Germany
 @sp 2
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -135,7 +135,7 @@ the near future.
 
 @section License
 The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999-2003 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2004 Johannes Gutenberg
 University Mainz, Germany.
 
 This program is free software; you can redistribute it and/or
@@ -781,7 +781,7 @@ behave in an entirely obvious way at first glance:
 The terms of sums and products (and some other things like the arguments of
 symmetric functions, the indices of symmetric tensors etc.) are re-ordered
 into a canonical form that is deterministic, but not lexicographical or in
-any other way easily guessable (it almost always depends on the number and
+any other way easy to guess (it almost always depends on the number and
 order of the symbols you define). However, constructing the same expression
 twice, either implicitly or explicitly, will always result in the same
 canonical form.
@@ -839,7 +839,7 @@ int pole_error::degree() const;
 that returns the order of the singularity (or 0 when the pole is
 logarithmic or the order is undefined).
 
-When using GiNaC it is useful to arrange for exceptions to be catched in
+When using GiNaC it is useful to arrange for exceptions to be caught in
 the main program even if you don't want to do any special error handling.
 Otherwise whenever an error occurs in GiNaC, it will be delegated to the
 default exception handler of your C++ compiler's run-time system which
@@ -977,6 +977,17 @@ function that declares a symbol with a name already existent in a symbol
 in the calling function.  Again, comparing them (using @code{operator==}
 for instance) will always reveal their difference.  Watch out, please.
 
+@cindex @code{realsymbol()}
+Symbols are expected to stand in for complex values by default, i.e. they live
+in the complex domain.  As a consequence, operations like complex conjugation,
+for example (see @ref{Complex Conjugation}), do @emph{not} evaluate if applied
+to such symbols. Likewise @code{log(exp(x))} does not evaluate to @code{x},
+because of the unknown imaginary part of @code{x}.
+On the other hand, if you are sure that your symbols will hold only real values, you
+would like to have such functions evaluated. Therefore GiNaC allows you to specify
+the domain of the symbol. Instead of @code{symbol x("x");} you can write
+@code{realsymbol x("x");} to tell GiNaC that @code{x} stands in for real values.
+
 @cindex @code{subs()}
 Although symbols can be assigned expressions for internal reasons, you
 should not do it (and we are not going to tell you how it is done).  If
@@ -2817,7 +2828,7 @@ You can use this to compare two expressions or for further simplifications:
 
     e = canonicalize_clifford(e);
     cout << e << endl;
-     // -> 2*eta~mu~nu
+     // -> 2*ONE*eta~mu~nu
 @}
 @end example
 
@@ -2988,6 +2999,9 @@ avoided.
 * Series Expansion::                Taylor and Laurent expansion.
 * Symmetrization::
 * Built-in Functions::              List of predefined mathematical functions.
+* Multiple polylogarithms::
+* Complex Conjugation::
+* Built-in Functions::              List of predefined mathematical functions.
 * Solving Linear Systems of Equations::
 * Input/Output::                    Input and output of expressions.
 @end menu
@@ -3140,23 +3154,62 @@ for an explanation of these.
 @cindex container
 @cindex @code{relational} (class)
 
-GiNaC provides the two methods
+Many GiNaC classes, like @code{add}, @code{mul}, @code{lst}, and
+@code{function}, act as containers for subexpressions. For example, the
+subexpressions of a sum (an @code{add} object) are the individual terms,
+and the subexpressions of a @code{function} are the function's arguments.
+
+GiNaC provides two ways of accessing subexpressions. The first way is to use
+the two methods
 
 @example
 size_t ex::nops();
 ex ex::op(size_t i);
 @end example
 
-for accessing the subexpressions in the container-like GiNaC classes like
-@code{add}, @code{mul}, @code{lst}, and @code{function}. @code{nops()}
-determines the number of subexpressions (@samp{operands}) contained, while
-@code{op()} returns the @code{i}-th (0..@code{nops()-1}) subexpression.
-In the case of a @code{power} object, @code{op(0)} will return the basis
-and @code{op(1)} the exponent. For @code{indexed} objects, @code{op(0)}
-is the base expression and @code{op(i)}, @math{i>0} are the indices.
+@code{nops()} determines the number of subexpressions (operands) contained
+in the expression, while @code{op(i)} returns the @code{i}-th
+(0..@code{nops()-1}) subexpression. In the case of a @code{power} object,
+@code{op(0)} will return the basis and @code{op(1)} the exponent. For
+@code{indexed} objects, @code{op(0)} is the base expression and @code{op(i)},
+@math{i>0} are the indices.
+
+The second way to access subexpressions is via the STL-style random-access
+iterator class @code{const_iterator} and the methods
+
+@example
+const_iterator ex::begin();
+const_iterator ex::end();
+@end example
+
+@code{begin()} returns an iterator referring to the first subexpression;
+@code{end()} returns an iterator which is one-past the last subexpression.
+If the expression has no subexpressions, then @code{begin() == end()}. These
+iterators can also be used in conjunction with non-modifying STL algorithms.
+
+Here is an example that (non-recursively) prints all the subexpressions of a
+given expression in three different ways:
+
+@example
+@{
+    ex e = ...
+
+    // with nops()/op()
+    for (size_t i = 0; i != e.nops(); ++i)
+        cout << e.op(i) << endl;
+
+    // with iterators
+    for (const_iterator i = e.begin(); i != e.end(); ++i)
+        cout << *i << endl;
 
-The left-hand and right-hand side expressions of objects of class
-@code{relational} (and only of these) can also be accessed with the methods
+    // with iterators and STL copy()
+    std::copy(e.begin(), e.end(), std::ostream_iterator<ex>(cout, "\n"));
+@}
+@end example
+
+Additionally, the left-hand and right-hand side expressions of objects of
+class @code{relational} (and only of these) can also be accessed with the
+methods
 
 @example
 ex ex::lhs();
@@ -3263,7 +3316,7 @@ after @code{other}.
 
 @node Numerical Evaluation, Substituting Expressions, Information About Expressions, Methods and Functions
 @c    node-name, next, previous, up
-@section Numercial Evaluation
+@section Numerical Evaluation
 @cindex @code{evalf()}
 
 GiNaC keeps algebraic expressions, numbers and constants in their exact form.
@@ -4112,7 +4165,7 @@ ex ex::expand(unsigned options = 0);
 
 may be called.  In our example above, this corresponds to @math{4*x*y +
 x*z + 20*y^2 + 21*y*z + 4*z^2}.  Again, since the canonical form in
-GiNaC is not easily guessable you should be prepared to see different
+GiNaC is not easy to guess you should be prepared to see different
 orderings of terms in such sums!
 
 Another useful representation of multivariate polynomials is as a
@@ -4182,8 +4235,9 @@ int ex::ldegree(const ex & s);
 @end example
 
 which also work reliably on non-expanded input polynomials (they even work
-on rational functions, returning the asymptotic degree). To extract
-a coefficient with a certain power from an expanded polynomial you use
+on rational functions, returning the asymptotic degree). By definition, the
+degree of zero is zero. To extract a coefficient with a certain power from
+an expanded polynomial you use
 
 @example
 ex ex::coeff(const ex & s, int n);
@@ -4480,7 +4534,7 @@ method. It can also already contain a list of replacements from an earlier
 application of @code{.to_polynomial()} or @code{.to_rational()}, so it's
 possible to use it on multiple expressions and get consistent results.
 
-The difference betwerrn @code{.to_polynomial()} and @code{.to_rational()}
+The difference between @code{.to_polynomial()} and @code{.to_rational()}
 is probably best illustrated with an example:
 
 @example
@@ -4743,10 +4797,11 @@ almost any kind of object (anything that is @code{subs()}able):
 @}
 @end example
 
-
-@node Built-in Functions, Solving Linear Systems of Equations, Symmetrization, Methods and Functions
+@node Built-in Functions, Multiple polylogarithms, Symmetrization, Methods and Functions
 @c    node-name, next, previous, up
 @section Predefined mathematical functions
+@c
+@subsection Overview
 
 GiNaC contains the following predefined mathematical functions:
 
@@ -4758,6 +4813,9 @@ GiNaC contains the following predefined mathematical functions:
 @cindex @code{abs()}
 @item @code{csgn(x)}
 @tab complex sign
+@cindex @code{conjugate()}
+@item @code{conjugate(x)}
+@tab complex conjugation
 @cindex @code{csgn()}
 @item @code{sqrt(x)}
 @tab square root (not a GiNaC function, rather an alias for @code{pow(x, numeric(1, 2))})
@@ -4807,22 +4865,34 @@ GiNaC contains the following predefined mathematical functions:
 @tab natural logarithm
 @cindex @code{log()}
 @item @code{Li2(x)}
-@tab Dilogarithm
+@tab dilogarithm
 @cindex @code{Li2()}
-@item @code{zeta(x)}
-@tab Riemann's zeta function
+@item @code{Li(m, x)}
+@tab classical polylogarithm as well as multiple polylogarithm
+@cindex @code{Li()}
+@item @code{S(n, p, x)}
+@tab Nielsen's generalized polylogarithm
+@cindex @code{S()}
+@item @code{H(m, x)}
+@tab harmonic polylogarithm
+@cindex @code{H()}
+@item @code{zeta(m)}
+@tab Riemann's zeta function as well as multiple zeta value
+@cindex @code{zeta()}
+@item @code{zeta(m, s)}
+@tab alternating Euler sum
 @cindex @code{zeta()}
-@item @code{zeta(n, x)}
+@item @code{zetaderiv(n, x)}
 @tab derivatives of Riemann's zeta function
 @item @code{tgamma(x)}
-@tab Gamma function
+@tab gamma function
 @cindex @code{tgamma()}
-@cindex Gamma function
+@cindex gamma function
 @item @code{lgamma(x)}
-@tab logarithm of Gamma function
+@tab logarithm of gamma function
 @cindex @code{lgamma()}
 @item @code{beta(x, y)}
-@tab Beta function (@code{tgamma(x)*tgamma(y)/tgamma(x+y)})
+@tab beta function (@code{tgamma(x)*tgamma(y)/tgamma(x+y)})
 @cindex @code{beta()}
 @item @code{psi(x)}
 @tab psi (digamma) function
@@ -4838,21 +4908,6 @@ GiNaC contains the following predefined mathematical functions:
 @item @code{Order(x)}
 @tab order term function in truncated power series
 @cindex @code{Order()}
-@item @code{Li(n, x)}
-@tab polylogarithm
-@cindex @code{Li()}
-@item @code{S(n, p, x)}
-@tab Nielsen's generalized polylogarithm
-@cindex @code{S()}
-@item @code{H(m_lst, x)}
-@tab harmonic polylogarithm
-@cindex @code{H()}
-@item @code{Li(m_lst, x_lst)}
-@tab multiple polylogarithm
-@cindex @code{Li()}
-@item @code{mZeta(m_lst)}
-@tab multiple zeta value
-@cindex @code{mZeta()}
 @end multitable
 @end cartouche
 
@@ -4872,8 +4927,189 @@ serious CAS.  It is to be expected that future revisions of the C++
 standard incorporate these functions in the complex domain in a manner
 compatible with C99.
 
+@node Multiple polylogarithms, Complex Conjugation, Built-in Functions, Methods and Functions
+@c    node-name, next, previous, up
+@subsection Multiple polylogarithms
+
+@cindex polylogarithm
+@cindex Nielsen's generalized polylogarithm
+@cindex harmonic polylogarithm
+@cindex multiple zeta value
+@cindex alternating Euler sum
+@cindex multiple polylogarithm
+
+The multiple polylogarithm is the most generic member of a family of functions,
+to which others like the harmonic polylogarithm, Nielsen's generalized
+polylogarithm and the multiple zeta value belong.
+Everyone of these functions can also be written as a multiple polylogarithm with specific
+parameters. This whole family of functions is therefore often referred to simply as
+multiple polylogarithms, containing @code{Li}, @code{H}, @code{S} and @code{zeta}.
+
+To facilitate the discussion of these functions we distinguish between indices and
+arguments as parameters. In the table above indices are printed as @code{m}, @code{s},
+@code{n} or @code{p}, whereas arguments are printed as @code{x}.
+
+To define a @code{Li}, @code{H} or @code{zeta} with a depth greater than one, you have to
+pass a GiNaC @code{lst} for the indices @code{m} and @code{s}, and in the case of @code{Li}
+for the argument @code{x} as well.
+Note that @code{Li} and @code{zeta} are polymorphic in this respect. They can stand in for
+the classical polylogarithm and Riemann's zeta function (if depth is one), as well as for
+the multiple polylogarithm and the multiple zeta value, respectively. Note also, that
+GiNaC doesn't check whether the @code{lst}s for two parameters do have the same length.
+It is up to the user to ensure this, otherwise evaluating will result in undefined behavior.
+
+The functions print in LaTeX format as
+@tex
+${\rm Li\;\!}_{m_1,m_2,\ldots,m_k}(x_1,x_2,\ldots,x_k)$, 
+@end tex
+@tex
+${\rm S}_{n,p}(x)$, 
+@end tex
+@tex
+${\rm H\;\!}_{m_1,m_2,\ldots,m_k}(x)$ and 
+@end tex
+@tex
+$\zeta(m_1,m_2,\ldots,m_k)$.
+@end tex
+If @code{zeta} is an alternating zeta sum, i.e. @code{zeta(m,s)}, the indices with negative sign
+are printed with a line above, e.g.
+@tex
+$\zeta(5,\overline{2})$.
+@end tex
+The order of indices and arguments in the GiNaC @code{lst}s and in the output is the same.
+
+Definitions and analytical as well as numerical properties of multiple polylogarithms
+are too numerous to be covered here. Instead, the user is referred to the publications listed at the
+end of this section. The implementation in GiNaC adheres to the definitions and conventions therein,
+except for a few differences which will be explicitly stated in the following.
+
+One difference is about the order of the indices and arguments. For GiNaC we adopt the convention
+that the indices and arguments are understood to be in the same order as in which they appear in
+the series representation. This means
+@tex
+${\rm Li\;\!}_{m_1,m_2,m_3}(x,1,1) = {\rm H\;\!}_{m_1,m_2,m_3}(x)$ and 
+@end tex
+@tex
+${\rm Li\;\!}_{2,1}(1,1) = \zeta(2,1) = \zeta(3)$, but
+@end tex
+@tex
+$\zeta(1,2)$ evaluates to infinity.
+@end tex
+So in comparison to the referenced publications the order of indices and arguments for @code{Li}
+is reversed.
+
+The functions only evaluate if the indices are integers greater than zero, except for the indices
+@code{s} in @code{zeta} and @code{m} in @code{H}. Since @code{s} will be interpreted as the sequence
+of signs for the corresponding indices @code{m}, it must contain 1 or -1, e.g.
+@code{zeta(lst(3,4), lst(-1,1))} means
+@tex
+$\zeta(\overline{3},4)$.
+@end tex
+The definition of @code{H} allows indices to be 0, 1 or -1 (in expanded notation) or equally to
+be any integer (in compact notation). With GiNaC expanded and compact notation can be mixed,
+e.g. @code{lst(0,0,-1,0,1,0,0)}, @code{lst(0,0,-1,2,0,0)} and @code{lst(-3,2,0,0)} are equivalent as
+indices. The anonymous evaluator @code{eval()} tries to reduce the functions, if possible, to
+the least-generic multiple polylogarithm. If all arguments are unit, it returns @code{zeta}.
+Arguments equal to zero get considered, too. Riemann's zeta function @code{zeta} (with depth one)
+evaluates also for negative integers and positive even integers. For example:
+
+@example
+> Li(@{3,1@},@{x,1@});
+S(2,2,x)
+> H(@{-3,2@},1);
+-zeta(@{3,2@},@{-1,-1@})
+> S(3,1,1);
+1/90*Pi^4
+@end example
+
+It is easy to tell for a given function into which other function it can be rewritten, may
+it be a less-generic or a more-generic one, except for harmonic polylogarithms @code{H}
+with negative indices or trailing zeros (the example above gives a hint). Signs can
+quickly be messed up, for example. Therefore GiNaC offers a C++ function
+@code{convert_H_to_Li()} to deal with the upgrade of a @code{H} to a multiple polylogarithm
+@code{Li} (@code{eval()} already cares for the possible downgrade):
+
+@example
+> convert_H_to_Li(@{0,-2,-1,3@},x);
+Li(@{3,1,3@},@{-x,1,-1@})
+> convert_H_to_Li(@{2,-1,0@},x);
+-Li(@{2,1@},@{x,-1@})*log(x)+2*Li(@{3,1@},@{x,-1@})+Li(@{2,2@},@{x,-1@})
+@end example
+
+Every function apart from the multiple polylogarithm @code{Li} can be numerically evaluated for
+arbitrary real or complex arguments. @code{Li} only evaluates if for all arguments
+@tex
+$x_i$ the condition
+@end tex
+@tex
+$x_1x_2\cdots x_i < 1$ holds.
+@end tex
+
+@example
+> Digits=100;
+100
+> evalf(zeta(@{3,1,3,1@}));
+0.005229569563530960100930652283899231589890420784634635522547448972148869544...
+@end example
+
+Note that the convention for arguments on the branch cut in GiNaC as stated above is
+different from the one Remiddi and Vermaseren have chosen for the harmonic polylogarithm.
+
+If a function evaluates to infinity, no exceptions are raised, but the function is returned
+unevaluated, e.g.
+@tex
+$\zeta(1)$.
+@end tex
+In long expressions this helps a lot with debugging, because you can easily spot
+the divergencies. But on the other hand, you have to make sure for yourself, that no illegal
+cancellations of divergencies happen.
+
+Useful publications:
 
-@node Solving Linear Systems of Equations, Input/Output, Built-in Functions, Methods and Functions
+@cite{Nested Sums, Expansion of Transcendental Functions and Multi-Scale Multi-Loop Integrals}, 
+S.Moch, P.Uwer, S.Weinzierl, hep-ph/0110083
+
+@cite{Harmonic Polylogarithms}, 
+E.Remiddi, J.A.M.Vermaseren, Int.J.Mod.Phys. A15 (2000), pp. 725-754
+
+@cite{Special Values of Multiple Polylogarithms}, 
+J.Borwein, D.Bradley, D.Broadhurst, P.Lisonek, Trans.Amer.Math.Soc. 353/3 (2001), pp. 907-941
+
+@node Complex Conjugation, Solving Linear Systems of Equations, Multiple polylogarithms, Methods and Functions
+@c    node-name, next, previous, up
+@section Complex Conjugation
+@c
+@cindex @code{conjugate()}
+
+The method
+
+@example
+ex ex::conjugate();
+@end example
+
+returns the complex conjugate of the expression. For all built-in functions and objects the
+conjugation gives the expected results:
+
+@example
+@{
+    varidx a(symbol("a"), 4), b(symbol("b"), 4);
+    symbol x("x");
+    realsymbol y("y");
+                                           
+    cout << (3*I*x*y + sin(2*Pi*I*y)).conjugate() << endl;
+     // -> -3*I*conjugate(x)*y+sin(-2*I*Pi*y)
+    cout << (dirac_gamma(a)*dirac_gamma(b)*dirac_gamma5()).conjugate() << endl;
+     // -> -gamma5*gamma~b*gamma~a
+@}
+@end example
+
+For symbols in the complex domain the conjugation can not be evaluated and the GiNaC function
+@code{conjugate} is returned. GiNaC functions conjugate by applying the conjugation to their
+arguments. This is the default strategy. If you want to define your own functions and want to
+change this behavior, you have to supply a specialized conjugation method for your function
+(see @ref{Symbolic functions} and the GiNaC source-code for @code{abs} as an example).
+
+@node Solving Linear Systems of Equations, Input/Output, Complex Conjugation, Methods and Functions
 @c    node-name, next, previous, up
 @section Solving Linear Systems of Equations
 @cindex @code{lsolve()}
@@ -5090,7 +5326,7 @@ static void my_print(const ex & e)
     if (is_a<function>(e))
         cout << ex_to<function>(e).get_name();
     else
-        cout << e.bp->class_name();
+        cout << ex_to<basic>(e).class_name();
     cout << "(";
     size_t n = e.nops();
     if (n)
@@ -5438,12 +5674,7 @@ that is not further evaluated:
 @example
 DECLARE_FUNCTION_2P(myfcn)
 
-static ex myfcn_eval(const ex & x, const ex & y)
-@{
-    return myfcn(x, y).hold();
-@}
-
-REGISTER_FUNCTION(myfcn, eval_func(myfcn_eval))
+REGISTER_FUNCTION(myfcn, dummy())
 @end example
 
 Any code that has seen the @code{DECLARE_FUNCTION} line can use @code{myfcn()}
@@ -5453,33 +5684,20 @@ in algebraic expressions:
 @{
     ...
     symbol x("x");
-    ex e = 2*myfcn(42, 3*x+1) - x;
-     // this calls myfcn_eval(42, 3*x+1), and inserts its return value into
-     // the actual expression
+    ex e = 2*myfcn(42, 1+3*x) - x;
     cout << e << endl;
      // prints '2*myfcn(42,1+3*x)-x'
     ...
 @}
 @end example
 
-@cindex @code{hold()}
-@cindex evaluation
-The @code{eval_func()} option specifies the C++ function that implements
-the @code{eval()} method, GiNaC's anonymous evaluator. This function takes
-the same number of arguments as the associated symbolic function (two in this
-case) and returns the (possibly transformed or in some way simplified)
-symbolically evaluated function (@xref{Automatic evaluation}, for a description
-of the automatic evaluation process). If no (further) evaluation is to take
-place, the @code{eval_func()} function must return the original function
-with @code{.hold()}, to avoid a potential infinite recursion. If your
-symbolic functions produce a segmentation fault or stack overflow when
-using them in expressions, you are probably missing a @code{.hold()}
-somewhere.
+The @code{dummy()} option in the @code{REGISTER_FUNCTION} line signifies
+"no options". A function with no options specified merely acts as a kind of
+container for its arguments. It is a pure "dummy" function with no associated
+logic (which is, however, sometimes perfectly sufficient).
 
-There is not much you can do with the @code{myfcn} function. It merely acts
-as a kind of container for its arguments (which is, however, sometimes
-perfectly sufficient). Let's have a look at the implementation of GiNaC's
-cosine function.
+Let's now have a look at the implementation of GiNaC's cosine function for an
+example of how to make an "intelligent" function.
 
 @subsection The cosine function
 
@@ -5493,9 +5711,38 @@ which declares to all programs using GiNaC that there is a function @samp{cos}
 that takes one @code{ex} as an argument. This is all they need to know to use
 this function in expressions.
 
-The implementation of the cosine function is in @file{inifcns_trans.cpp}. The
-@code{eval_func()} function looks something like this (actually, it doesn't
-look like this at all, but it should give you an idea what is going on):
+The implementation of the cosine function is in @file{inifcns_trans.cpp}. Here
+is its @code{REGISTER_FUNCTION} line:
+
+@example
+REGISTER_FUNCTION(cos, eval_func(cos_eval).
+                       evalf_func(cos_evalf).
+                       derivative_func(cos_deriv).
+                       latex_name("\\cos"));
+@end example
+
+There are four options defined for the cosine function. One of them
+(@code{latex_name}) gives the function a proper name for LaTeX output; the
+other three indicate the C++ functions in which the "brains" of the cosine
+function are defined.
+
+@cindex @code{hold()}
+@cindex evaluation
+The @code{eval_func()} option specifies the C++ function that implements
+the @code{eval()} method, GiNaC's anonymous evaluator. This function takes
+the same number of arguments as the associated symbolic function (one in this
+case) and returns the (possibly transformed or in some way simplified)
+symbolically evaluated function (@xref{Automatic evaluation}, for a description
+of the automatic evaluation process). If no (further) evaluation is to take
+place, the @code{eval_func()} function must return the original function
+with @code{.hold()}, to avoid a potential infinite recursion. If your
+symbolic functions produce a segmentation fault or stack overflow when
+using them in expressions, you are probably missing a @code{.hold()}
+somewhere.
+
+The @code{eval_func()} function for the cosine looks something like this
+(actually, it doesn't look like this at all, but it should give you an idea
+what is going on):
 
 @example
 static ex cos_eval(const ex & x)
@@ -5519,6 +5766,20 @@ static ex cos_eval(const ex & x)
 @}
 @end example
 
+This function is called every time the cosine is used in a symbolic expression:
+
+@example
+@{
+    ...
+    e = cos(Pi);
+     // this calls cos_eval(Pi), and inserts its return value into
+     // the actual expression
+    cout << e << endl;
+     // prints '-1'
+    ...
+@}
+@end example
+
 In this way, @code{cos(4*Pi)} automatically becomes @math{1},
 @code{cos(asin(a+b))} becomes @code{sqrt(1-(a+b)^2)}, etc. If no reasonable
 symbolic transformation can be done, the unmodified function is returned
@@ -5585,32 +5846,20 @@ static ex tan_series(const ex & x, const relational & rel,
 The @code{series()} implementation of a function @emph{must} return a
 @code{pseries} object, otherwise your code will crash.
 
-Now that all the ingredients have been set up, the @code{REGISTER_FUNCTION}
-macro is used to tell the system how the @code{cos()} function behaves:
-
-@example
-REGISTER_FUNCTION(cos, eval_func(cos_eval).
-                       evalf_func(cos_evalf).
-                       derivative_func(cos_deriv).
-                       latex_name("\\cos"));
-@end example
-
-This registers the @code{cos_eval()}, @code{cos_evalf()} and
-@code{cos_deriv()} C++ functions with the @code{cos()} function, and also
-gives it a proper LaTeX name.
-
 @subsection Function options
 
 GiNaC functions understand several more options which are always
 specified as @code{.option(params)}. None of them are required, but you
-need to specify at least one option to @code{REGISTER_FUNCTION()} (usually
-the @code{eval()} method).
+need to specify at least one option to @code{REGISTER_FUNCTION()}. There
+is a do-nothing option called @code{dummy()} which you can use to define
+functions without any special options.
 
 @example
 eval_func(<C++ function>)
 evalf_func(<C++ function>)
 derivative_func(<C++ function>)
 series_func(<C++ function>)
+conjugate_func(<C++ function>)
 @end example
 
 These specify the C++ functions that implement symbolic evaluation,
@@ -7369,6 +7618,7 @@ The following shows how to build a simple package using automake
 and the @samp{AM_PATH_GINAC} macro. The program used here is @file{simple.cpp}:
 
 @example
+#include <iostream>
 #include <ginac/ginac.h>
 
 int main()