This is a tutorial that documents GiNaC @value{VERSION}, an open
framework for symbolic computation within the C++ programming language.
-Copyright (C) 1999-2004 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2005 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
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2004 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2005 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-2004 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2005 Johannes Gutenberg
University Mainz, Germany.
This program is free software; you can redistribute it and/or
* Lists:: Lists of expressions.
* Mathematical functions:: Mathematical functions.
* Relations:: Equality, Inequality and all that.
+* Integrals:: Symbolic integrals.
* Matrices:: Matrices.
* Indexed objects:: Handling indexed quantities.
* Non-commutative objects:: Algebras with non-commutative products.
wrapped inside an @code{ex}.
-@node Relations, Matrices, Mathematical functions, Basic Concepts
+@node Relations, Integrals, Mathematical functions, Basic Concepts
@c node-name, next, previous, up
@section Relations
@cindex @code{relational} (class)
however, that @code{==} here does not perform any simplifications, hence
@code{expand()} must be called explicitly.
+@node Integrals, Matrices, Relations, Basic Concepts
+@c node-name, next, previous, up
+@section Integrals
+@cindex @code{integral} (class)
+
+An object of class @dfn{integral} can be used to hold a symbolic integral.
+If you want to symbolically represent the integral of @code{x*x} from 0 to
+1, you would write this as
+@example
+integral(x, 0, 1, x*x)
+@end example
+The first argument is the integration variable. It should be noted that
+GiNaC is not very good (yet?) at symbolically evaluating integrals. In
+fact, it can only integrate polynomials. An expression containing integrals
+can be evaluated symbolically by calling the
+@example
+.eval_integ()
+@end example
+method on it. Numerical evaluation is available by calling the
+@example
+.evalf()
+@end example
+method on an expression containing the integral. This will only evaluate
+integrals into a number if @code{subs}ing the integration variable by a
+number in the fourth argument of an integral and then @code{evalf}ing the
+result always results in a number. Of course, also the boundaries of the
+integration domain must @code{evalf} into numbers. It should be noted that
+trying to @code{evalf} a function with discontinuities in the integration
+domain is not recommended. The accuracy of the numeric evaluation of
+integrals is determined by the static member variable
+@example
+ex integral::relative_integration_error
+@end example
+of the class @code{integral}. The default value of this is 10^-8.
+The integration works by halving the interval of integration, until numeric
+stability of the answer indicates that the requested accuracy has been
+reached. The maximum depth of the halving can be set via the static member
+variable
+@example
+int integral::max_integration_level
+@end example
+The default value is 15. If this depth is exceeded, @code{evalf} will simply
+return the integral unevaluated. The function that performs the numerical
+evaluation, is also available as
+@example
+ex adaptivesimpson(const ex & x, const ex & a, const ex & b, const ex & f,
+const ex & error)
+@end example
+This function will throw an exception if the maximum depth is exceeded. The
+last parameter of the function is optional and defaults to the
+@code{relative_integration_error}. To make sure that we do not do too
+much work if an expression contains the same integral multiple times,
+a lookup table is used.
+
+If you know that an expression holds an integral, you can get the
+integration variable, the left boundary, right boundary and integrant by
+respectively calling @code{.op(0)}, @code{.op(1)}, @code{.op(2)}, and
+@code{.op(3)}. Differentiating integrals with respect to variables works
+as expected. Note that it makes no sense to differentiate an integral
+with respect to the integration variable.
-@node Matrices, Indexed objects, Relations, Basic Concepts
+@node Matrices, Indexed objects, Integrals, Basic Concepts
@c node-name, next, previous, up
@section Matrices
@cindex @code{matrix} (class)
@end itemize
-@strong{Note:} when printing expressions, covariant indices and indices
+@strong{Please notice:} when printing expressions, covariant indices and indices
without variance are denoted @samp{.i} while contravariant indices are
denoted @samp{~i}. Dotted indices have a @samp{*} in front of the index
value. In the following, we are going to use that notation in the text so
@cindex @code{clifford} (class)
@subsection Clifford algebra
+
+Clifford algebras are supported in two flavours: Dirac gamma
+matrices (more physical) and generic Clifford algebras (more
+mathematical).
+
@cindex @code{dirac_gamma()}
-Clifford algebra elements (also called Dirac gamma matrices, although GiNaC
-doesn't treat them as matrices) are designated as @samp{gamma~mu} and satisfy
-@samp{gamma~mu*gamma~nu + gamma~nu*gamma~mu = 2*eta~mu~nu} where @samp{eta~mu~nu}
-is the Minkowski metric tensor. Dirac gammas are constructed by the function
+@subsubsection Dirac gamma matrices
+Dirac gamma matrices (note that GiNaC doesn't treat them
+as matrices) are designated as @samp{gamma~mu} and satisfy
+@samp{gamma~mu*gamma~nu + gamma~nu*gamma~mu = 2*eta~mu~nu} where
+@samp{eta~mu~nu} is the Minkowski metric tensor. Dirac gammas are
+constructed by the function
@example
ex dirac_gamma(const ex & mu, unsigned char rl = 0);
ex dirac_ONE(unsigned char rl = 0);
@end example
-@strong{Note:} You must always use @code{dirac_ONE()} when referring to
+@strong{Please notice:} You must always use @code{dirac_ONE()} when referring to
multiples of the unity element, even though it's customary to omit it.
E.g. instead of @code{dirac_gamma(mu)*(dirac_slash(q,4)+m)} you have to
write @code{dirac_gamma(mu)*(dirac_slash(q,4)+m*dirac_ONE())}. Otherwise,
@}
@end example
+@cindex @code{clifford_unit()}
+@subsubsection A generic Clifford algebra
+
+A generic Clifford algebra, i.e. a
+@tex
+$2^n$
+@end tex
+dimensional algebra with
+generators @samp{e~k} satisfying the identities
+@samp{e~i e~j + e~j e~i = B(i, j)} for some matrix (@code{metric})
+@math{B(i, j)}, which may be non-symmetric. Such generators are created
+by the function
+
+@example
+ ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0);
+@end example
+
+where @code{mu} should be a @code{varidx} class object indexing the
+generators, @code{metr} defines the metric @math{B(i, j)} and can be
+represented by a square @code{matrix}, @code{tensormetric} or @code{indexed} class
+object, optional parameter @code{rl} allows to distinguish different
+Clifford algebras (which will commute with each other). Note that the call
+@code{clifford_unit(mu, minkmetric())} creates something very close to
+@code{dirac_gamma(mu)}. The method @code{clifford::get_metric()} returns a
+metric defining this Clifford number.
+
+If the matrix @math{B(i, j)} is in fact symmetric you may prefer to create
+the Clifford algebra units with a call like that
+
+@example
+ ex e = clifford_unit(mu, indexed(B, sy_symm(), i, j));
+@end example
+
+since this may yield some further automatic simplifications.
+
+Individual generators of a Clifford algebra can be accessed in several
+ways. For example
+
+@example
+@{
+ ...
+ varidx nu(symbol("nu"), 3);
+ matrix M(3, 3) = 1, 0, 0,
+ 0,-1, 0,
+ 0, 0, 0;
+ ex e = clifford_unit(nu, M);
+ ex e0 = e.subs(nu == 0);
+ ex e1 = e.subs(nu == 1);
+ ex e2 = e.subs(nu == 2);
+ ...
+@}
+@end example
+
+will produce three generators of a Clifford algebra with properties
+@code{pow(e0, 2) = 1}, @code{pow(e1, 2) = -1} and @code{pow(e2, 2) = 0}.
+
+@cindex @code{lst_to_clifford()}
+A similar effect can be achieved from the function
+
+@example
+ ex lst_to_clifford(const ex & v, const ex & mu, const ex & metr,
+ unsigned char rl = 0);
+@end example
+
+which converts a list or vector @samp{v = (v~0, v~1, ..., v~n)} into
+the Clifford number @samp{v~0 e.0 + v~1 e.1 + ... + v~n e.n} with @samp{e.k}
+being created by @code{clifford_unit(mu, metr, rl)}. The previous code
+may be rewritten with the help of @code{lst_to_clifford()} as follows
+
+@example
+@{
+ ...
+ varidx nu(symbol("nu"), 3);
+ matrix M(3, 3) = 1, 0, 0,
+ 0,-1, 0,
+ 0, 0, 0;
+ ex e0 = lst_to_clifford(lst(1, 0, 0), nu, M);
+ ex e1 = lst_to_clifford(lst(0, 1, 0), nu, M);
+ ex e2 = lst_to_clifford(lst(0, 0, 1), nu, M);
+ ...
+@}
+@end example
+
+@cindex @code{clifford_to_lst()}
+There is the inverse function
+
+@example
+ lst clifford_to_lst(const ex & e, const ex & c, bool algebraic = true);
+@end example
+
+which takes an expression @code{e} and tries to find a list
+@samp{v = (v~0, v~1, ..., v~n)} such that @samp{e = v~0 c.0 + v~1 c.1 + ...
++ v~n c.n} with respect to the given Clifford units @code{c} and none of
+@samp{v~k} contains the Clifford units @code{c} (of course, this
+may be impossible). This function can use an @code{algebraic} method
+(default) or a symbolic one. With the @code{algebraic} method @samp{v~k} are calculated as
+@samp{(e c.k + c.k e)/pow(c.k, 2)}. If @samp{pow(c.k, 2) = 0} for some @samp{k}
+then the method will be automatically changed to symbolic. The same effect
+is obtained by the assignment (@code{algebraic = false}) in the procedure call.
+
+@cindex @code{clifford_prime()}
+@cindex @code{clifford_star()}
+@cindex @code{clifford_bar()}
+There are several functions for (anti-)automorphisms of Clifford algebras:
+
+@example
+ ex clifford_prime(const ex & e)
+ inline ex clifford_star(const ex & e) @{ return e.conjugate(); @}
+ inline ex clifford_bar(const ex & e) @{ return clifford_prime(e.conjugate()); @}
+@end example
+
+The automorphism of a Clifford algebra @code{clifford_prime()} simply
+changes signs of all Clifford units in the expression. The reversion
+of a Clifford algebra @code{clifford_star()} coincides with the
+@code{conjugate()} method and effectively reverses the order of Clifford
+units in any product. Finally the main anti-automorphism
+of a Clifford algebra @code{clifford_bar()} is the composition of the
+previous two, i.e. it makes the reversion and changes signs of all Clifford units
+in a product. These functions correspond to the notations
+@math{e'},
+@tex
+$e^*$
+@end tex
+and
+@tex
+$\overline{e}$
+@end tex
+used in Clifford algebra textbooks.
+
+@cindex @code{clifford_norm()}
+The function
+
+@example
+ ex clifford_norm(const ex & e);
+@end example
+
+@cindex @code{clifford_inverse()}
+calculates the norm of a Clifford number from the expression
+@tex
+$||e||^2 = e\overline{e}$
+@end tex
+. The inverse of a Clifford expression is returned
+by the function
+
+@example
+ ex clifford_inverse(const ex & e);
+@end example
+
+which calculates it as
+@tex
+$e^{-1} = e/||e||^2$
+@end tex
+. If
+@tex
+$||e|| = 0$
+@end tex
+then an exception is raised.
+
+@cindex @code{remove_dirac_ONE()}
+If a Clifford number happens to be a factor of
+@code{dirac_ONE()} then we can convert it to a ``real'' (non-Clifford)
+expression by the function
+
+@example
+ ex remove_dirac_ONE(const ex & e);
+@end example
+
+@cindex @code{canonicalize_clifford()}
+The function @code{canonicalize_clifford()} works for a
+generic Clifford algebra in a similar way as for Dirac gammas.
+
+The last provided function is
+
+@cindex @code{clifford_moebius_map()}
+@example
+ ex clifford_moebius_map(const ex & a, const ex & b, const ex & c,
+ const ex & d, const ex & v, const ex & G, unsigned char rl = 0);
+ ex clifford_moebius_map(const ex & M, const ex & v, const ex & G, unsigned char rl = 0);
+@end example
+
+It takes a list or vector @code{v} and makes the Moebius
+(conformal or linear-fractional) transformation @samp{v ->
+(av+b)/(cv+d)} defined by the matrix @samp{M = [[a, b], [c, d]]}. The
+parameter @code{G} defines the metric of the surrounding
+(pseudo-)Euclidean space. The returned value of this function is a list
+of components of the resulting vector.
+
@cindex @code{color} (class)
@subsection Color algebra
ex color_ONE(unsigned char rl = 0);
@end example
-@strong{Note:} You must always use @code{color_ONE()} when referring to
+@strong{Please notice:} You must always use @code{color_ONE()} when referring to
multiples of the unity element, even though it's customary to omit it.
E.g. instead of @code{color_T(a)*(color_T(b)*indexed(X,b)+1)} you have to
write @code{color_T(a)*(color_T(b)*indexed(X,b)+color_ONE())}. Otherwise,
@item @code{Li(m, x)}
@tab classical polylogarithm as well as multiple polylogarithm
@cindex @code{Li()}
+@item @code{G(a, y)}
+@tab multiple polylogarithm
+@cindex @code{G()}
+@item @code{G(a, s, y)}
+@tab multiple polylogarithm with explicit signs for the imaginary parts
+@cindex @code{G()}
@item @code{S(n, p, x)}
@tab Nielsen's generalized polylogarithm
@cindex @code{S()}
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}.
+multiple polylogarithms, containing @code{Li}, @code{G}, @code{H}, @code{S} and @code{zeta}.
+The multiple polylogarithm itself comes in two variants: @code{Li} and @code{G}. While
+@code{Li} and @code{G} in principle represent the same function, the different
+notations are more natural to the series representation or the integral
+representation, respectively.
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}.
+@code{n} or @code{p}, whereas arguments are printed as @code{x}, @code{a} and @code{y}.
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.
+for the argument @code{x} as well. The parameter @code{a} of @code{G} must always be a @code{lst} containing
+the arguments in expanded form. If @code{G} is used with a third parameter @code{s}, @code{s} must
+have the same length as @code{a}. It contains then the signs of the imaginary parts of the arguments. If
+@code{s} is not given, the signs default to +1.
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
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{s} in @code{zeta} and @code{G} as well as @code{m} in @code{H}. Since @code{s}
+will be interpreted as the sequence of signs for the corresponding indices
+@code{m} or the sign of the imaginary part for the
+corresponding arguments @code{a}, it must contain 1 or -1, e.g.
@code{zeta(lst(3,4), lst(-1,1))} means
@tex
-$\zeta(\overline{3},4)$.
+$\zeta(\overline{3},4)$
+@end tex
+and
+@code{G(lst(a,b), lst(-1,1), c)} means
+@tex
+$G(a-0\epsilon,b+0\epsilon;c)$.
@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,
-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
+Every function can be numerically evaluated for
+arbitrary real or complex arguments. The precision is arbitrary and can be set through the
+global variable @code{Digits}:
@example
> Digits=100;
@cite{Special Values of Multiple Polylogarithms},
J.Borwein, D.Bradley, D.Broadhurst, P.Lisonek, Trans.Amer.Math.Soc. 353/3 (2001), pp. 907-941
+@cite{Numerical Evaluation of Multiple Polylogarithms},
+J.Vollinga, S.Weinzierl, hep-ph/0410259
+
@node Complex Conjugation, Solving Linear Systems of Equations, Multiple polylogarithms, Methods and Functions
@c node-name, next, previous, up
@section Complex Conjugation
by GiNaC to establish a canonical sort order for terms. It returns 0, +1 or
-1, depending on the relative order of this object and the @code{other}
object. If it returns 0, the objects are considered equal.
-@strong{Note:} This has nothing to do with the (numeric) ordering
+@strong{Please notice:} This has nothing to do with the (numeric) ordering
relationship expressed by @code{<}, @code{>=} etc (which cannot be defined
for non-numeric classes). For example, @code{numeric(1).compare_same_type(numeric(2))}
may return +1 even though 1 is clearly smaller than 2. Every GiNaC class
git://www.ginac.de / ginac.git / blobdiff