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-2007 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-2007 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-2007 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
ANSI-standard @cite{ISO/IEC 14882:1998(E)}. We used GCC for development
so if you have a different compiler you are on your own. For the
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, the CLN library
+@file{/bin/sh}, GNU @command{bash} is fine. The pkg-config utility is
+required for the configuration, it can be downloaded from
+@uref{http://pkg-config.freedesktop.org}.
+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
the file @file{configure.ac}. It is only distributed in packaged
releases of GiNaC. If you got the naked sources, e.g. from CVS, you
must generate @command{configure} along with the various
-@file{Makefile.in} by using the @command{autogen.sh} script. This will
+@file{Makefile.in} by using the @command{autoreconf} utility. This will
require a fair amount of support from your local toolchain, though.}
The whole process is illustrated in the following two
@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::
-* 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()}
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
+@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
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
@item
The @code{basic} class declares a member variable @code{tinfo_key} which
-holds an unsigned integer that identifies the object's class. These numbers
-are defined in the @file{tinfos.h} header file for the built-in GiNaC
-classes. They all start with @code{TINFO_}.
+holds a variable of @code{tinfo_t} type (which is actually just
+@code{const void*}) that identifies the object's class.
@item
By means of some clever tricks with static members, GiNaC maintains a list
using namespace GiNaC;
@end example
-The first thing we have to do is to define a @code{tinfo_key} for our new
-class. This can be any arbitrary unsigned number that is not already taken
-by one of the existing classes but it's better to come up with something
-that is unlikely to clash with keys that might be added in the future. The
-numbers in @file{tinfos.h} are modeled somewhat after the class hierarchy
-which is not a requirement but we are going to stick with this scheme:
-
-@example
-const unsigned TINFO_mystring = 0x42420001U;
-@end example
-
Now we can write down the class declaration. The class stores a C++
@code{string} and the user shall be able to construct a @code{mystring}
object from a C or C++ string:
Let's proceed step-by-step. The default constructor looks like this:
@example
-mystring::mystring() : inherited(TINFO_mystring) @{@}
+mystring::mystring() : inherited(&mystring::tinfo_static) @{@}
@end example
The golden rule is that in all constructors you have to set the
-@code{tinfo_key} member to the @code{TINFO_*} value of your class. Otherwise
+@code{tinfo_key} member to the @code{&your_class_name::tinfo_static}
+@footnote{Each GiNaC class has a static member called tinfo_static.
+This member is declared by the GINAC_DECLARE_REGISTERED_CLASS macros
+and defined by the GINAC_IMPLEMENT_REGISTERED_CLASS macros.}. Otherwise
it will be set by the constructor of the superclass and all hell will break
loose in the RTTI. For your convenience, the @code{basic} class provides
a constructor that takes a @code{tinfo_key} value, which we are using here
Now the only thing missing is our two new constructors:
@example
-mystring::mystring(const string &s) : inherited(TINFO_mystring), str(s) @{@}
-mystring::mystring(const char *s) : inherited(TINFO_mystring), str(s) @{@}
+mystring::mystring(const string &s) : inherited(&mystring::tinfo_static), str(s) @{@}
+mystring::mystring(const char *s) : inherited(&mystring::tinfo_static), str(s) @{@}
@end example
No surprises here. We set the @code{str} member from the argument and
ex mystring::eval(int level) const
@{
string new_str;
- for (int i=0; i<str.length(); i++) @{
+ for (size_t i=0; i<str.length(); i++) @{
char c = str[i];
if (c >= 'A' && c <= 'Z')
new_str += tolower(c);
That's it. May the source be with you!
+@subsection Upgrading extension classes from older version of GiNaC
+
+If you got some extension classes for GiNaC 1.3.X some changes are
+necessary in order to make your code work with GiNaC 1.4.
+
+@itemize @bullet
+@item constructors which set @code{tinfo_key} such as
+
+@example
+myclass::myclass() : inherited(TINFO_myclass) @{@}
+@end example
+
+need to be rewritten as
+
+@example
+myclass::myclass() : inherited(&myclass::tinfo_static) @{@}
+@end example
+
+@item TINO_myclass is not necessary any more and can be removed.
-@node A Comparison With Other CAS, Advantages, Adding classes, Top
+@end itemize
+
+
+@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, Configure script options, 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
-can be difficult. GiNaC includes two tools to make this process easier.
-
-@menu
-* ginac-config:: A shell script to detect compiler and linker flags.
-* AM_PATH_GINAC:: Macro for GNU automake.
-@end menu
-
-
-@node ginac-config, AM_PATH_GINAC, Package Tools, Package Tools
-@c node-name, next, previous, up
-@section @command{ginac-config}
-@cindex ginac-config
-
-@command{ginac-config} is a shell script that you can use to determine
-the compiler and linker command line options required to compile and
-link a program with the GiNaC library.
-
-@command{ginac-config} takes the following flags:
-
-@table @samp
-@item --version
-Prints out the version of GiNaC installed.
-@item --cppflags
-Prints '-I' flags pointing to the installed header files.
-@item --libs
-Prints out the linker flags necessary to link a program against GiNaC.
-@item --prefix[=@var{PREFIX}]
-If @var{PREFIX} is specified, overrides the configured value of @env{$prefix}.
-(And of exec-prefix, unless @code{--exec-prefix} is also specified)
-Otherwise, prints out the configured value of @env{$prefix}.
-@item --exec-prefix[=@var{PREFIX}]
-If @var{PREFIX} is specified, overrides the configured value of @env{$exec_prefix}.
-Otherwise, prints out the configured value of @env{$exec_prefix}.
-@end table
-
-Typically, @command{ginac-config} will be used within a configure
-script, as described below. It, however, can also be used directly from
-the command line using backquotes to compile a simple program. For
-example:
-
+setting the correct command line options for the compiler and linker can
+be difficult. The @command{pkg-config} utility makes this process
+easier. GiNaC supplies all necessary data in @file{ginac.pc} (installed
+into @code{/usr/local/lib/pkgconfig} by default). To compile a simple
+program use @footnote{If GiNaC is installed into some non-standard
+directory @var{prefix} one should set the @var{PKG_CONFIG_PATH}
+environment variable to @var{prefix}/lib/pkgconfig for this to work.}
@example
-c++ -o simple `ginac-config --cppflags` simple.cpp `ginac-config --libs`
+g++ -o simple `pkg-config --cflags --libs ginac` simple.cpp
@end example
This command line might expand to (for example):
-
@example
-cc -o simple -I/usr/local/include simple.cpp -L/usr/local/lib \
- -lginac -lcln -lstdc++
+g++ -o simple -lginac -lcln simple.cpp
@end example
-Not only is the form using @command{ginac-config} easier to type, it will
+Not only is the form using @command{pkg-config} easier to type, it will
work on any system, no matter how GiNaC was configured.
-
-@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
-
-For packages configured using GNU automake, GiNaC also provides
-a macro to automate the process of checking for GiNaC.
+For packages configured using GNU automake, @command{pkg-config} also
+provides the @code{PKG_CHECK_MODULES} macro to automate the process of
+checking for libraries
@example
-AM_PATH_GINAC([@var{MINIMUM-VERSION}, [@var{ACTION-IF-FOUND}
- [, @var{ACTION-IF-NOT-FOUND}]]])
+PKG_CHECK_MODULES(MYAPP, ginac >= MINIMUM_VERSION,
+ [@var{ACTION-IF-FOUND}],
+ [@var{ACTION-IF-NOT-FOUND}])
@end example
This macro:
@itemize @bullet
@item
-Determines the location of GiNaC using @command{ginac-config}, which is
-either found in the user's path, or from the environment variable
-@env{GINACLIB_CONFIG}.
+Determines the location of GiNaC using data from @file{ginac.pc}, which is
+either found in the default @command{pkg-config} search path, or from
+the environment variable @env{PKG_CONFIG_PATH}.
@item
Tests the installed libraries to make sure that their version
-is later than @var{MINIMUM-VERSION}. (A default version will be used
-if not specified)
+is later than @var{MINIMUM-VERSION}.
@item
-If the required version was found, sets the @env{GINACLIB_CPPFLAGS} variable
-to the output of @command{ginac-config --cppflags} and the @env{GINACLIB_LIBS}
-variable to the output of @command{ginac-config --libs}, and calls
+If the required version was found, sets the @env{MYAPP_CFLAGS} variable
+to the output of @command{pkg-config --cflags ginac} and the @env{MYAPP_LIBS}
+variable to the output of @command{pkg-config --libs ginac}, and calls
@samp{AC_SUBST()} for these variables so they can be used in generated
makefiles, and then executes @var{ACTION-IF-FOUND}.
@item
-If the required version was not found, sets @env{GINACLIB_CPPFLAGS} and
-@env{GINACLIB_LIBS} to empty strings, and executes @var{ACTION-IF-NOT-FOUND}.
+If the required version was not found, executes @var{ACTION-IF-NOT-FOUND}.
@end itemize
-This macro is in file @file{ginac.m4} which is installed in
-@file{$datadir/aclocal}. Note that if automake was installed with a
-different @samp{--prefix} than GiNaC, you will either have to manually
-move @file{ginac.m4} to automake's @file{$datadir/aclocal}, or give
-aclocal the @samp{-I} option when running it.
-
@menu
-* Configure script options:: Configuring a package that uses AM_PATH_GINAC.
-* Example package:: Example of a package using AM_PATH_GINAC.
+* Configure script options:: Configuring a package that uses GiNaC
+* Example package:: Example of a package using GiNaC
@end menu
-@node Configure script options, Example package, AM_PATH_GINAC, AM_PATH_GINAC
+@node Configure script options, Example package, Package tools, Package tools
@c node-name, next, previous, up
-@subsection Configuring a package that uses @samp{AM_PATH_GINAC}
-
-Simply make sure that @command{ginac-config} is in your path, and run
-the configure script.
-
-Notes:
-
-@itemize @bullet
+@subsection Configuring a package that uses GiNaC
-@item
The directory where the GiNaC libraries are installed needs
-to be found by your system's dynamic linker.
-
-This is generally done by
-
-@display
-editing @file{/etc/ld.so.conf} and running @command{ldconfig}
-@end display
+to be found by your system's dynamic linkers (both compile- and run-time
+ones). See the documentation of your system linker for details. Also
+make sure that @file{ginac.pc} is in @command{pkg-config}'s search path,
+@xref{pkg-config, ,pkg-config, *manpages*}.
-or by
-
-@display
-setting the environment variable @env{LD_LIBRARY_PATH},
-@end display
+The short summary below describes how to do this on a GNU/Linux
+system.
-or, as a last resort,
-
-@display
-giving a @samp{-R} or @samp{-rpath} flag (depending on your linker) when
-running configure, for instance:
+Suppose GiNaC is installed into the directory @samp{PREFIX}. To tell
+the linkers where to find the library one should
+@itemize @bullet
+@item
+edit @file{/etc/ld.so.conf} and run @command{ldconfig}. For example,
@example
-LDFLAGS=-R/home/cbauer/lib ./configure
+# echo PREFIX/lib >> /etc/ld.so.conf
+# ldconfig
@end example
-@end display
@item
-You can also specify a @command{ginac-config} not in your path by
-setting the @env{GINACLIB_CONFIG} environment variable to the
-name of the executable
+or set the environment variables @env{LD_LIBRARY_PATH} and @env{LD_RUN_PATH}
+@example
+$ export LD_LIBRARY_PATH=PREFIX/lib
+$ export LD_RUN_PATH=PREFIX/lib
+@end example
@item
-If you move the GiNaC package from its installed location,
-you will either need to modify @command{ginac-config} script
-manually to point to the new location or rebuild GiNaC.
+or give a @samp{-L} and @samp{--rpath} flags when running configure,
+for instance:
+@example
+$ LDFLAGS='-Wl,-LPREFIX/lib -Wl,--rpath=PREFIX/lib' ./configure
+@end example
@end itemize
-Advanced note:
-
-@itemize @bullet
-@item
-configure flags
-
+To tell @command{pkg-config} where the @file{ginac.pc} file is,
+set the @env{PKG_CONFIG_PATH} environment variable:
@example
---with-ginac-prefix=@var{PREFIX}
---with-ginac-exec-prefix=@var{PREFIX}
+$ export PKG_CONFIG_PATH=PREFIX/lib/pkgconfig
@end example
-are provided to override the prefix and exec-prefix that were stored
-in the @command{ginac-config} shell script by GiNaC's configure. You are
-generally better off configuring GiNaC with the right path to begin with.
-@end itemize
+Finally, run the @command{configure} script
+@example
+$ ./configure
+@end example
+@c There are many other ways to do the same, @xref{Options, ,Command Line Options, ld, GNU ld manual}.
-@node Example package, Bibliography, Configure script options, AM_PATH_GINAC
+@node Example package, Bibliography, Configure script options, Package tools
@c node-name, next, previous, up
-@subsection Example of a package using @samp{AM_PATH_GINAC}
+@subsection Example of a package using GiNaC
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}:
+and the @samp{PKG_CHECK_MODULES} macro. The program used here is @file{simple.cpp}:
@example
#include <iostream>
You should first read the introductory portions of the automake
Manual, if you are not already familiar with it.
-Two files are needed, @file{configure.in}, which is used to build the
+Two files are needed, @file{configure.ac}, which is used to build the
configure script:
@example
-dnl Process this file with autoconf to produce a configure script.
-AC_INIT(simple.cpp)
-AM_INIT_AUTOMAKE(simple.cpp, 1.0.0)
+dnl Process this file with autoreconf to produce a configure script.
+AC_INIT([simple], 1.0.0, bogus@@example.net)
+AC_CONFIG_SRCDIR(simple.cpp)
+AM_INIT_AUTOMAKE([foreign 1.8])
AC_PROG_CXX
AC_PROG_INSTALL
-AC_LANG_CPLUSPLUS
+AC_LANG([C++])
-AM_PATH_GINAC(0.9.0, [
- LIBS="$LIBS $GINACLIB_LIBS"
- CPPFLAGS="$CPPFLAGS $GINACLIB_CPPFLAGS"
-], AC_MSG_ERROR([need to have GiNaC installed]))
+PKG_CHECK_MODULES(SIMPLE, ginac >= 1.3.7)
AC_OUTPUT(Makefile)
@end example
-The only command in this which is not standard for automake
-is the @samp{AM_PATH_GINAC} macro.
+The @samp{PKG_CHECK_MODULES} macro does the following: If a GiNaC version
+greater or equal than 1.3.7 is found, then it defines @var{SIMPLE_CFLAGS}
+and @var{SIMPLE_LIBS}. Otherwise, it dies with the error message like
+@example
+configure: error: Package requirements (ginac >= 1.3.7) were not met:
+
+Requested 'ginac >= 1.3.7' but version of GiNaC is 1.3.5
-That command does the following: If a GiNaC version greater or equal
-than 0.7.0 is found, then it adds @env{$GINACLIB_LIBS} to @env{$LIBS}
-and @env{$GINACLIB_CPPFLAGS} to @env{$CPPFLAGS}. Otherwise, it dies with
-the error message `need to have GiNaC installed'
+Consider adjusting the PKG_CONFIG_PATH environment variable if you
+installed software in a non-standard prefix.
+
+Alternatively, you may set the environment variables SIMPLE_CFLAGS
+and SIMPLE_LIBS to avoid the need to call pkg-config.
+See the pkg-config man page for more details.
+@end example
And the @file{Makefile.am}, which will be used to build the Makefile.
## Process this file with automake to produce Makefile.in
bin_PROGRAMS = simple
simple_SOURCES = simple.cpp
+simple_CPPFLAGS = $(SIMPLE_CFLAGS)
+simple_LDADD = $(SIMPLE_LIBS)
@end example
This @file{Makefile.am}, says that we are building a single executable,
from a single source file @file{simple.cpp}. Since every program
-we are building uses GiNaC we simply added the GiNaC options
-to @env{$LIBS} and @env{$CPPFLAGS}, but in other circumstances, we might
-want to specify them on a per-program basis: for instance by
-adding the lines:
-
-@example
-simple_LDADD = $(GINACLIB_LIBS)
-INCLUDES = $(GINACLIB_CPPFLAGS)
-@end example
-
-to the @file{Makefile.am}.
+we are building uses GiNaC we could have simply added @var{SIMPLE_CFLAGS}
+to @var{CPPFLAGS} and @var{SIMPLE_LIBS} to @var{LIBS}. However, it is
+more flexible to specify libraries and complier options on a per-program
+basis.
To try this example out, create a new directory and add the three
files above to it.
-Now execute the following commands:
+Now execute the following command:
@example
-$ automake --add-missing
-$ aclocal
-$ autoconf
+$ autoreconf -i
@end example
You now have a package that can be built in the normal fashion
@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
git://www.ginac.de / ginac.git / blobdiff