X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=555b2d66e5b14b3cba251507952cecc1f95c5606;hp=72b0dc08af601772f8b2903f9580be797905e7ff;hb=67467d256b44f5e08498ca81c946d9ffaa25d1e2;hpb=1dfc93035f181d451d383e2d9e9d69e1678107eb diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index 72b0dc08..555b2d66 100644 --- a/doc/tutorial/ginac.texi +++ b/doc/tutorial/ginac.texi @@ -15,6 +15,7 @@ @include version.texi +@dircategory Mathematics @direntry * ginac: (ginac). C++ library for symbolic computation. @end direntry @@ -23,7 +24,7 @@ This is a tutorial that documents GiNaC @value{VERSION}, an open framework for symbolic computation within the C++ programming language. -Copyright (C) 1999-2004 Johannes Gutenberg University Mainz, Germany +Copyright (C) 1999-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 @@ -47,12 +48,11 @@ notice identical to this one. @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-2004 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 @@ -79,20 +79,20 @@ framework for symbolic computation within the C++ programming language. @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 @@ -135,7 +135,7 @@ the near future. @section License The GiNaC framework for symbolic computation within the C++ programming -language is Copyright @copyright{} 1999-2004 Johannes Gutenberg +language is Copyright @copyright{} 1999-2008 Johannes Gutenberg University Mainz, Germany. This program is free software; you can redistribute it and/or @@ -150,11 +150,11 @@ General Public License for more details. You should have received a copy of the GNU General Public License along with this program; see the file COPYING. If not, write to the -Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, -MA 02111-1307, USA. +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, +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 @@ -168,7 +168,7 @@ leaves many open questions. @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++ @@ -206,7 +206,7 @@ $ ./hello 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 @@ -256,7 +256,7 @@ the @command{ginsh}, a simple GiNaC interactive shell that provides a 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 @@ -417,6 +417,27 @@ x^(-1)-0.5772156649015328606+(0.9890559953279725555)*x Here we have made use of the @command{ginsh}-command @code{%} to pop the previously evaluated element from @command{ginsh}'s internal stack. +Often, functions don't have roots in closed form. Nevertheless, it's +quite easy to compute a solution numerically, to arbitrary precision: + +@cindex fsolve +@example +> Digits=50: +> fsolve(cos(x)==x,x,0,2); +0.7390851332151606416553120876738734040134117589007574649658 +> f=exp(sin(x))-x: +> X=fsolve(f,x,-10,10); +2.2191071489137460325957851882042901681753665565320678854155 +> subs(f,x==X); +-6.372367644529809108115521591070847222364418220770475144296E-58 +@end example + +Notice how the final result above differs slightly from zero by about +@math{6*10^(-58)}. This is because with 50 decimal digits precision the +root cannot be represented more accurately than @code{X}. Such +inaccuracies are to be expected when computing with finite floating +point values. + If you ever wanted to convert units in C or C++ and found this is cumbersome, here is the solution. Symbolic types can always be used as tags for different types of objects. Converting from wrong units to the @@ -458,14 +479,13 @@ met. First of all, you need to have a C++-compiler adhering to the 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, Bruno Haible's library -CLN is extensively used and needs to be installed on your system. -Please get it either from @uref{ftp://ftp.santafe.edu/pub/gnu/}, from -@uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/, GiNaC's FTP site} or -from @uref{ftp://ftp.ilog.fr/pub/Users/haible/gnu/, Bruno Haible's FTP -site} (it is covered by GPL) and install it prior to trying to install +@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 GiNaC. The configure script checks if it can find it and if it cannot it will refuse to continue. @@ -535,7 +555,7 @@ warning levels. If omitted, it defaults to @option{-g 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 @@ -619,7 +639,7 @@ subdirectories. It is therefore safe to go into any subdirectory @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 @@ -672,9 +692,9 @@ do it by hand since you now know where all the files went during 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 @@ -685,7 +705,7 @@ meta-class for storing all mathematical objects. * 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. @@ -697,11 +717,11 @@ meta-class for storing all mathematical objects. * 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}) @@ -723,7 +743,7 @@ ex MyEx5 = MyEx4 + 1; // similar to above 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} @@ -750,11 +770,11 @@ as @code{std::set}. Unsorted containers such as @code{std::vector<>} and @code{std::list<>} don't pose a problem. A @code{std::vector} 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 @@ -828,7 +848,7 @@ transform expressions, like @code{subs()} or @code{normal()}, automatically 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 @@ -884,9 +904,9 @@ int main() @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 @@ -901,7 +921,12 @@ To get an idea about what kinds of symbolic composites may be built we 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 + +@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 @@ -910,7 +935,7 @@ features. An example is @code{expairseq}, a container for a sequence of 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: @@ -958,7 +983,7 @@ $\sin 2x$ @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) @@ -1000,7 +1025,7 @@ internally such anonymous symbols can be quite useful, however). 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 @@ -1109,7 +1134,7 @@ definitions. 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: @@ -1118,7 +1143,7 @@ symbol x("x", "\\Box"); @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.). @@ -1128,21 +1153,27 @@ Symbols in GiNaC can't be assigned values. If you need to store results of 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 declaring 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) @@ -1310,7 +1341,7 @@ int main() @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. @@ -1328,6 +1359,8 @@ can be applied is listed in the following table. @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()} @@ -1351,6 +1384,8 @@ can be applied is listed in the following table. @end multitable @end cartouche +@page + @subsection Numeric functions The following functions can be applied to @code{numeric} objects and will be @@ -1374,6 +1409,8 @@ evaluated immediately: @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)} @@ -1490,7 +1527,7 @@ rational number will return a floating-point approximation. Both 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) @@ -1505,7 +1542,7 @@ specific number when the method @code{.evalf()} is called. 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 @@ -1520,7 +1557,7 @@ The predefined known constants are: @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 @@ -1591,7 +1628,7 @@ and safe simplifications are carried out like transforming @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) @@ -1756,7 +1793,7 @@ elements with @code{unique()}: @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) @@ -1765,7 +1802,7 @@ elements with @code{unique()}: 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 @@ -1808,7 +1845,7 @@ point number of class @code{numeric} you should call 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) @@ -1834,7 +1871,7 @@ conversion from @code{relational} to @code{bool} takes place. Note, 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) @@ -1880,7 +1917,7 @@ return the integral unevaluated. The function that performs the numerical evaluation, is also available as @example ex adaptivesimpson(const ex & x, const ex & a, const ex & b, const ex & f, -const ex & error) + 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 @@ -1889,13 +1926,13 @@ much work if an expression contains the same integral multiple times, a lookup table is used. If you know that an expression holds an integral, you can get the -integration variable, the left boundary, right boundary and integrant by +integration variable, the left boundary, right boundary and integrand by respectively calling @code{.op(0)}, @code{.op(1)}, @code{.op(2)}, and @code{.op(3)}. Differentiating integrals with respect to variables works as expected. Note that it makes no sense to differentiate an integral with respect to the integration variable. -@node Matrices, Indexed objects, Integrals, Basic Concepts +@node Matrices, Indexed objects, Integrals, Basic concepts @c node-name, next, previous, up @section Matrices @cindex @code{matrix} (class) @@ -1943,7 +1980,8 @@ ex diag_matrix(const lst & l); ex unit_matrix(unsigned x); ex unit_matrix(unsigned r, unsigned c); ex symbolic_matrix(unsigned r, unsigned c, const string & base_name); -ex symbolic_matrix(unsigned r, unsigned c, const string & base_name, const string & tex_base_name); +ex symbolic_matrix(unsigned r, unsigned c, const string & base_name, + const string & tex_base_name); @end example @code{diag_matrix()} constructs a diagonal matrix given the list of diagonal @@ -1952,6 +1990,38 @@ by @samp{c}) unit matrix. And finally, @code{symbolic_matrix} constructs a matrix filled with newly generated symbols made of the specified base name and the position of each element in the matrix. +Matrices often arise by omitting elements of another matrix. For +instance, the submatrix @code{S} of a matrix @code{M} takes a +rectangular block from @code{M}. The reduced matrix @code{R} is defined +by removing one row and one column from a matrix @code{M}. (The +determinant of a reduced matrix is called a @emph{Minor} of @code{M} and +can be used for computing the inverse using Cramer's rule.) + +@cindex @code{sub_matrix()} +@cindex @code{reduced_matrix()} +@example +ex sub_matrix(const matrix&m, unsigned r, unsigned nr, unsigned c, unsigned nc); +ex reduced_matrix(const matrix& m, unsigned r, unsigned c); +@end example + +The function @code{sub_matrix()} takes a row offset @code{r} and a +column offset @code{c} and takes a block of @code{nr} rows and @code{nc} +columns. The function @code{reduced_matrix()} has two integer arguments +that specify which row and column to remove: + +@example +@{ + matrix m(3,3); + m = 11, 12, 13, + 21, 22, 23, + 31, 32, 33; + cout << reduced_matrix(m, 1, 1) << endl; + // -> [[11,13],[31,33]] + cout << sub_matrix(m, 1, 2, 1, 2) << endl; + // -> [[22,23],[32,33]] +@} +@end example + Matrix elements can be accessed and set using the parenthesis (function call) operator: @@ -1999,6 +2069,12 @@ Here are a couple of examples for constructing matrices: @} @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: @@ -2113,7 +2189,8 @@ Matrices may also be inverted using the @code{ex matrix::inverse()} method and linear systems may be solved with: @example -matrix matrix::solve(const matrix & vars, const matrix & rhs, unsigned algo=solve_algo::automatic) const; +matrix matrix::solve(const matrix & vars, const matrix & rhs, + unsigned algo=solve_algo::automatic) const; @end example Assuming the matrix object this method is applied on is an @code{m} @@ -2125,7 +2202,7 @@ contain some of the indeterminates from @code{vars}. If the system is 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 @@ -2164,7 +2241,7 @@ one or more indices. @end itemize -@strong{Note:} when printing expressions, covariant indices and indices +@strong{Please notice:} when printing expressions, covariant indices and indices without variance are denoted @samp{.i} while contravariant indices are denoted @samp{~i}. Dotted indices have a @samp{*} in front of the index value. In the following, we are going to use that notation in the text so @@ -2274,7 +2351,7 @@ bool idx::is_dim_symbolic(); 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: @@ -2365,7 +2442,7 @@ and the same or opposite variance. 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: @@ -2565,6 +2642,47 @@ of a sum are consistent: @} @end example +@cindex @code{expand_dummy_sum()} +A dummy index summation like +@tex +$ a_i b^i$ +@end tex +@ifnottex +a.i b~i +@end ifnottex +can be expanded for indices with numeric +dimensions (e.g. 3) into the explicit sum like +@tex +$a_1b^1+a_2b^2+a_3b^3 $. +@end tex +@ifnottex +a.1 b~1 + a.2 b~2 + a.3 b~3. +@end ifnottex +This is performed by the function + +@example + ex expand_dummy_sum(const ex & e, bool subs_idx = false); +@end example + +which takes an expression @code{e} and returns the expanded sum for all +dummy indices with numeric dimensions. If the parameter @code{subs_idx} +is set to @code{true} then all substitutions are made by @code{idx} class +indices, i.e. without variance. In this case the above sum +@tex +$ a_i b^i$ +@end tex +@ifnottex +a.i b~i +@end ifnottex +will be expanded to +@tex +$a_1b_1+a_2b_2+a_3b_3 $. +@end tex +@ifnottex +a.1 b.1 + a.2 b.2 + a.3 b.3. +@end ifnottex + + @cindex @code{simplify_indexed()} @subsection Simplifying indexed expressions @@ -2580,7 +2698,7 @@ ex ex::simplify_indexed(const scalar_products & sp); 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 @@ -2621,11 +2739,7 @@ arithmetic class, you just pass it to @code{simplify_indexed()}): 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: @@ -2656,7 +2770,7 @@ representation @code{diag(1, 1, 1, ...)}. It is constructed by the function k(symbol("k"), 3), l(symbol("l"), 3); ex e = indexed(A, i, j) * indexed(B, k, l) - * delta_tensor(i, k) * delta_tensor(j, l) << endl; + * delta_tensor(i, k) * delta_tensor(j, l); cout << e.simplify_indexed() << endl; // -> B.i.j*A.i.j @@ -2784,7 +2898,8 @@ dimensions: @example ex epsilon_tensor(const ex & i1, const ex & i2); ex epsilon_tensor(const ex & i1, const ex & i2, const ex & i3); -ex lorentz_eps(const ex & i1, const ex & i2, const ex & i3, const ex & i4, bool pos_sig = false); +ex lorentz_eps(const ex & i1, const ex & i2, const ex & i3, const ex & i4, + bool pos_sig = false); @end example The first two functions create an epsilon tensor in 2 or 3 Euclidean @@ -2859,7 +2974,7 @@ one form for @samp{F} and explicitly multiply it with a matrix representation 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 @@ -2916,10 +3031,8 @@ expressions. Also, non-commutative products in GiNaC are more intelligent 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()} @@ -2935,7 +3048,7 @@ The @code{return_type()} function returns one of three values (defined in 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 @@ -2951,8 +3064,8 @@ expressions in GiNaC: 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: @@ -3014,7 +3127,7 @@ The unity element of a Clifford algebra is constructed by ex dirac_ONE(unsigned char rl = 0); @end example -@strong{Note:} You must always use @code{dirac_ONE()} when referring to +@strong{Please notice:} You must always use @code{dirac_ONE()} when referring to multiples of the unity element, even though it's customary to omit it. E.g. instead of @code{dirac_gamma(mu)*(dirac_slash(q,4)+m)} you have to write @code{dirac_gamma(mu)*(dirac_slash(q,4)+m*dirac_ONE())}. Otherwise, @@ -3084,7 +3197,8 @@ To calculate the trace of an expression containing strings of Dirac gammas you use one of the functions @example -ex dirac_trace(const ex & e, const std::set & rls, const ex & trONE = 4); +ex dirac_trace(const ex & e, const std::set & rls, + const ex & trONE = 4); ex dirac_trace(const ex & e, const lst & rll, const ex & trONE = 4); ex dirac_trace(const ex & e, unsigned char rl = 0, const ex & trONE = 4); @end example @@ -3097,13 +3211,24 @@ element, which defaults to 4. The @code{dirac_trace()} function is a linear functional that is equal to the ordinary matrix trace only in @math{D = 4} dimensions. In particular, the -functional is not cyclic in @math{D != 4} dimensions when acting on +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 -@math{D != 4} dimensions: +@tex $D \ne 4$ +@end tex +@ifnottex +@math{D != 4} +@end ifnottex +dimensions: @example @{ @@ -3171,26 +3296,62 @@ You can use this to compare two expressions or for further simplifications: @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 @samp{e~k} satisfying the identities -@samp{e~i e~j + e~j e~i = B(i, j)} for some symmetric matrix (@code{metric}) -@math{B(i, j)}. Such generators are created by the function +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)$ +@end tex +@ifnottex +e~i e~j + e~j e~i = M(i, j) + M(j, i) +@end ifnottex +for some bilinear form (@code{metric}) +@math{M(i, j)}, which may be non-symmetric (see arXiv:math.QA/9911180) +and contain symbolic entries. Such generators are created by the +function @example - ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0); + ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0); @end example -where @code{mu} should be a @code{varidx} class object indexing the -generators, @code{metr} defines the metric @math{B(i, j)} and can be +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). Note that the call -@code{clifford_unit(mu, minkmetric())} creates something very close to -@code{dirac_gamma(mu)}. The method @code{clifford::get_metric()} returns a -metric defining this Clifford number. +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 +@code{dirac_gamma} have more efficient simplification mechanism. +@cindex @code{clifford::get_metric()} +The method @code{clifford::get_metric()} returns a metric defining this +Clifford number. + +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 + ex e = clifford_unit(mu, indexed(M, sy_symm(), i, j)); +@end example + +since this may yield some further automatic simplifications. Again, for a +metric defined through a @code{matrix} such a symmetry is detected +automatically. Individual generators of a Clifford algebra can be accessed in several ways. For example @@ -3198,20 +3359,26 @@ ways. For example @example @{ ... - varidx nu(symbol("nu"), 3); - matrix M(3, 3) = 1, 0, 0, - 0,-1, 0, - 0, 0, 0; - ex e = clifford_unit(nu, M); - ex e0 = e.subs(nu == 0); - ex e1 = e.subs(nu == 1); - ex e2 = e.subs(nu == 2); + idx i(symbol("i"), 4); + realsymbol s("s"); + ex M = diag_matrix(lst(1, -1, 0, s)); + 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 -will produce three generators of a Clifford algebra with properties -@code{pow(e0, 2) = 1}, @code{pow(e1, 2) = -1} and @code{pow(e2, 2) = 0}. +will produce four anti-commuting generators of a Clifford algebra with properties +@tex +$e_0^2=1 $, $e_1^2=-1$, $e_2^2=0$ and $e_3^2=s$. +@end tex +@ifnottex +@code{pow(e0, 2) = 1}, @code{pow(e1, 2) = -1}, @code{pow(e2, 2) = 0} and +@code{pow(e3, 2) = s}. +@end ifnottex @cindex @code{lst_to_clifford()} A similar effect can be achieved from the function @@ -3219,23 +3386,52 @@ A similar effect can be achieved from the function @example ex lst_to_clifford(const ex & v, const ex & mu, const ex & metr, unsigned char rl = 0); + ex lst_to_clifford(const ex & v, const ex & e); @end example -which converts a list or vector @samp{v = (v~0, v~1, ..., v~n)} into -the Clifford number @samp{v~0 e.0 + v~1 e.1 + ... + v~n e.n} with @samp{e.k} -being created by @code{clifford_unit(mu, metr, rl)}. The previous code -may be rewritten with the help of @code{lst_to_clifford()} as follows +which converts a list or vector +@tex +$v = (v^0, v^1, ..., v^n)$ +@end tex +@ifnottex +@samp{v = (v~0, v~1, ..., v~n)} +@end ifnottex +into the +Clifford number +@tex +$v^0 e_0 + v^1 e_1 + ... + v^n e_n$ +@end tex +@ifnottex +@samp{v~0 e.0 + v~1 e.1 + ... + v~n e.n} +@end ifnottex +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)}. +@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"), 3); - matrix M(3, 3) = 1, 0, 0, - 0,-1, 0, - 0, 0, 0; - ex e0 = lst_to_clifford(lst(1, 0, 0), nu, M); - ex e1 = lst_to_clifford(lst(0, 1, 0), nu, M); - ex e2 = lst_to_clifford(lst(0, 0, 1), nu, M); + 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), 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 @@ -3248,12 +3444,38 @@ There is the inverse function @end example which takes an expression @code{e} and tries to find a list -@samp{v = (v~0, v~1, ..., v~n)} such that @samp{e = v~0 c.0 + v~1 c.1 + ... -+ v~n c.n} with respect to the given Clifford units @code{c} and none of -@samp{v~k} contains the Clifford units @code{c} (of course, this +@tex +$v = (v^0, v^1, ..., v^n)$ +@end tex +@ifnottex +@samp{v = (v~0, v~1, ..., v~n)} +@end ifnottex +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 +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 @samp{v~k} are calculated as -@samp{(e c.k + c.k e)/pow(c.k, 2)}. If @samp{pow(c.k, 2) = 0} for some @samp{k} +(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 +@ifnottex +@samp{(e c.k + c.k e)/pow(c.k, 2)}. If @samp{pow(c.k, 2)} +@end ifnottex +is zero or is not @code{numeric} for some @samp{k} then the method will be automatically changed to symbolic. The same effect is obtained by the assignment (@code{algebraic = false}) in the procedure call. @@ -3280,10 +3502,16 @@ in a product. These functions correspond to the notations @tex $e^*$ @end tex +@ifnottex +e* +@end ifnottex and @tex $\overline{e}$ @end tex +@ifnottex +@code{\bar@{e@}} +@end ifnottex used in Clifford algebra textbooks. @cindex @code{clifford_norm()} @@ -3296,10 +3524,12 @@ The function @cindex @code{clifford_inverse()} calculates the norm of a Clifford number from the expression @tex -$||e||^2 = e\overline{e}$ +$||e||^2 = e\overline{e}$. @end tex -. The inverse of a Clifford expression is returned -by the function +@ifnottex +@code{||e||^2 = e \bar@{e@}} +@end ifnottex + The inverse of a Clifford expression is returned by the function @example ex clifford_inverse(const ex & e); @@ -3307,12 +3537,18 @@ by the function which calculates it as @tex -$e^{-1} = e/||e||^2$ +$e^{-1} = \overline{e}/||e||^2$. @end tex -. If +@ifnottex +@math{e^@{-1@} = \bar@{e@}/||e||^2} +@end ifnottex + If @tex $||e|| = 0$ @end tex +@ifnottex +@math{||e||=0} +@end ifnottex then an exception is raised. @cindex @code{remove_dirac_ONE()} @@ -3328,21 +3564,72 @@ expression by the function The function @code{canonicalize_clifford()} works for a generic Clifford algebra in a similar way as for Dirac gammas. -The last provided function is +The next provided function is @cindex @code{clifford_moebius_map()} @example ex clifford_moebius_map(const ex & a, const ex & b, const ex & c, - const ex & d, const ex & v, const ex & G); + const ex & d, const ex & v, const ex & G, + unsigned char rl = 0); + ex clifford_moebius_map(const ex & M, const ex & v, const ex & G, + unsigned char rl = 0); @end example -It takes a list or vector @code{v} and makes the Moebius -(conformal or linear-fractional) transformation @samp{v -> -(av+b)/(cv+d)} defined by the matrix @samp{[[a, b], [c, d]]}. The last -parameter @code{G} defines the metric of the surrounding -(pseudo-)Euclidean space. The returned value of this function is a list -of components of the resulting vector. +It takes a list or vector @code{v} and makes the Moebius (conformal or +linear-fractional) transformation @samp{v -> (av+b)/(cv+d)} defined by +the matrix @samp{M = [[a, b], [c, d]]}. The parameter @code{G} defines +the metric of the surrounding (pseudo-)Euclidean space. This can be an +indexed object, tensormetric, matrix or a Clifford unit, in the later +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 +@example +char clifford_max_label(const ex & e, bool ignore_ONE = false); +@end example + +can detect a presence of Clifford objects in the expression @code{e}: if +such objects are found it returns the maximal +@code{representation_label} of them, otherwise @code{-1}. The optional +parameter @code{ignore_ONE} indicates if @code{dirac_ONE} objects should +be ignored during the search. + +LaTeX output for Clifford units looks like +@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 +definition of the @code{\clifford} command. For example, the definition +@example + \newcommand@{\clifford@}[1][]@{@} +@end example +typesets all Clifford units identically, while the alternative definition +@example + \newcommand@{\clifford@}[2][]@{\ifcase #1 #2\or \tilde@{#2@} \or \breve@{#2@} \fi@} +@end example +prints units with @code{representation_label=0} as +@tex +$e$, +@end tex +@ifnottex +@code{e}, +@end ifnottex +with @code{representation_label=1} as +@tex +$\tilde{e}$ +@end tex +@ifnottex +@code{\tilde@{e@}} +@end ifnottex + and with @code{representation_label=2} as +@tex +$\breve{e}$. +@end tex +@ifnottex +@code{\breve@{e@}}. +@end ifnottex @cindex @code{color} (class) @subsection Color algebra @@ -3369,7 +3656,7 @@ The unity element of a color algebra is constructed by ex color_ONE(unsigned char rl = 0); @end example -@strong{Note:} You must always use @code{color_ONE()} when referring to +@strong{Please notice:} You must always use @code{color_ONE()} when referring to multiples of the unity element, even though it's customary to omit it. E.g. instead of @code{color_T(a)*(color_T(b)*indexed(X,b)+1)} you have to write @code{color_T(a)*(color_T(b)*indexed(X,b)+color_ONE())}. Otherwise, @@ -3388,6 +3675,11 @@ create the symmetric and antisymmetric structure constants @math{d_abc} and @math{f_abc} which satisfy @math{@{T_a, T_b@} = 1/3 delta_ab + d_abc T_c} and @math{[T_a, T_b] = i f_abc T_c}. +These functions evaluate to their numerical values, +if you supply numeric indices to them. The index values should be in +the range from 1 to 8, not from 0 to 7. This departure from usual conventions +goes along better with the notations used in physical literature. + @cindex @code{color_h()} There's an additional function @@ -3460,7 +3752,7 @@ example: @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 @@ -3496,9 +3788,9 @@ table @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 @@ -3537,27 +3829,26 @@ method on class @code{ex} and sometimes calling a function cannot be avoided. @menu -* Information About Expressions:: -* Numerical Evaluation:: -* Substituting Expressions:: -* Pattern Matching and Advanced Substitutions:: -* Applying a Function on Subexpressions:: -* Visitors and Tree Traversal:: -* Polynomial Arithmetic:: Working with polynomials. -* Rational Expressions:: Working with rational functions. -* Symbolic Differentiation:: -* Series Expansion:: Taylor and Laurent expansion. +* Information about expressions:: +* Numerical evaluation:: +* Substituting expressions:: +* Pattern matching and advanced substitutions:: +* Applying a function on subexpressions:: +* Visitors and tree traversal:: +* Polynomial arithmetic:: Working with polynomials. +* Rational expressions:: Working with rational functions. +* Symbolic differentiation:: +* Series expansion:: Taylor and Laurent expansion. * Symmetrization:: -* Built-in Functions:: List of predefined mathematical functions. +* Built-in functions:: List of predefined mathematical functions. * Multiple polylogarithms:: -* Complex Conjugation:: -* Built-in Functions:: List of predefined mathematical functions. -* Solving Linear Systems of Equations:: -* Input/Output:: Input and output of expressions. +* Complex expressions:: +* Solving linear systems of equations:: +* Input/output:: Input and output of expressions. @end menu -@node Information About Expressions, Numerical Evaluation, Methods and Functions, Methods and Functions +@node Information about expressions, Numerical evaluation, Methods and functions, Methods and functions @c node-name, next, previous, up @section Getting information about expressions @@ -3584,7 +3875,7 @@ unsigned ex::return_type_tinfo() const; When the test made by @code{is_a()} returns true, it is safe to call one of the functions @code{ex_to()}, 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 @@ -3598,7 +3889,7 @@ example, assuming @code{e} is an @code{ex}: @code{is_a(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 @@ -3630,7 +3921,7 @@ table: @item @code{numeric} @tab @dots{}a number (same as @code{is_a(...)}) @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} @@ -3841,7 +4132,8 @@ bool ex::is_zero(); @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 @@ -3914,9 +4206,9 @@ if @code{*this} sorts before @code{other}, and @math{1} if @code{*this} sorts 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. @@ -3954,7 +4246,7 @@ call @code{evalf()} followed by @code{numeric::to_double()}, like this: @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()} @@ -4022,13 +4314,17 @@ contain the same number of elements). Using this form, you would write @end example The optional last argument to @code{subs()} is a combination of -@code{subs_options} flags. There are two options available: +@code{subs_options} flags. There are three options available: @code{subs_options::no_pattern} disables pattern matching, which makes large @code{subs()} operations significantly faster if you are not using patterns. The second option, @code{subs_options::algebraic} enables algebraic substitutions in products and powers. -@ref{Pattern Matching and Advanced Substitutions}, for more information -about patterns and algebraic substitutions. +@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 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. @code{subs()} performs syntactic substitution of any complete algebraic object; it does not try to match sub-expressions as is demonstrated by the @@ -4057,7 +4353,7 @@ A more powerful form of substitution using wildcards is described in the next section. -@node Pattern Matching and Advanced Substitutions, Applying a Function on Subexpressions, Substituting Expressions, Methods and Functions +@node Pattern matching and advanced substitutions, Applying a function on subexpressions, Substituting expressions, Methods and functions @c node-name, next, previous, up @section Pattern matching and advanced substitutions @cindex @code{wildcard} (class) @@ -4094,7 +4390,7 @@ Some examples for patterns: 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 @@ -4191,7 +4487,7 @@ FAIL > 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 @@ -4332,61 +4628,29 @@ The last example would be written in C++ in this way: @} @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 +@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}. -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. +@strong{Note:} this only works for multiplications +and not for locating @code{x+y} within @code{x+y+z}. -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 +@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()} @@ -4529,9 +4793,9 @@ argument. You can not use functions like @samp{diff()}, @samp{op()}, @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()} @@ -4751,10 +5015,26 @@ lst gather_indices(const ex & e) @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()} @@ -4806,9 +5086,11 @@ together with @code{find()}: @example > a=expand((sin(x)+sin(y))*(1+p+q)*(1+d)); -d*p*sin(x)+p*sin(x)+q*d*sin(x)+q*sin(y)+d*sin(x)+q*d*sin(y)+sin(y)+d*sin(y)+q*sin(x)+d*sin(y)*p+sin(x)+sin(y)*p +d*p*sin(x)+p*sin(x)+q*d*sin(x)+q*sin(y)+d*sin(x)+q*d*sin(y)+sin(y)+d*sin(y) ++q*sin(x)+d*sin(y)*p+sin(x)+sin(y)*p > collect(a,@{p,q@}); -d*sin(x)+(d*sin(x)+sin(y)+d*sin(y)+sin(x))*p+(d*sin(x)+sin(y)+d*sin(y)+sin(x))*q+sin(y)+d*sin(y)+sin(x) +d*sin(x)+(d*sin(x)+sin(y)+d*sin(y)+sin(x))*p ++(d*sin(x)+sin(y)+d*sin(y)+sin(x))*q+sin(y)+d*sin(y)+sin(x) > collect(a,find(a,sin($1))); (1+q+d+q*d+d*p+p)*sin(y)+(1+q+d+q*d+d*p+p)*sin(x) > collect(a,@{find(a,sin($1)),p,q@}); @@ -5017,7 +5299,8 @@ The functions @code{gcd()} and @code{lcm()} accept two expressions @code{a} and @code{b} as arguments and return a new expression, their greatest common divisor or least common multiple, respectively. If the polynomials @code{a} and @code{b} are coprime @code{gcd(a,b)} returns 1 -and @code{lcm(a,b)} returns the product of @code{a} and @code{b}. +and @code{lcm(a,b)} returns the product of @code{a} and @code{b}. Note that all +the coefficients must be rationals. @example #include @@ -5106,7 +5389,7 @@ Note also, how factors with the same exponents are not fully factorized 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 @@ -5232,7 +5515,7 @@ The following more useful example will print @samp{sin(x)-cos(x)}: @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 @@ -5298,7 +5581,7 @@ When you run it, it produces the sequence @code{1}, @code{-1}, @code{5}, @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()} @@ -5347,6 +5630,9 @@ value of Archimedes' constant @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 @@ -5411,7 +5697,7 @@ program, it will type out: @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()} @@ -5457,7 +5743,9 @@ almost any kind of object (anything that is @code{subs()}able): @} @end example -@node Built-in Functions, Multiple polylogarithms, Symmetrization, Methods and Functions +@page + +@node Built-in functions, Multiple polylogarithms, Symmetrization, Methods and functions @c node-name, next, previous, up @section Predefined mathematical functions @c @@ -5471,12 +5759,20 @@ GiNaC contains the following predefined mathematical functions: @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()} @@ -5593,7 +5889,7 @@ serious CAS. It is to be expected that future revisions of the C++ 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 @@ -5644,11 +5940,20 @@ ${\rm H\;\!}_{m_1,m_2,\ldots,m_k}(x)$ and @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 @@ -5668,8 +5973,13 @@ ${\rm Li\;\!}_{2,1}(1,1) = \zeta(2,1) = \zeta(3)$, but @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} @@ -5680,11 +5990,17 @@ corresponding arguments @code{a}, it must contain 1 or -1, e.g. @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 @@ -5735,6 +6051,9 @@ unevaluated, e.g. @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. @@ -5750,21 +6069,35 @@ E.Remiddi, J.A.M.Vermaseren, Int.J.Mod.Phys. A15 (2000), pp. 725-754 @cite{Special Values of Multiple Polylogarithms}, J.Borwein, D.Bradley, D.Broadhurst, P.Lisonek, Trans.Amer.Math.Soc. 353/3 (2001), pp. 907-941 -@node Complex Conjugation, Solving Linear Systems of Equations, Multiple polylogarithms, Methods and Functions +@cite{Numerical Evaluation of Multiple Polylogarithms}, +J.Vollinga, S.Weinzierl, hep-ph/0410259 + +@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 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} +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); @@ -5778,15 +6111,16 @@ conjugation gives the expected results: @} @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 @@ -5794,12 +6128,13 @@ matrix operations that comes in handy when a system of linear equations needs to be solved: @example -ex lsolve(const ex &eqns, const ex &symbols, unsigned options=solve_algo::automatic); +ex lsolve(const ex & eqns, const ex & symbols, + unsigned options = solve_algo::automatic); @end example 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, @@ -5824,7 +6159,7 @@ to @code{lsolve()}: it accepts the same parameters as 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 @@ -5873,7 +6208,8 @@ format to the default, use the @code{dflt} manipulator: @example // ... - cout << latex; // all output to cout will be in LaTeX format from now on + cout << latex; // all output to cout will be in LaTeX format from + // now on cout << e << endl; // prints '4.5 i+\frac@{3@}@{2@} x^@{2@}' cout << sin(x/2) << endl; // prints '\sin(\frac@{1@}@{2@} x)' cout << dflt; // revert to default output format @@ -5892,6 +6228,7 @@ you can output to a temporary @code{ostringstream} like this: // ... @end example +@anchor{csrc printing} @cindex @code{csrc} @cindex @code{csrc_float} @cindex @code{csrc_double} @@ -5964,7 +6301,8 @@ For example, the code snippet will print @example - @{(-\ln(\circ))@}+@{(-\gamma_E)@} \circ+@{(\frac@{1@}@{12@} \pi^@{2@})@} \circ^@{2@}+\mathcal@{O@}(\circ^@{3@}) + @{(-\ln(\circ))@}+@{(-\gamma_E)@} \circ+@{(\frac@{1@}@{12@} \pi^@{2@})@} \circ^@{2@} + +\mathcal@{O@}(\circ^@{3@}) @end example @cindex @code{index_dimensions} @@ -6088,6 +6426,127 @@ int main() @} @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) @@ -6264,7 +6723,7 @@ Be warned, however, that the set of properties and their meaning for each 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 @@ -6622,7 +7081,7 @@ code for the @code{psi()} function (@file{inifcns.h} and @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 @@ -6792,7 +7251,8 @@ int main() // our own one set_print_func(my_print_power_as_latex); - // this prints "-1+@{@{(y+x)@}@}\uparrow@{2@}-3 \frac@{@{x@}\uparrow@{3@}@}@{@{y@}\uparrow@{2@}@}" + // this prints "-1+@{@{(y+x)@}@}\uparrow@{2@}-3 \frac@{@{x@}\uparrow@{3@}@}@{@{y@} + // \uparrow@{2@}@}" cout << e << endl; @} @end example @@ -7136,7 +7596,8 @@ inline bool operator==(const sprod_s & lhs, const sprod_s & rhs) inline bool operator<(const sprod_s & lhs, const sprod_s & rhs) @{ - return lhs.left.compare(rhs.left) < 0 ? true : lhs.right.compare(rhs.right) < 0; + return lhs.left.compare(rhs.left) < 0 + ? true : lhs.right.compare(rhs.right) < 0; @} @end example @@ -7302,7 +7763,7 @@ Note that the unarchiving constructor is @code{sprod::structure} and not @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 @@ -7344,9 +7805,8 @@ The RTTI in GiNaC is based on two mechanisms: @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 @@ -7368,7 +7828,8 @@ Now we will start implementing a new class @code{mystring} that allows 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: @@ -7383,17 +7844,6 @@ using namespace std; 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: @@ -7404,8 +7854,8 @@ class mystring : public basic 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; @@ -7440,27 +7890,27 @@ class: @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. -@strong{Note:} This has nothing to do with the (numeric) ordering +@strong{Please notice:} This has nothing to do with the (numeric) ordering relationship expressed by @code{<}, @code{>=} etc (which cannot be defined for non-numeric classes). For example, @code{numeric(1).compare_same_type(numeric(2))} may return +1 even though 1 is clearly smaller than 2. Every GiNaC class @@ -7469,7 +7919,7 @@ objects for which no reasonable algebraic ordering relationship can be 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 @@ -7477,11 +7927,14 @@ which are the two constructors we declared. 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 @@ -7498,7 +7951,7 @@ if you don't plan to use archives, but the minimum required implementation 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); @@ -7516,7 +7969,7 @@ The unarchiving constructor is basically the inverse of the archiving 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); @} @@ -7530,7 +7983,7 @@ by the unarchiving constructor of the @code{basic} class. 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); @} @@ -7549,7 +8002,7 @@ Our @code{compare_same_type()} function uses a provided function to compare 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(other); int cmpval = str.compare(o.str); @@ -7571,8 +8024,10 @@ all relevant member variables. 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 @@ -7586,7 +8041,7 @@ ex e = mystring("Hello, world!"); cout << is_a(e) << endl; // -> 1 (true) -cout << e.bp->class_name() << endl; +cout << ex_to(e).class_name() << endl; // -> mystring @end example @@ -7608,11 +8063,11 @@ class mystring : public basic @{ ... 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 << '\"'; @@ -7711,7 +8166,7 @@ public: ex mystring::eval(int level) const @{ string new_str; - for (int i=0; i= 'A' && c <= 'Z') new_str += tolower(c); @@ -7757,7 +8212,7 @@ required but will make operations with objects of the class more efficient: @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 @@ -7809,8 +8264,30 @@ should become a need. 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 + +@node A comparison with other CAS, Advantages, Adding classes, Top @c node-name, next, previous, up @chapter A Comparison With Other CAS @cindex advocacy @@ -7826,7 +8303,7 @@ disadvantages over these systems. * 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 @@ -7906,7 +8383,7 @@ speed with other CAS. @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 @@ -7941,7 +8418,7 @@ yet ANSI compliant, support all needed features. @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++? @@ -7958,16 +8435,16 @@ Furthermore, the main developers are more familiar with C++ than with 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 @@ -8056,7 +8533,7 @@ Marshall Cline. Chapter 16 covers this issue and presents an 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 @@ -8079,7 +8556,12 @@ addition and multiplication, one container for exponentiation with base and exponent and some atomic leaves of symbols and numbers in this fashion: +@ifnotinfo @image{repnaive} +@end ifnotinfo +@ifinfo + +@end ifinfo @cindex pair-wise representation However, doing so results in a rather deeply nested tree which will @@ -8090,7 +8572,12 @@ spirit we can store the multiplication as a sequence of terms, each having a numeric exponent and a possibly complicated base, the tree becomes much more flat: +@ifnotinfo @image{reppair} +@end ifnotinfo +@ifinfo + +@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 @@ -8112,7 +8599,12 @@ $2d^3 \left( 4a + 5b - 3 \right)$: @math{2*d^3*(4*a+5*b-3)}: @end ifnottex +@ifnotinfo @image{repreal} +@end ifnotinfo +@ifinfo + +@end ifinfo @cindex radical This also allows for a better handling of numeric radicals, since @@ -8124,77 +8616,38 @@ expansion and the like are reimplemented for @code{add} and @code{mul}, 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: @@ -8202,113 +8655,91 @@ 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 +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*}. -@display -editing @file{/etc/ld.so.conf} and running @command{ldconfig} -@end display +The short summary below describes how to do this on a GNU/Linux +system. -or by - -@display -setting the environment variable @env{LD_LIBRARY_PATH}, -@end display - -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 @@ -8327,33 +8758,39 @@ int main() 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. @@ -8361,31 +8798,24 @@ 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 @@ -8397,7 +8827,7 @@ $ make install @end example -@node Bibliography, Concept Index, Example package, Top +@node Bibliography, Concept index, Example package, Top @c node-name, next, previous, up @appendix Bibliography @@ -8442,9 +8872,9 @@ ISBN 3-540-66572-2, 2001, Springer, Heidelberg @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