This is a tutorial that documents GiNaC @value{VERSION}, an open
framework for symbolic computation within the C++ programming language.
-Copyright (C) 1999-2005 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2006 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
@title GiNaC @value{VERSION}
@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, Jens Vollinga
+@author @uref{http://www.ginac.de}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2005 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2006 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
@menu
* Introduction:: GiNaC's purpose.
-* A Tour of GiNaC:: A quick tour of the library.
+* A tour of GiNaC:: A quick tour of the library.
* Installation:: How to install the package.
-* Basic Concepts:: Description of fundamental classes.
-* Methods and Functions:: Algorithms for symbolic manipulations.
+* Basic concepts:: Description of fundamental classes.
+* Methods and functions:: Algorithms for symbolic manipulations.
* Extending GiNaC:: How to extend the library.
-* A Comparison With Other CAS:: Compares GiNaC to traditional CAS.
-* Internal Structures:: Description of some internal structures.
-* Package Tools:: Configuring packages to work with GiNaC.
+* A comparison with other CAS:: Compares GiNaC to traditional CAS.
+* Internal structures:: Description of some internal structures.
+* Package tools:: Configuring packages to work with GiNaC.
* Bibliography::
-* Concept Index::
+* Concept index::
@end menu
-@node Introduction, A Tour of GiNaC, Top, Top
+@node Introduction, A tour of GiNaC, Top, Top
@c node-name, next, previous, up
@chapter Introduction
@cindex history of GiNaC
@section License
The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999-2005 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2006 Johannes Gutenberg
University Mainz, Germany.
This program is free software; you can redistribute it and/or
MA 02110-1301, USA.
-@node A Tour of GiNaC, How to use it from within C++, Introduction, Top
+@node A tour of GiNaC, How to use it from within C++, Introduction, Top
@c node-name, next, previous, up
@chapter A Tour of GiNaC
@end menu
-@node How to use it from within C++, What it can do for you, A Tour of GiNaC, A Tour of GiNaC
+@node How to use it from within C++, What it can do for you, A tour of GiNaC, A tour of GiNaC
@c node-name, next, previous, up
@section How to use it from within C++
355687428096000*x*y+20922789888000*y^2+6402373705728000*x^2
@end example
-(@xref{Package Tools}, for tools that help you when creating a software
+(@xref{Package tools}, for tools that help you when creating a software
package that uses GiNaC.)
@cindex Hermite polynomial
convenient window into GiNaC's capabilities.
-@node What it can do for you, Installation, How to use it from within C++, A Tour of GiNaC
+@node What it can do for you, Installation, How to use it from within C++, A tour of GiNaC
@c node-name, next, previous, up
@section What it can do for you
configuration to succeed you need a Posix compliant shell installed in
@file{/bin/sh}, GNU @command{bash} is fine. Perl is needed by the built
process as well, since some of the source files are automatically
-generated by Perl scripts. Last but not least, Bruno Haible's library
-CLN is extensively used and needs to be installed on your system.
-Please get it either from @uref{ftp://ftp.santafe.edu/pub/gnu/}, from
-@uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/, GiNaC's FTP site} or
-from @uref{ftp://ftp.ilog.fr/pub/Users/haible/gnu/, Bruno Haible's FTP
-site} (it is covered by GPL) and install it prior to trying to install
+generated by Perl scripts. Last but not least, the CLN library
+is used extensively and needs to be installed on your system.
+Please get it from @uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/}
+(it is covered by GPL) and install it prior to trying to install
GiNaC. The configure script checks if it can find it and if it cannot
it will refuse to continue.
@var{target} there in case something went wrong.
-@node Installing GiNaC, Basic Concepts, Building GiNaC, Installation
+@node Installing GiNaC, Basic concepts, Building GiNaC, Installation
@c node-name, next, previous, up
@section Installing GiNaC
@cindex installation
installation.}.
-@node Basic Concepts, Expressions, Installing GiNaC, Top
+@node Basic concepts, Expressions, Installing GiNaC, Top
@c node-name, next, previous, up
-@chapter Basic Concepts
+@chapter Basic concepts
This chapter will describe the different fundamental objects that can be
handled by GiNaC. But before doing so, it is worthwhile introducing you
* Expressions:: The fundamental GiNaC class.
* Automatic evaluation:: Evaluation and canonicalization.
* Error handling:: How the library reports errors.
-* The Class Hierarchy:: Overview of GiNaC's classes.
+* The class hierarchy:: Overview of GiNaC's classes.
* Symbols:: Symbolic objects.
* Numbers:: Numerical objects.
* Constants:: Pre-defined constants.
* Matrices:: Matrices.
* Indexed objects:: Handling indexed quantities.
* Non-commutative objects:: Algebras with non-commutative products.
-* Hash Maps:: A faster alternative to std::map<>.
+* Hash maps:: A faster alternative to std::map<>.
@end menu
-@node Expressions, Automatic evaluation, Basic Concepts, Basic Concepts
+@node Expressions, Automatic evaluation, Basic concepts, Basic concepts
@c node-name, next, previous, up
@section Expressions
@cindex expression (class @code{ex})
Expressions are handles to other more fundamental objects, that often
contain other expressions thus creating a tree of expressions
-(@xref{Internal Structures}, for particular examples). Most methods on
+(@xref{Internal structures}, for particular examples). Most methods on
@code{ex} therefore run top-down through such an expression tree. For
example, the method @code{has()} scans recursively for occurrences of
something inside an expression. Thus, if you have declared @code{MyEx4}
Unsorted containers such as @code{std::vector<>} and @code{std::list<>}
don't pose a problem. A @code{std::vector<ex>} works as expected.
-@xref{Information About Expressions}, for more about comparing and ordering
+@xref{Information about expressions}, for more about comparing and ordering
expressions.
-@node Automatic evaluation, Error handling, Expressions, Basic Concepts
+@node Automatic evaluation, Error handling, Expressions, Basic concepts
@c node-name, next, previous, up
@section Automatic evaluation and canonicalization of expressions
@cindex evaluation
re-evaluate their results.
-@node Error handling, The Class Hierarchy, Automatic evaluation, Basic Concepts
+@node Error handling, The class hierarchy, Automatic evaluation, Basic concepts
@c node-name, next, previous, up
@section Error handling
@cindex exceptions
@end example
-@node The Class Hierarchy, Symbols, Error handling, Basic Concepts
+@node The class hierarchy, Symbols, Error handling, Basic concepts
@c node-name, next, previous, up
-@section The Class Hierarchy
+@section The class hierarchy
GiNaC's class hierarchy consists of several classes representing
mathematical objects, all of which (except for @code{ex} and some
pairs each consisting of one expression and a number (@code{numeric}).
What @emph{is} visible to the user are the derived classes @code{add}
and @code{mul}, representing sums and products. @xref{Internal
-Structures}, where these two classes are described in more detail. The
+structures}, where these two classes are described in more detail. The
following table shortly summarizes what kinds of mathematical objects
are stored in the different classes:
@end cartouche
-@node Symbols, Numbers, The Class Hierarchy, Basic Concepts
+@node Symbols, Numbers, The class hierarchy, Basic concepts
@c node-name, next, previous, up
@section Symbols
@cindex @code{symbol} (class)
As we said, the names of symbols primarily serve for purposes of expression
output. But there are actually two instances where GiNaC uses the names for
identifying symbols: When constructing an expression from a string, and when
-recreating an expression from an archive (@pxref{Input/Output}).
+recreating an expression from an archive (@pxref{Input/output}).
In addition to its name, a symbol may contain a special string that is used
in LaTeX output:
@end example
This creates a symbol that is printed as "@code{x}" in normal output, but
-as "@code{\Box}" in LaTeX code (@xref{Input/Output}, for more
+as "@code{\Box}" in LaTeX code (@xref{Input/output}, for more
information about the different output formats of expressions in GiNaC).
GiNaC automatically creates proper LaTeX code for symbols having names of
greek letters (@samp{alpha}, @samp{mu}, etc.).
calculations and give them a name, use C++ variables of type @code{ex}.
If you want to replace a symbol in an expression with something else, you
can invoke the expression's @code{.subs()} method
-(@pxref{Substituting Expressions}).
+(@pxref{Substituting expressions}).
@cindex @code{realsymbol()}
By default, symbols are expected to stand in for complex values, i.e. they live
in the complex domain. As a consequence, operations like complex conjugation,
-for example (@pxref{Complex Conjugation}), do @emph{not} evaluate if applied
+for example (@pxref{Complex expressions}), 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
+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{possymbol()}
+Furthermore, it is also possible to declare a symbol as positive. This will,
+for instance, enable the automatic simplification of @code{abs(x)} into
+@code{x}. This is done by declaying the symbol as @code{possymbol x("x");}.
-@node Numbers, Constants, Symbols, Basic Concepts
+
+@node Numbers, Constants, Symbols, Basic concepts
@c node-name, next, previous, up
@section Numbers
@cindex @code{numeric} (class)
@cindex @code{imag()}
@item @code{csgn(z)}
@tab complex sign (returns an @code{int})
+@item @code{step(x)}
+@tab step function (returns an @code{numeric})
@item @code{numer(z)}
@tab numerator of rational or complex rational number
@item @code{denom(z)}
part of complex numbers.
-@node Constants, Fundamental containers, Numbers, Basic Concepts
+@node Constants, Fundamental containers, Numbers, Basic concepts
@c node-name, next, previous, up
@section Constants
@cindex @code{constant} (class)
@end cartouche
-@node Fundamental containers, Lists, Constants, Basic Concepts
+@node Fundamental containers, Lists, Constants, Basic concepts
@c node-name, next, previous, up
@section Sums, products and powers
@cindex polynomial
@code{3*x+4-x} to @code{2*x+4}.
-@node Lists, Mathematical functions, Fundamental containers, Basic Concepts
+@node Lists, Mathematical functions, Fundamental containers, Basic concepts
@c node-name, next, previous, up
@section Lists of expressions
@cindex @code{lst} (class)
@end example
-@node Mathematical functions, Relations, Lists, Basic Concepts
+@node Mathematical functions, Relations, Lists, Basic concepts
@c node-name, next, previous, up
@section Mathematical functions
@cindex @code{function} (class)
There are quite a number of useful functions hard-wired into GiNaC. For
instance, all trigonometric and hyperbolic functions are implemented
-(@xref{Built-in Functions}, for a complete list).
+(@xref{Built-in functions}, for a complete list).
These functions (better called @emph{pseudofunctions}) are all objects
of class @code{function}. They accept one or more expressions as
wrapped inside an @code{ex}.
-@node Relations, Integrals, 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
+@node Integrals, Matrices, Relations, Basic concepts
@c node-name, next, previous, up
@section Integrals
@cindex @code{integral} (class)
as expected. Note that it makes no sense to differentiate an integral
with respect to the integration variable.
-@node Matrices, Indexed objects, Integrals, Basic Concepts
+@node Matrices, Indexed objects, Integrals, Basic concepts
@c node-name, next, previous, up
@section Matrices
@cindex @code{matrix} (class)
@}
@end example
+@cindex @code{is_zero_matrix()}
+The method @code{matrix::is_zero_matrix()} returns @code{true} only if
+all entries of the matrix are zeros. There is also method
+@code{ex::is_zero_matrix()} which returns @code{true} only if the
+expression is zero or a zero matrix.
+
@cindex @code{transpose()}
There are three ways to do arithmetic with matrices. The first (and most
direct one) is to use the methods provided by the @code{matrix} class:
overdetermined, an exception is thrown.
-@node Indexed objects, Non-commutative objects, Matrices, Basic Concepts
+@node Indexed objects, Non-commutative objects, Matrices, Basic concepts
@c node-name, next, previous, up
@section Indexed objects
for checking whether the value and dimension are numeric or symbolic
(non-numeric). Using the @code{info()} method of an index (see @ref{Information
-About Expressions}) returns information about the index value.
+about expressions}) returns information about the index value.
@cindex @code{varidx} (class)
If you need co- and contravariant indices, use the @code{varidx} class:
Sometimes you will want to substitute one symbolic index with another
symbolic or numeric index, for example when calculating one specific element
of a tensor expression. This is done with the @code{.subs()} method, as it
-is done for symbols (see @ref{Substituting Expressions}).
+is done for symbols (see @ref{Substituting expressions}).
You have two possibilities here. You can either substitute the whole index
by another index or expression:
The @code{scalar_products} object @code{sp} acts as a storage for the
scalar products added to it with the @code{.add()} method. This method
takes three arguments: the two expressions of which the scalar product is
-taken, and the expression to replace it with. After @code{sp.add(A, B, 0)},
-@code{simplify_indexed()} will replace all scalar products of indexed
-objects that have the symbols @code{A} and @code{B} as base expressions
-with the single value 0. The number, type and dimension of the indices
-don't matter; @samp{A~mu~nu*B.mu.nu} would also be replaced by 0.
+taken, and the expression to replace it with.
@cindex @code{expand()}
The example above also illustrates a feature of the @code{expand()} method:
of the metric tensor.
-@node Non-commutative objects, Hash Maps, Indexed objects, Basic Concepts
+@node Non-commutative objects, Hash maps, Indexed objects, Basic concepts
@c node-name, next, previous, up
@section Non-commutative objects
than in other computer algebra systems; they can, for example, automatically
canonicalize themselves according to rules specified in the implementation
of the non-commutative classes. The drawback is that to work with other than
-the built-in algebras you have to implement new classes yourself. Symbols
-always commutate and it's not possible to construct non-commutative products
-using symbols to represent the algebra elements or generators. User-defined
-functions can, however, be specified as being non-commutative.
+the built-in algebras you have to implement new classes yourself. Both
+symbols and user-defined functions can be specified as being non-commutative.
@cindex @code{return_type()}
@cindex @code{return_type_tinfo()}
function
@example
- ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0,
- bool anticommuting = false);
+ 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, an index @code{mu} with a numeric value may be of type
-@code{idx} as well.
+where @code{mu} should be a @code{idx} (or descendant) class object
+indexing the generators.
Parameter @code{metr} defines the metric @math{M(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. The last
-optional parameter @code{anticommuting} defines if the anticommuting
-assumption (i.e.
-@tex
-$e_i e_j + e_j e_i = 0$)
-@end tex
-@ifnottex
-e~i e~j + e~j e~i = 0)
-@end ifnottex
-will be used for contraction of Clifford units. If the @code{metric} is
-supplied by a @code{matrix} object, then the value of
-@code{anticommuting} is calculated automatically and the supplied one
-will be ignored. One can overcome this by giving @code{metric} through
-matrix wrapped into an @code{indexed} object.
+object. In fact, any expression either with two free indices or without
+indices at all is admitted as @code{metr}. In the later case an @code{indexed}
+object with two newly created indices with @code{metr} as its
+@code{op(0)} will be used.
+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)}, although
@cindex @code{clifford::get_metric()}
The method @code{clifford::get_metric()} returns a metric defining this
Clifford number.
-@cindex @code{clifford::is_anticommuting()}
-The method @code{clifford::is_anticommuting()} returns the
-@code{anticommuting} property of a unit.
If the matrix @math{M(i, j)} is in fact symmetric you may prefer to create
the Clifford algebra units with a call like that
@example
@{
...
- varidx nu(symbol("nu"), 4);
+ idx i(symbol("i"), 4);
realsymbol s("s");
ex M = diag_matrix(lst(1, -1, 0, s));
- ex e = clifford_unit(nu, M);
- ex e0 = e.subs(nu == 0);
- ex e1 = e.subs(nu == 1);
- ex e2 = e.subs(nu == 2);
- ex e3 = e.subs(nu == 3);
+ ex e = clifford_unit(i, M);
+ ex e0 = e.subs(i == 0);
+ ex e1 = e.subs(i == 1);
+ ex e2 = e.subs(i == 2);
+ ex e3 = e.subs(i == 3);
...
@}
@end example
@example
ex lst_to_clifford(const ex & v, const ex & mu, const ex & metr,
- unsigned char rl = 0, bool anticommuting = false);
+ unsigned char rl = 0);
ex lst_to_clifford(const ex & v, const ex & e);
@end example
with @samp{e.k}
directly supplied in the second form of the procedure. In the first form
the Clifford unit @samp{e.k} is generated by the call of
-@code{clifford_unit(mu, metr, rl, anticommuting)}. The previous code may be rewritten
+@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"), 4);
+ idx i(symbol("i"), 4);
realsymbol s("s");
ex M = diag_matrix(lst(1, -1, 0, s));
- ex e0 = lst_to_clifford(lst(1, 0, 0, 0), nu, M);
- ex e1 = lst_to_clifford(lst(0, 1, 0, 0), nu, M);
- ex e2 = lst_to_clifford(lst(0, 0, 1, 0), nu, M);
- ex e3 = lst_to_clifford(lst(0, 0, 0, 1), nu, M);
+ ex e0 = lst_to_clifford(lst(1, 0, 0, 0), i, M);
+ ex e1 = lst_to_clifford(lst(0, 1, 0, 0), i, M);
+ ex e2 = lst_to_clifford(lst(0, 0, 1, 0), i, M);
+ ex e3 = lst_to_clifford(lst(0, 0, 0, 1), i, M);
...
@}
@end example
@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, bool anticommuting = false);
+ unsigned char rl = 0);
ex clifford_moebius_map(const ex & M, const ex & v, const ex & G,
- unsigned char rl = 0, bool anticommuting = false);
+ unsigned char rl = 0);
@end example
It takes a list or vector @code{v} and makes the Moebius (conformal or
the matrix @samp{M = [[a, b], [c, d]]}. The parameter @code{G} defines
the metric of the surrounding (pseudo-)Euclidean space. This can be an
indexed object, tensormetric, matrix or a Clifford unit, in the later
-case the optional parameters @code{rl} and @code{anticommuting} are ignored
-even if supplied. The returned value of this function is a list of
-components of the resulting vector.
+case the optional parameter @code{rl} is ignored even if supplied.
+Depending from the type of @code{v} the returned value of this function
+is either a vector or a list holding vector's components.
@cindex @code{clifford_max_label()}
Finally the function
@end example
-@node Hash Maps, Methods and Functions, Non-commutative objects, Basic Concepts
+@node Hash maps, Methods and functions, Non-commutative objects, Basic concepts
@c node-name, next, previous, up
@section Hash Maps
@cindex hash maps
@end itemize
-@node Methods and Functions, Information About Expressions, Hash Maps, Top
+@node Methods and functions, Information about expressions, Hash maps, Top
@c node-name, next, previous, up
-@chapter Methods and Functions
+@chapter Methods and functions
@cindex polynomial
In this chapter the most important algorithms provided by GiNaC will be
avoided.
@menu
-* Information About Expressions::
-* Numerical Evaluation::
-* Substituting Expressions::
-* Pattern Matching and Advanced Substitutions::
-* Applying a Function on Subexpressions::
-* Visitors and Tree Traversal::
-* Polynomial Arithmetic:: Working with polynomials.
-* Rational Expressions:: Working with rational functions.
-* Symbolic Differentiation::
-* Series Expansion:: Taylor and Laurent expansion.
+* Information about expressions::
+* Numerical evaluation::
+* Substituting expressions::
+* Pattern matching and advanced substitutions::
+* Applying a function on subexpressions::
+* Visitors and tree traversal::
+* Polynomial arithmetic:: Working with polynomials.
+* Rational expressions:: Working with rational functions.
+* Symbolic differentiation::
+* Series expansion:: Taylor and Laurent expansion.
* Symmetrization::
-* Built-in Functions:: List of predefined mathematical functions.
+* 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.
+* Complex expressions::
+* Solving linear systems of equations::
+* Input/output:: Input and output of expressions.
@end menu
-@node Information About Expressions, Numerical Evaluation, Methods and Functions, Methods and Functions
+@node Information about expressions, Numerical evaluation, Methods and functions, Methods and functions
@c node-name, next, previous, up
@section Getting information about expressions
When the test made by @code{is_a<T>()} returns true, it is safe to call
one of the functions @code{ex_to<T>()}, where @code{T} is one of the
-class names (@xref{The Class Hierarchy}, for a list of all classes). For
+class names (@xref{The class hierarchy}, for a list of all classes). For
example, assuming @code{e} is an @code{ex}:
@example
@code{is_a<T>(e)} allows you to check whether the top-level object of
an expression @samp{e} is an instance of the GiNaC class @samp{T}
-(@xref{The Class Hierarchy}, for a list of all classes). This is most useful,
+(@xref{The class hierarchy}, for a list of all classes). This is most useful,
e.g., for checking whether an expression is a number, a sum, or a product:
@example
@item @code{numeric}
@tab @dots{}a number (same as @code{is_a<numeric>(...)})
@item @code{real}
-@tab @dots{}a real integer, rational or float (i.e. is not complex)
+@tab @dots{}a real number, symbol or constant (i.e. is not complex)
@item @code{rational}
@tab @dots{}an exact rational number (integers are rational, too)
@item @code{integer}
@end example
for checking whether one expression is equal to another, or equal to zero,
-respectively.
+respectively. See also the method @code{ex::is_zero_matrix()},
+@pxref{Matrices}.
@subsection Ordering expressions
after @code{other}.
-@node Numerical Evaluation, Substituting Expressions, Information About Expressions, Methods and Functions
+@node Numerical evaluation, Substituting expressions, Information about expressions, Methods and functions
@c node-name, next, previous, up
-@section Numerical Evaluation
+@section Numerical evaluation
@cindex @code{evalf()}
GiNaC keeps algebraic expressions, numbers and constants in their exact form.
@end example
-@node Substituting Expressions, Pattern Matching and Advanced Substitutions, Numerical Evaluation, Methods and Functions
+@node Substituting expressions, Pattern matching and advanced substitutions, Numerical evaluation, Methods and functions
@c node-name, next, previous, up
@section Substituting expressions
@cindex @code{subs()}
@end example
The optional last argument to @code{subs()} is a combination of
-@code{subs_options} flags. There are two options available:
+@code{subs_options} flags. There are three options available:
@code{subs_options::no_pattern} disables pattern matching, which makes
large @code{subs()} operations significantly faster if you are not using
patterns. The second option, @code{subs_options::algebraic} enables
algebraic substitutions in products and powers.
-@ref{Pattern Matching and Advanced Substitutions}, for more information
-about patterns and algebraic substitutions.
+@ref{Pattern matching and advanced substitutions}, for more information
+about patterns and algebraic substitutions. The third option,
+@code{subs_options::no_index_renaming} disables the feature that dummy
+indices are renamed if the subsitution could give a result in which a
+dummy index occurs more than two times. This is sometimes necessary if
+you want to use @code{subs()} to rename your dummy indices.
@code{subs()} performs syntactic substitution of any complete algebraic
object; it does not try to match sub-expressions as is demonstrated by the
next section.
-@node Pattern Matching and Advanced Substitutions, Applying a Function on Subexpressions, Substituting Expressions, Methods and Functions
+@node Pattern matching and advanced substitutions, Applying a function on subexpressions, Substituting expressions, Methods and functions
@c node-name, next, previous, up
@section Pattern matching and advanced substitutions
@cindex @code{wildcard} (class)
@}
@end example
-@subsection Algebraic substitutions
-Supplying the @code{subs_options::algebraic} option to @code{subs()}
-enables smarter, algebraic substitutions in products and powers. If you want
-to substitute some factors of a product, you only need to list these factors
-in your pattern. Furthermore, if an (integer) power of some expression occurs
-in your pattern and in the expression that you want the substitution to occur
-in, it can be substituted as many times as possible, without getting negative
-powers.
-
-An example clarifies it all (hopefully):
-
-@example
-cout << (a*a*a*a+b*b*b*b+pow(x+y,4)).subs(wild()*wild()==pow(wild(),3),
- subs_options::algebraic) << endl;
-// --> (y+x)^6+b^6+a^6
-
-cout << ((a+b+c)*(a+b+c)).subs(a+b==x,subs_options::algebraic) << endl;
-// --> (c+b+a)^2
-// Powers and products are smart, but addition is just the same.
-
-cout << ((a+b+c)*(a+b+c)).subs(a+b+wild()==x+wild(), subs_options::algebraic)
- << endl;
-// --> (x+c)^2
-// As I said: addition is just the same.
-
-cout << (pow(a,5)*pow(b,7)+2*b).subs(b*b*a==x,subs_options::algebraic) << endl;
-// --> x^3*b*a^2+2*b
-
-cout << (pow(a,-5)*pow(b,-7)+2*b).subs(1/(b*b*a)==x,subs_options::algebraic)
- << endl;
-// --> 2*b+x^3*b^(-1)*a^(-2)
-
-cout << (4*x*x*x-2*x*x+5*x-1).subs(x==a,subs_options::algebraic) << endl;
-// --> -1-2*a^2+4*a^3+5*a
-
-cout << (4*x*x*x-2*x*x+5*x-1).subs(pow(x,wild())==pow(a,wild()),
- subs_options::algebraic) << endl;
-// --> -1+5*x+4*x^3-2*x^2
-// You should not really need this kind of patterns very often now.
-// But perhaps this it's-not-a-bug-it's-a-feature (c/sh)ould still change.
-
-cout << ex(sin(1+sin(x))).subs(sin(wild())==cos(wild()),
- subs_options::algebraic) << endl;
-// --> cos(1+cos(x))
-
-cout << expand((a*sin(x+y)*sin(x+y)+a*cos(x+y)*cos(x+y)+b)
- .subs((pow(cos(wild()),2)==1-pow(sin(wild()),2)),
- subs_options::algebraic)) << endl;
-// --> b+a
-@end example
-
-
-@node Applying a Function on Subexpressions, Visitors and Tree Traversal, Pattern Matching and Advanced Substitutions, Methods and Functions
+@subsection The option algebraic
+Both @code{has()} and @code{subs()} take an optional argument to pass them
+extra options. This section describes what happens if you give the former
+the option @code{has_options::algebraic} or the latter
+@code{subs:options::algebraic}. In that case the matching condition for
+powers and multiplications is changed in such a way that they become
+more intuitive. Intuition says that @code{x*y} is a part of @code{x*y*z}.
+If you use these options you will find that
+@code{(x*y*z).has(x*y, has_options::algebraic)} indeed returns true.
+Besides matching some of the factors of a product also powers match as
+often as is possible without getting negative exponents. For example
+@code{(x^5*y^2*z).subs(x^2*y^2==c, subs_options::algebraic)} will return
+@code{x*c^2*z}. This also works with negative powers:
+@code{(x^(-3)*y^(-2)*z).subs(1/(x*y)==c, subs_options::algebraic)} will
+return @code{x^(-1)*c^2*z}. Note that this only works for multiplications
+and not for locating @code{x+y} within @code{x+y+z}.
+
+
+@node Applying a function on subexpressions, Visitors and tree traversal, Pattern matching and advanced substitutions, Methods and functions
@c node-name, next, previous, up
-@section Applying a Function on Subexpressions
+@section Applying a function on subexpressions
@cindex tree traversal
@cindex @code{map()}
@end example
-@node Visitors and Tree Traversal, Polynomial Arithmetic, Applying a Function on Subexpressions, Methods and Functions
+@node Visitors and tree traversal, Polynomial arithmetic, Applying a function on subexpressions, Methods and functions
@c node-name, next, previous, up
-@section Visitors and Tree Traversal
+@section Visitors and tree traversal
@cindex tree traversal
@cindex @code{visitor} (class)
@cindex @code{accept()}
@end example
-@node Polynomial Arithmetic, Rational Expressions, Visitors and Tree Traversal, Methods and Functions
+@node Polynomial arithmetic, Rational expressions, Visitors and tree traversal, Methods and functions
@c node-name, next, previous, up
@section Polynomial arithmetic
+@subsection Testing whether an expression is a polynomial
+@cindex @code{is_polynomial()}
+
+Testing whether an expression is a polynomial in one or more variables
+can be done with the method
+@example
+bool ex::is_polynomial(const ex & vars) const;
+@end example
+In the case of more than
+one variable, the variables are given as a list.
+
+@example
+(x*y*sin(y)).is_polynomial(x) // Returns true.
+(x*y*sin(y)).is_polynomial(lst(x,y)) // Returns false.
+@end example
+
@subsection Expanding and collecting
@cindex @code{expand()}
@cindex @code{collect()}
with this method.
-@node Rational Expressions, Symbolic Differentiation, Polynomial Arithmetic, Methods and Functions
+@node Rational expressions, Symbolic differentiation, Polynomial arithmetic, Methods and functions
@c node-name, next, previous, up
@section Rational expressions
@end example
-@node Symbolic Differentiation, Series Expansion, Rational Expressions, Methods and Functions
+@node Symbolic differentiation, Series expansion, Rational expressions, Methods and functions
@c node-name, next, previous, up
@section Symbolic differentiation
@cindex differentiation
@code{i} by two since all odd Euler numbers vanish anyways.
-@node Series Expansion, Symmetrization, Symbolic Differentiation, Methods and Functions
+@node Series expansion, Symmetrization, Symbolic differentiation, Methods and functions
@c node-name, next, previous, up
@section Series expansion
@cindex @code{series()}
@end example
-@node Symmetrization, Built-in Functions, Series Expansion, Methods and Functions
+@node Symmetrization, Built-in functions, Series expansion, Methods and functions
@c node-name, next, previous, up
@section Symmetrization
@cindex @code{symmetrize()}
@}
@end example
-@node Built-in Functions, Multiple polylogarithms, 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
@item @code{abs(x)}
@tab absolute value
@cindex @code{abs()}
+@item @code{step(x)}
+@tab step function
+@cindex @code{step()}
@item @code{csgn(x)}
@tab complex sign
@cindex @code{conjugate()}
@item @code{conjugate(x)}
@tab complex conjugation
-@cindex @code{csgn()}
+@cindex @code{real_part()}
+@item @code{real_part(x)}
+@tab real part
+@cindex @code{imag_part()}
+@item @code{imag_part(x)}
+@tab imaginary part
@item @code{sqrt(x)}
@tab square root (not a GiNaC function, rather an alias for @code{pow(x, numeric(1, 2))})
@cindex @code{sqrt()}
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
+@node Multiple polylogarithms, Complex expressions, Built-in functions, Methods and functions
@c node-name, next, previous, up
@subsection Multiple polylogarithms
@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
+@node Complex expressions, Solving linear systems of equations, Multiple polylogarithms, Methods and functions
@c node-name, next, previous, up
-@section Complex Conjugation
+@section Complex expressions
@c
@cindex @code{conjugate()}
-The method
+For dealing with complex expressions there are the methods
@example
ex ex::conjugate();
+ex ex::real_part();
+ex ex::imag_part();
@end example
-returns the complex conjugate of the expression. For all built-in functions and objects the
-conjugation gives the expected results:
+that return respectively the complex conjugate, the real part and the
+imaginary part of an expression. Complex conjugation works as expected
+for all built-in functinos and objects. Taking real and imaginary
+parts has not yet been implemented for all built-in functions. In cases where
+it is not known how to conjugate or take a real/imaginary part one
+of the functions @code{conjugate}, @code{real_part} or @code{imag_part}
+is returned. For instance, in case of a complex symbol @code{x}
+(symbols are complex by default), one could not simplify
+@code{conjugate(x)}. In the case of strings of gamma matrices,
+the @code{conjugate} method takes the Dirac conjugate.
+For example,
@example
@{
varidx a(symbol("a"), 4), b(symbol("b"), 4);
@}
@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).
+If you declare your own GiNaC functions, then they will conjugate themselves
+by conjugating their arguments. This is the default strategy. If you 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). Also, specialized methods can be provided
+to take real and imaginary parts of user-defined functions.
-@node Solving Linear Systems of Equations, Input/Output, Complex Conjugation, Methods and Functions
+@node Solving linear systems of equations, Input/output, Complex expressions, Methods and functions
@c node-name, next, previous, up
-@section Solving Linear Systems of Equations
+@section Solving linear systems of equations
@cindex @code{lsolve()}
The function @code{lsolve()} provides a convenient wrapper around some
Here, @code{eqns} is a @code{lst} of equalities (i.e. class
@code{relational}) while @code{symbols} is a @code{lst} of
-indeterminates. (@xref{The Class Hierarchy}, for an exposition of class
+indeterminates. (@xref{The class hierarchy}, for an exposition of class
@code{lst}).
It returns the @code{lst} of solutions as an expression. As an example,
around that method.
-@node Input/Output, Extending GiNaC, Solving Linear Systems of Equations, Methods and Functions
+@node Input/output, Extending GiNaC, Solving linear systems of equations, Methods and functions
@c node-name, next, previous, up
@section Input and output of expressions
@cindex I/O
// ...
@end example
+@anchor{csrc printing}
@cindex @code{csrc}
@cindex @code{csrc_float}
@cindex @code{csrc_double}
@}
@end example
+@subsection Compiling expressions to C function pointers
+@cindex compiling expressions
+
+Numerical evaluation of algebraic expressions is seamlessly integrated into
+GiNaC by help of the CLN library. While CLN allows for very fast arbitrary
+precision numerics, which is more than sufficient for most users, sometimes only
+the speed of built-in floating point numbers is fast enough, e.g. for Monte
+Carlo integration. The only viable option then is the following: print the
+expression in C syntax format, manually add necessary C code, compile that
+program and run is as a separate application. This is not only cumbersome and
+involves a lot of manual intervention, but it also separates the algebraic and
+the numerical evaluation into different execution stages.
+
+GiNaC offers a couple of functions that help to avoid these inconveniences and
+problems. The functions automatically perform the printing of a GiNaC expression
+and the subsequent compiling of its associated C code. The created object code
+is then dynamically linked to the currently running program. A function pointer
+to the C function that performs the numerical evaluation is returned and can be
+used instantly. This all happens automatically, no user intervention is needed.
+
+The following example demonstrates the use of @code{compile_ex}:
+
+@example
+ // ...
+ symbol x("x");
+ ex myexpr = sin(x) / x;
+
+ FUNCP_1P fp;
+ compile_ex(myexpr, x, fp);
+
+ cout << fp(3.2) << endl;
+ // ...
+@end example
+
+The function @code{compile_ex} is called with the expression to be compiled and
+its only free variable @code{x}. Upon successful completion the third parameter
+contains a valid function pointer to the corresponding C code module. If called
+like in the last line only built-in double precision numerics is involved.
+
+@cindex FUNCP_1P
+@cindex FUNCP_2P
+@cindex FUNCP_CUBA
+The function pointer has to be defined in advance. GiNaC offers three function
+pointer types at the moment:
+
+@example
+ typedef double (*FUNCP_1P) (double);
+ typedef double (*FUNCP_2P) (double, double);
+ typedef void (*FUNCP_CUBA) (const int*, const double[], const int*, double[]);
+@end example
+
+@cindex CUBA library
+@cindex Monte Carlo integration
+@code{FUNCP_2P} allows for two variables in the expression. @code{FUNCP_CUBA} is
+the correct type to be used with the CUBA library
+(@uref{http://www.feynarts/cuba}) for numerical integrations. The details for the
+parameters of @code{FUNCP_CUBA} are explained in the CUBA manual.
+
+@cindex compile_ex
+For every function pointer type there is a matching @code{compile_ex} available:
+
+@example
+ void compile_ex(const ex& expr, const symbol& sym, FUNCP_1P& fp,
+ const std::string filename = "");
+ void compile_ex(const ex& expr, const symbol& sym1, const symbol& sym2,
+ FUNCP_2P& fp, const std::string filename = "");
+ void compile_ex(const lst& exprs, const lst& syms, FUNCP_CUBA& fp,
+ const std::string filename = "");
+@end example
+
+When the last parameter @code{filename} is not supplied, @code{compile_ex} will
+choose a unique random name for the intermediate source and object files it
+produces. On program termination these files will be deleted. If one wishes to
+keep the C code and the object files, one can supply the @code{filename}
+parameter. The intermediate files will use that filename and will not be
+deleted.
+
+@cindex link_ex
+@code{link_ex} is a function that allows to dynamically link an existing object
+file and to make it available via a function pointer. This is useful if you
+have already used @code{compile_ex} on an expression and want to avoid the
+compilation step to be performed over and over again when you restart your
+program. The precondition for this is of course, that you have chosen a
+filename when you did call @code{compile_ex}. For every above mentioned
+function pointer type there exists a corresponding @code{link_ex} function:
+
+@example
+ void link_ex(const std::string filename, FUNCP_1P& fp);
+ void link_ex(const std::string filename, FUNCP_2P& fp);
+ void link_ex(const std::string filename, FUNCP_CUBA& fp);
+@end example
+
+The complete filename (including the suffix @code{.so}) of the object file has
+to be supplied.
+
+The function
+
+@cindex unlink_ex
+@example
+ void unlink_ex(const std::string filename);
+@end example
+
+is supplied for the rare cases when one wishes to close the dynamically linked
+object files directly and have the intermediate files (only if filename has not
+been given) deleted. Normally one doesn't need this function, because all the
+clean-up will be done automatically upon (regular) program termination.
+
+All the described functions will throw an exception in case they cannot perform
+correctly, like for example when writing the file or starting the compiler
+fails. Since internally the same printing methods as described in section
+@ref{csrc printing} are used, only functions and objects that are available in
+standard C will compile successfully (that excludes polylogarithms for example
+at the moment). Another precondition for success is, of course, that it must be
+possible to evaluate the expression numerically. No free variables despite the
+ones supplied to @code{compile_ex} should appear in the expression.
+
+@cindex ginac-excompiler
+@code{compile_ex} uses the shell script @code{ginac-excompiler} to start the C
+compiler and produce the object files. This shell script comes with GiNaC and
+will be installed together with GiNaC in the configured @code{$PREFIX/bin}
+directory.
@subsection Archiving
@cindex @code{archive} (class)
class may change between GiNaC versions.
-@node Extending GiNaC, What does not belong into GiNaC, Input/Output, Top
+@node Extending GiNaC, What does not belong into GiNaC, Input/output, Top
@c node-name, next, previous, up
@chapter Extending GiNaC
@section GiNaC's expression output system
GiNaC allows the output of expressions in a variety of different formats
-(@pxref{Input/Output}). This section will explain how expression output
+(@pxref{Input/output}). This section will explain how expression output
is implemented internally, and how to define your own output formats or
change the output format of built-in algebraic objects. You will also want
to read this section if you plan to write your own algebraic classes or
@code{sprod::unarchive()} function.
-@node Adding classes, A Comparison With Other CAS, Structures, Extending GiNaC
+@node Adding classes, A comparison with other CAS, Structures, Extending GiNaC
@c node-name, next, previous, up
@section Adding classes
cout << is_a<mystring>(e) << endl;
// -> 1 (true)
-cout << e.bp->class_name() << endl;
+cout << ex_to<basic>(e).class_name() << endl;
// -> mystring
@end example
That's it. May the source be with you!
-@node A Comparison With Other CAS, Advantages, Adding classes, Top
+@node A comparison with other CAS, Advantages, Adding classes, Top
@c node-name, next, previous, up
@chapter A Comparison With Other CAS
@cindex advocacy
* Why C++?:: Attractiveness of C++.
@end menu
-@node Advantages, Disadvantages, A Comparison With Other CAS, A Comparison With Other CAS
+@node Advantages, Disadvantages, A comparison with other CAS, A comparison with other CAS
@c node-name, next, previous, up
@section Advantages
@end itemize
-@node Disadvantages, Why C++?, Advantages, A Comparison With Other CAS
+@node Disadvantages, Why C++?, Advantages, A comparison with other CAS
@c node-name, next, previous, up
@section Disadvantages
@end itemize
-@node Why C++?, Internal Structures, Disadvantages, A Comparison With Other CAS
+@node Why C++?, Internal structures, Disadvantages, A comparison with other CAS
@c node-name, next, previous, up
@section Why C++?
any other programming language.
-@node Internal Structures, Expressions are reference counted, Why C++? , Top
+@node Internal structures, Expressions are reference counted, Why C++? , Top
@c node-name, next, previous, up
-@appendix Internal Structures
+@appendix Internal structures
@menu
* Expressions are reference counted::
* Internal representation of products and sums::
@end menu
-@node Expressions are reference counted, Internal representation of products and sums, Internal Structures, Internal Structures
+@node Expressions are reference counted, Internal representation of products and sums, Internal structures, Internal structures
@c node-name, next, previous, up
@appendixsection Expressions are reference counted
implementation which is pretty close to the one in GiNaC.
-@node Internal representation of products and sums, Package Tools, Expressions are reference counted, Internal Structures
+@node Internal representation of products and sums, Package tools, Expressions are reference counted, Internal structures
@c node-name, next, previous, up
@appendixsection Internal representation of products and sums
but the data structure is inherited from @code{expairseq}.
-@node Package Tools, ginac-config, Internal representation of products and sums, Top
+@node Package tools, ginac-config, Internal representation of products and sums, Top
@c node-name, next, previous, up
-@appendix Package Tools
+@appendix Package tools
If you are creating a software package that uses the GiNaC library,
setting the correct command line options for the compiler and linker
@end menu
-@node ginac-config, AM_PATH_GINAC, Package Tools, Package Tools
+@node ginac-config, AM_PATH_GINAC, Package tools, Package tools
@c node-name, next, previous, up
@section @command{ginac-config}
@cindex ginac-config
work on any system, no matter how GiNaC was configured.
-@node AM_PATH_GINAC, Configure script options, ginac-config, Package Tools
+@node AM_PATH_GINAC, Configure script options, ginac-config, Package tools
@c node-name, next, previous, up
@section @samp{AM_PATH_GINAC}
@cindex AM_PATH_GINAC
@end example
-@node Bibliography, Concept Index, Example package, Top
+@node Bibliography, Concept index, Example package, Top
@c node-name, next, previous, up
@appendix Bibliography
@end itemize
-@node Concept Index, , Bibliography, Top
+@node Concept index, , Bibliography, Top
@c node-name, next, previous, up
-@unnumbered Concept Index
+@unnumbered Concept index
@printindex cp