@include version.texi
+@dircategory Mathematics
@direntry
* ginac: (ginac). C++ library for symbolic computation.
@end direntry
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-2008 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-2008 Johannes Gutenberg University Mainz, Germany
@sp 2
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@section License
The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999-2005 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2008 Johannes Gutenberg
University Mainz, Germany.
This program is free software; you can redistribute it and/or
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
have a look at the most important classes in the class hierarchy and
some of the relations among the classes:
+@ifnotinfo
@image{classhierarchy}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
The abstract classes shown here (the ones without drop-shadow) are of no
interest for the user. They are used internally in order to avoid code
Now, here is one important property of GiNaC that differentiates it from
other computer algebra programs you may have used: GiNaC does @emph{not} use
the names of symbols to tell them apart, but a (hidden) serial number that
-is unique for each newly created @code{symbol} object. In you want to use
+is unique for each newly created @code{symbol} object. If you want to use
one and the same symbol in different places in your program, you must only
create one @code{symbol} object and pass that around. If you create another
symbol, even if it has the same name, GiNaC will treat it as a different
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 declaring the symbol as @code{possymbol x("x");}.
+
@node Numbers, Constants, Symbols, Basic concepts
@c node-name, next, previous, up
@end example
Note that the variable @code{answer} is constructed here as an integer
-by @code{numeric}'s copy constructor but in an intermediate step it
+by @code{numeric}'s copy constructor, but in an intermediate step it
holds a rational number represented as integer numerator and integer
denominator. When multiplied by 10, the denominator becomes unity and
the result is automatically converted to a pure integer again.
@tab @dots{}equal to zero
@item @code{.is_positive()}
@tab @dots{}not complex and greater than 0
+@item @code{.is_negative()}
+@tab @dots{}not complex and smaller than 0
@item @code{.is_integer()}
@tab @dots{}a (non-complex) integer
@item @code{.is_pos_integer()}
@end multitable
@end cartouche
+@page
+
@subsection Numeric functions
The following functions can be applied to @code{numeric} objects and will be
The predefined known constants are:
@cartouche
-@multitable @columnfractions .14 .30 .56
+@multitable @columnfractions .14 .32 .54
@item @strong{Name} @tab @strong{Common Name} @tab @strong{Numerical Value (to 35 digits)}
@item @code{Pi}
@tab Archimedes' constant
evaluation, is also available as
@example
ex adaptivesimpson(const ex & x, const ex & a, const ex & b, const ex & f,
-const ex & error)
+ const ex & error)
@end example
This function will throw an exception if the maximum depth is exceeded. The
last parameter of the function is optional and defaults to the
@}
@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:
anything useful with it.
@cindex @code{get_value()}
-@cindex @code{get_dimension()}
+@cindex @code{get_dim()}
The methods
@example
ex idx::get_value();
-ex idx::get_dimension();
+ex idx::get_dim();
@end example
return the value and dimension of an @code{idx} object. If you have an index
that performs some more expensive operations:
-@itemize
+@itemize @bullet
@item it checks the consistency of free indices in sums in the same way
@code{get_free_indices()} does
@item it tries to give dummy indices that appear in different terms of a sum
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:
the header file @file{flags.h}), corresponding to three categories of
expressions in GiNaC:
-@itemize
+@itemize @bullet
@item @code{return_types::commutative}: Commutates with everything. Most GiNaC
classes are of this kind.
@item @code{return_types::noncommutative}: Non-commutative, belonging to a
The value returned by the @code{return_type_tinfo()} method is valid only
when the return type of the expression is @code{noncommutative}. It is a
-value that is unique to the class of the object and usually one of the
-constants in @file{tinfos.h}, or derived therefrom.
+value that is unique to the class of the object, but may vary every time a
+GiNaC program is being run (it is dynamically assigned on start-up).
Here are a couple of examples:
functional is not cyclic in
@tex $D \ne 4$
@end tex
+@ifnottex
+@math{D != 4}
+@end ifnottex
dimensions when acting on
expressions containing @samp{gamma5}, so it's not a proper trace. This
-@samp{gamma5} scheme is described in greater detail in
-@cite{The Role of gamma5 in Dimensional Regularization}.
+@samp{gamma5} scheme is described in greater detail in the article
+@cite{The Role of gamma5 in Dimensional Regularization} (@ref{Bibliography}).
The value of the trace itself is also usually different in 4 and in
@tex $D \ne 4$
@end tex
+@ifnottex
+@math{D != 4}
+@end ifnottex
dimensions:
@example
@subsubsection A generic Clifford algebra
A generic Clifford algebra, i.e. a
-@tex
-$2^n$
+@tex $2^n$
@end tex
+@ifnottex
+2^n
+@end ifnottex
dimensional algebra with
generators
@tex $e_k$
@end tex
+@ifnottex
+e_k
+@end ifnottex
satisfying the identities
@tex
-$e_i e_j + e_j e_i = M(i, j) + M(j, i) $
+$e_i e_j + e_j e_i = M(i, j) + M(j, i)$
@end tex
@ifnottex
e~i e~j + e~j e~i = M(i, j) + M(j, i)
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
-with the help of @code{lst_to_clifford()} as follows
+@code{clifford_unit(mu, metr, rl)}.
+@cindex pseudo-vector
+If the number of components supplied
+by @code{v} exceeds the dimensionality of the Clifford unit @code{e} by
+1 then function @code{lst_to_clifford()} uses the following
+pseudo-vector representation:
+@tex
+$v^0 {\bf 1} + v^1 e_0 + v^2 e_1 + ... + v^{n+1} e_n$
+@end tex
+@ifnottex
+@samp{v~0 ONE + v~1 e.0 + v~2 e.1 + ... + v~[n+1] e.n}
+@end ifnottex
+
+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
@ifnottex
@samp{v = (v~0, v~1, ..., v~n)}
@end ifnottex
-such that
+such that the expression is either vector
@tex
$e = v^0 c_0 + v^1 c_1 + ... + v^n c_n$
@end tex
@ifnottex
@samp{e = v~0 c.0 + v~1 c.1 + ... + v~n c.n}
@end ifnottex
-with respect to the given Clifford units @code{c} and with none of the
-@samp{v~k} containing Clifford units @code{c} (of course, this
+or pseudo-vector
+@tex
+$v^0 {\bf 1} + v^1 e_0 + v^2 e_1 + ... + v^{n+1} e_n$
+@end tex
+@ifnottex
+@samp{v~0 ONE + v~1 e.0 + v~2 e.1 + ... + v~[n+1] e.n}
+@end ifnottex
+with respect to the given Clifford units @code{c}. Here none of the
+@samp{v~k} should contain Clifford units @code{c} (of course, this
may be impossible). This function can use an @code{algebraic} method
-(default) or a symbolic one. With the @code{algebraic} method the @samp{v~k} are calculated as
+(default) or a symbolic one. With the @code{algebraic} method the
+@samp{v~k} are calculated as
@tex
$(e c_k + c_k e)/c_k^2$. If $c_k^2$
@end tex
@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
@code{\clifford[1]@{e@}^@{@{\nu@}@}}, where @code{1} is the
@code{representation_label} and @code{\nu} is the index of the
corresponding unit. This provides a flexible typesetting with a suitable
-defintion of the @code{\clifford} command. For example, the definition
+definition of the @code{\clifford} command. For example, the definition
@example
\newcommand@{\clifford@}[1][]@{@}
@end example
@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
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
+@xref{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
+indices are renamed if the substitution 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.
Notes:
-@itemize
+@itemize @bullet
@item Wildcards behave like symbols and are subject to the same algebraic
rules. E.g., @samp{$0+2*$0} is automatically transformed to @samp{3*$0}.
@item As shown in the last example, to use wildcards for indices you have to
> match((a+b)*(a+c),($1+b)*($1+c));
@{$1==a@}
> match((a+b)*(a+c),(a+$1)*(a+$2));
-@{$1==c,$2==b@}
+@{$1==b,$2==c@}
(Unpredictable. The result might also be [$1==c,$2==b].)
> match((a+b)*(a+c),($1+$2)*($1+$3));
(The result is undefined. Due to the sequential nature of the algorithm
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
+@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^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
+return @code{x^(-1)*c^2*z}.
+
+@strong{Note:} this only works for multiplications
and not for locating @code{x+y} within @code{x+y+z}.
@tex
$\pi$
@end tex
+@ifnottex
+@math{Pi}
+@end ifnottex
(for which there already exists the built-in constant @code{Pi})
using John Machin's amazing formula
@tex
@}
@end example
+@page
+
@node Built-in functions, Multiple polylogarithms, Symmetrization, Methods and functions
@c node-name, next, previous, up
@section Predefined mathematical functions
@tex
$\zeta(m_1,m_2,\ldots,m_k)$.
@end tex
+@ifnottex
+@command{\mbox@{Li@}_@{m_1,m_2,...,m_k@}(x_1,x_2,...,x_k)},
+@command{\mbox@{S@}_@{n,p@}(x)},
+@command{\mbox@{H@}_@{m_1,m_2,...,m_k@}(x)} and
+@command{\zeta(m_1,m_2,...,m_k)} (with the dots replaced by actual parameters).
+@end ifnottex
If @code{zeta} is an alternating zeta sum, i.e. @code{zeta(m,s)}, the indices with negative sign
are printed with a line above, e.g.
@tex
$\zeta(5,\overline{2})$.
@end tex
+@ifnottex
+@command{\zeta(5,\overline@{2@})}.
+@end ifnottex
The order of indices and arguments in the GiNaC @code{lst}s and in the output is the same.
Definitions and analytical as well as numerical properties of multiple polylogarithms
@tex
$\zeta(1,2)$ evaluates to infinity.
@end tex
-So in comparison to the referenced publications the order of indices and arguments for @code{Li}
-is reversed.
+@ifnottex
+@code{Li_@{m_1,m_2,m_3@}(x,1,1) = H_@{m_1,m_2,m_3@}(x)} and
+@code{Li_@{2,1@}(1,1) = zeta(2,1) = zeta(3)}, but
+@code{zeta(1,2)} evaluates to infinity.
+@end ifnottex
+So in comparison to the older ones of the referenced publications the order of
+indices and arguments for @code{Li} is reversed.
The functions only evaluate if the indices are integers greater than zero, except for the indices
@code{s} in @code{zeta} and @code{G} as well as @code{m} in @code{H}. Since @code{s}
@tex
$\zeta(\overline{3},4)$
@end tex
+@ifnottex
+@command{zeta(\overline@{3@},4)}
+@end ifnottex
and
@code{G(lst(a,b), lst(-1,1), c)} means
@tex
$G(a-0\epsilon,b+0\epsilon;c)$.
@end tex
+@ifnottex
+@command{G(a-0\epsilon,b+0\epsilon;c)}.
+@end ifnottex
The definition of @code{H} allows indices to be 0, 1 or -1 (in expanded notation) or equally to
be any integer (in compact notation). With GiNaC expanded and compact notation can be mixed,
e.g. @code{lst(0,0,-1,0,1,0,0)}, @code{lst(0,0,-1,2,0,0)} and @code{lst(-3,2,0,0)} are equivalent as
@tex
$\zeta(1)$.
@end tex
+@ifnottex
+@command{zeta(1)}.
+@end ifnottex
In long expressions this helps a lot with debugging, because you can easily spot
the divergencies. But on the other hand, you have to make sure for yourself, that no illegal
cancellations of divergencies happen.
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
+for all built-in functions 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}
// ...
@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)
@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
placing character strings in algebraic expressions (this is not very useful,
but it's just an example). This class will be a direct subclass of
@code{basic}. You can use this sample implementation as a starting point
-for your own classes.
+for your own classes @footnote{The self-contained source for this example is
+included in GiNaC, see the @file{doc/examples/mystring.cpp} file.}.
The code snippets given here assume that you have included some header files
as follows:
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:
GINAC_DECLARE_REGISTERED_CLASS(mystring, basic)
public:
- mystring(const string &s);
- mystring(const char *s);
+ mystring(const string & s);
+ mystring(const char * s);
private:
string str;
@code{mystring()}, the default constructor.
@item
-@code{void archive(archive_node &n)}, the archiving function. This stores all
+@code{void archive(archive_node & n)}, the archiving function. This stores all
information needed to reconstruct an object of this class inside an
@code{archive_node}.
@item
-@code{mystring(const archive_node &n, lst &sym_lst)}, the unarchiving
+@code{mystring(const archive_node & n, lst & sym_lst)}, the unarchiving
constructor. This constructs an instance of the class from the information
found in an @code{archive_node}.
@item
-@code{ex unarchive(const archive_node &n, lst &sym_lst)}, the static
+@code{ex unarchive(const archive_node & n, lst & sym_lst)}, the static
unarchiving function. It constructs a new instance by calling the unarchiving
constructor.
@item
@cindex @code{compare_same_type()}
-@code{int compare_same_type(const basic &other)}, which is used internally
+@code{int compare_same_type(const basic & other)}, which is used internally
by GiNaC to establish a canonical sort order for terms. It returns 0, +1 or
-1, depending on the relative order of this object and the @code{other}
object. If it returns 0, the objects are considered equal.
defined.
@item
-And, of course, @code{mystring(const string &s)} and @code{mystring(const char *s)}
+And, of course, @code{mystring(const string & s)} and @code{mystring(const char * s)}
which are the two constructors we declared.
@end itemize
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
is really simple. First, the archiving function:
@example
-void mystring::archive(archive_node &n) const
+void mystring::archive(archive_node & n) const
@{
inherited::archive(n);
n.add_string("string", str);
function:
@example
-mystring::mystring(const archive_node &n, lst &sym_lst) : inherited(n, sym_lst)
+mystring::mystring(const archive_node & n, lst & sym_lst) : inherited(n, sym_lst)
@{
n.find_string("string", str);
@}
Finally, the unarchiving function:
@example
-ex mystring::unarchive(const archive_node &n, lst &sym_lst)
+ex mystring::unarchive(const archive_node & n, lst & sym_lst)
@{
return (new mystring(n, sym_lst))->setflag(status_flags::dynallocated);
@}
the string members:
@example
-int mystring::compare_same_type(const basic &other) const
+int mystring::compare_same_type(const basic & other) const
@{
const mystring &o = static_cast<const mystring &>(other);
int cmpval = str.compare(o.str);
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
@{
...
protected:
- void do_print(const print_context &c, unsigned level = 0) const;
+ void do_print(const print_context & c, unsigned level = 0) const;
...
@};
-void mystring::do_print(const print_context &c, unsigned level) const
+void mystring::do_print(const print_context & c, unsigned level) const
@{
// print_context::s is a reference to an ostream
c.s << '\"' << str << '\"';
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);
@cindex @code{is_equal_same_type()}
@example
unsigned calchash() const;
-bool is_equal_same_type(const basic &other) const;
+bool is_equal_same_type(const basic & other) const;
@end example
The @code{calchash()} method returns an @code{unsigned} hash value for the
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.
+
+@end itemize
+
@node A comparison with other CAS, Advantages, Adding classes, Top
@c node-name, next, previous, up
and exponent and some atomic leaves of symbols and numbers in this
fashion:
+@ifnotinfo
@image{repnaive}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
@cindex pair-wise representation
However, doing so results in a rather deeply nested tree which will
having a numeric exponent and a possibly complicated base, the tree
becomes much more flat:
+@ifnotinfo
@image{reppair}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
The number @code{3} above the symbol @code{d} shows that @code{mul}
objects are treated similarly where the coefficients are interpreted as
@math{2*d^3*(4*a+5*b-3)}:
@end ifnottex
+@ifnotinfo
@image{repreal}
+@end ifnotinfo
+@ifinfo
+<PICTURE MISSING>
+@end ifinfo
@cindex radical
This also allows for a better handling of numeric radicals, since
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
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.
+@subsection Configuring a package that uses GiNaC
-Notes:
-
-@itemize @bullet
-
-@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
git://www.ginac.de / ginac.git / blobdiff