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
@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
@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
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.
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
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
e = canonicalize_clifford(e);
cout << e << endl;
- // -> 2*eta~mu~nu
+ // -> 2*ONE*eta~mu~nu
@}
@end example
* 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
@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();
@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.
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
@}
@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
@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))})
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
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 refered to simply as
+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
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 refered to the publications listed at the
+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
+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
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
@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 Solving Linear Systems of Equations, Input/Output, Built-in Functions, Methods and Functions
+@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()}
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,
git://www.ginac.de / ginac.git / blobdiff