This is a tutorial that documents GiNaC @value{VERSION}, an open
framework for symbolic computation within the C++ programming language.
-Copyright (C) 1999 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2000 Johannes Gutenberg University Mainz, Germany
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1999 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2000 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
* 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.
* Bibliography::
* Concept Index::
@end menu
@section License
The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999 Johannes Gutenberg University Mainz,
-Germany.
+language is Copyright @copyright{} 1999-2000 Johannes Gutenberg
+University Mainz, Germany.
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
@section How to use it from within C++
The GiNaC open framework for symbolic computation within the C++ programming
-language does not try to define a language of it's own as conventional
+language does not try to define a language of its own as conventional
CAS do. Instead, it extends the capabilities of C++ by symbolic
manipulations. Here is how to generate and print a simple (and rather
pointless) bivariate polynomial with some large coefficients:
355687428096000*x*y+20922789888000*y^2+6402373705728000*x^2
@end example
+(@xref{Package Tools}, for tools that help you when creating a software
+package that uses GiNaC.)
+
@cindex Hermite polynomial
Next, there is a more meaningful C++ program that calls a function which
generates Hermite polynomials in a specified free variable.
#include <ginac/ginac.h>
using namespace GiNaC;
-ex HermitePoly(symbol x, int deg)
+ex HermitePoly(const symbol & x, int n)
@{
- ex HKer=exp(-pow(x,2));
- // uses the identity H_n(x) == (-1)^n exp(x^2) (d/dx)^n exp(-x^2)
- return normal(pow(-1,deg) * diff(HKer, x, deg) / HKer);
+ ex HKer=exp(-pow(x, 2));
+ // uses the identity H_n(x) == (-1)^n exp(x^2) (d/dx)^n exp(-x^2)
+ return normal(pow(-1, n) * diff(HKer, x, n) / HKer);
@}
int main()
@c node-name, next, previous, up
@section What it can do for you
-@cindex @code{ginsh}
+@cindex @command{ginsh}
After invoking @command{ginsh} one can test and experiment with GiNaC's
features much like in other Computer Algebra Systems except that it does
not provide programming constructs like loops or conditionals. For a
3*y^2+x^2
@end example
-You can differentiate functions and expand them as Taylor or
-Laurent series (the third argument of series is the evaluation point,
-the fourth defines the order):
+You can differentiate functions and expand them as Taylor or Laurent
+series (the third argument of @code{series} is the evaluation point, the
+fourth defines the order):
+@cindex Zeta function
@example
> diff(tan(x),x);
tan(x)^2+1
x-1/6*x^3+Order(x^4)
> series(1/tan(x),x,0,4);
x^(-1)-1/3*x+Order(x^2)
+> series(gamma(x),x,0,3);
+x^(-1)-EulerGamma+(1/12*Pi^2+1/2*EulerGamma^2)*x
++(-1/3*zeta(3)-1/12*Pi^2*EulerGamma-1/6*EulerGamma^3)*x^2+Order(x^3)
+> evalf(");
+x^(-1.0)-0.5772156649015328606+(0.98905599532797255544)*x
+-(0.90747907608088628905)*x^2+Order(x^(3.0))
+> series(gamma(2*sin(x)-2),x,Pi/2,6);
+-(x-1/2*Pi)^(-2)+(-1/12*Pi^2-1/2*EulerGamma^2-1/240)*(x-1/2*Pi)^2
+-EulerGamma-1/12+Order((x-1/2*Pi)^3)
@end example
-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 metric system is therefore easy:
+Here we have made use of the @command{ginsh}-command @code{"} to pop the
+previously evaluated element from @command{ginsh}'s internal stack.
+
+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
+metric system is now easy:
@example
> in=.0254*m;
@c node-name, next, previous, up
@section Prerequisites
-In order to install GiNaC on your system, some prerequisites need
-to be met. First of all, you need to have a C++-compiler adhering to
-the ANSI-standard @cite{ISO/IEC 14882:1998(E)}. We used @acronym{GCC} for
+In order to install GiNaC on your system, some prerequisites need to be
+met. First of all, you need to have a C++-compiler adhering to the
+ANSI-standard @cite{ISO/IEC 14882:1998(E)}. We used @acronym{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
-@acronym{CLN} is extensively used and needs to be installed on your system.
-Please get it from @uref{ftp://ftp.santafe.edu/pub/gnu/} 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 GiNaC.
-The configure script checks if it can find it and if it cannot
+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 @acronym{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
+GiNaC. The configure script checks if it can find it and if it cannot
it will refuse to continue.
@option{--prefix=@var{PREFIX}}: The directory where the compiled library
and headers are installed. It defaults to @file{/usr/local} which means
that the library is installed in the directory @file{/usr/local/lib},
-the header files in @file{/usr/local/include/GiNaC} and the documentation
+the header files in @file{/usr/local/include/ginac} and the documentation
(like this one) into @file{/usr/local/share/doc/GiNaC}.
@item
@file{@var{PREFIX}/include/ginac/}. For instance, if you specify
@option{--includedir=/usr/include} you will end up with the header files
sitting in the directory @file{/usr/include/ginac/}. Note that the
-subdirectory @file{GiNaC} is enforced by this process in order to
+subdirectory @file{ginac} is enforced by this process in order to
keep the header files separated from others. This avoids some
clashes and allows for an easier deinstallation of GiNaC. This ought
to be considered A Good Thing (tm).
And here is a configuration for a private static GiNaC library with
several components sitting in custom places (site-wide @acronym{GCC} and
private @acronym{CLN}). The compiler is pursuaded to be picky and full
-assertions and debugging are switched on:
+assertions and debugging information are switched on:
@example
$ export CXX=/usr/local/gnu/bin/c++
do it by hand since you now know where all the files went during
installation.}.
+
@node Basic Concepts, Expressions, Installing GiNaC, Top
@c node-name, next, previous, up
@chapter Basic Concepts
* Symbols:: Symbolic objects.
* Numbers:: Numerical objects.
* Constants:: Pre-defined constants.
-* Fundamental operations:: The power, add and mul classes.
+* Fundamental containers:: The power, add and mul classes.
* Built-in functions:: Mathematical functions.
+* Relations:: Equality, Inequality and all that.
+* Archiving:: Storing expression libraries in files.
@end menu
Expressions are handles to other more fundamental objects, that many
times 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}
mathematical objects, all of which (except for @code{ex} and some
helpers) are internally derived from one abstract base class called
@code{basic}. You do not have to deal with objects of class
-@code{basic}, instead you'll be dealing with symbols and functions of
-symbols. You'll soon learn in this chapter how many of the functions on
-symbols are really classes. This is because simple symbolic arithmetic
-is not supported by languages like C++ so in a certain way GiNaC has to
-implement its own arithmetic.
-
-To give an idea about what kinds of symbolic composits may be built we
+@code{basic}, instead you'll be dealing with symbols, numbers,
+containers of expressions and so on. You'll soon learn in this chapter
+how many of the functions on symbols are really classes. This is
+because simple symbolic arithmetic is not supported by languages like
+C++ so in a certain way GiNaC has to implement its own arithmetic.
+
+@cindex container
+@cindex atom
+To get an idea about what kinds of symbolic composits may be built we
have a look at the most important classes in the class hierarchy. The
-dashed line symbolizes a "points to" or "handles" relationship while the
-solid lines stand for "inherits from" relationship in the class
+oval classes are atomic ones and the squared classes are containers.
+The dashed line symbolizes a `points to' or `handles' relationship while
+the solid lines stand for `inherits from' relationship in the class
hierarchy:
@image{classhierarchy}
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 of terms and products, respectively.
-We'll come back later to some more details about these two classes and
-motivate the use of pairs in sums and products here.
+@xref{Internal Structures}, where these two classes are described in
+more detail.
+At this point, we only summarize what kind of mathematical objects are
+stored in the different classes in above diagram in order to give you a
+overview:
+
+@cartouche
+@multitable @columnfractions .22 .78
+@item @code{symbol} @tab Algebraic symbols @math{a}, @math{x}, @math{y}@dots{}
+@item @code{constant} @tab Constants like
+@tex
+$\pi$
+@end tex
+@ifnottex
+@math{Pi}
+@end ifnottex
+@item @code{numeric} @tab All kinds of numbers, @math{42}, @math{7/3*I}, @math{3.14159}@dots{}
+@item @code{add} @tab Sums like @math{x+y} or @math{a+(2*b)+3}
+@item @code{mul} @tab Products like @math{x*y} or @math{a*(x+y+z)*b*2}
+@item @code{power} @tab Exponentials such as @math{x^2}, @math{a^b},
+@tex
+$\sqrt{2}$
+@end tex
+@ifnottex
+@code{sqrt(}@math{2}@code{)}
+@end ifnottex
+@dots{}
+@item @code{pseries} @tab Power Series, e.g. @math{x+1/6*x^3+1/120*x^5+O(x^7)}
+@item @code{function} @tab A symbolic function like @math{sin(2*x)}
+@item @code{lst} @tab Lists of expressions [@math{x}, @math{2*y}, @math{3+z}]
+@item @code{matrix} @tab @math{n}x@math{m} matrices of expressions
+@item @code{relational} @tab A relation like the identity @math{x}@code{==}@math{y}
+@item @code{color} @tab Element of the @math{SU(3)} Lie-algebra
+@item @code{isospin} @tab Element of the @math{SU(2)} Lie-algebra
+@item @code{idx} @tab Index of a tensor object
+@item @code{coloridx} @tab Index of a @math{SU(3)} tensor
+@end multitable
+@end cartouche
@node Symbols, Numbers, The Class Hierarchy, Basic Concepts
@c node-name, next, previous, up
@section Symbols
-@cindex Symbols (class @code{symbol})
+@cindex @code{symbol} (class)
+@cindex hierarchy of classes
+@cindex atom
Symbols are for symbolic manipulation what atoms are for chemistry. You
can declare objects of class @code{symbol} as any other object simply by
saying @code{symbol x,y;}. There is, however, a catch in here having to
in the calling function. Again, comparing them (using @code{operator==}
for instance) will always reveal their difference. Watch out, please.
+@cindex @code{subs()}
Although symbols can be assigned expressions for internal reasons, you
should not do it (and we are not going to tell you how it is done). If
you want to replace a symbol with something else in an expression, you
@node Numbers, Constants, Symbols, Basic Concepts
@c node-name, next, previous, up
@section Numbers
-@cindex numbers (class @code{numeric})
+@cindex @code{numeric} (class)
+@cindex GMP
@cindex CLN
+@cindex rational
+@cindex fraction
For storing numerical things, GiNaC uses Bruno Haible's library
@acronym{CLN}. The classes therein serve as foundation classes for
GiNaC. @acronym{CLN} stands for Class Library for Numbers or
numerics at work in most of our examples. This design really becomes
convenient when one declares own functions having more than one
parameter but it forbids using implicit constructors because that would
-lead to ambiguities.
+lead to compile-time ambiguities.
It may be tempting to construct numbers writing @code{numeric r(3/2)}.
This would, however, call C's built-in operator @code{/} for integers
first and result in a numeric holding a plain integer 1. @strong{Never
-use @code{/} on integers!} Use the constructor from two integers
-instead, as shown in the example above. Writing @code{numeric(1)/2} may
-look funny but works also.
+use the operator @code{/} on integers} unless you know exactly what you
+are doing! Use the constructor from two integers instead, as shown in
+the example above. Writing @code{numeric(1)/2} may look funny but works
+also.
@cindex @code{Digits}
@cindex accuracy
We have seen now the distinction between exact numbers and floating
point numbers. Clearly, the user should never have to worry about
-dynamically created exact numbers, since their "exactness" always
-determines how they ought to be handled, i.e. how "long" they are. The
+dynamically created exact numbers, since their `exactness' always
+determines how they ought to be handled, i.e. how `long' they are. The
situation is different for floating point numbers. Their accuracy is
controlled by one @emph{global} variable, called @code{Digits}. (For
those readers who know about Maple: it behaves very much like Maple's
following table.
@cartouche
-@multitable @columnfractions .33 .67
-@item Method @tab Returns true if@dots{}
+@multitable @columnfractions .30 .70
+@item @strong{Method} @tab @strong{Returns true if the object is@dots{}}
@item @code{.is_zero()}
-@tab object is equal to zero
+@tab @dots{}equal to zero
@item @code{.is_positive()}
-@tab object is not complex and greater than 0
+@tab @dots{}not complex and greater than 0
@item @code{.is_integer()}
-@tab object is a (non-complex) integer
+@tab @dots{}a (non-complex) integer
@item @code{.is_pos_integer()}
-@tab object is an integer and greater than 0
+@tab @dots{}an integer and greater than 0
@item @code{.is_nonneg_integer()}
-@tab object is an integer and greater equal 0
+@tab @dots{}an integer and greater equal 0
@item @code{.is_even()}
-@tab object is an even integer
+@tab @dots{}an even integer
@item @code{.is_odd()}
-@tab object is an odd integer
+@tab @dots{}an odd integer
@item @code{.is_prime()}
-@tab object is a prime integer (probabilistic primality test)
+@tab @dots{}a prime integer (probabilistic primality test)
@item @code{.is_rational()}
-@tab object is an exact rational number (integers are rational, too, as are complex extensions like @math{2/3+7/2*I})
+@tab @dots{}an exact rational number (integers are rational, too)
@item @code{.is_real()}
-@tab object is a real integer, rational or float (i.e. is not complex)
+@tab @dots{}a real integer, rational or float (i.e. is not complex)
+@item @code{.is_cinteger()}
+@tab @dots{}a (complex) integer, such as @math{2-3*I}
+@item @code{.is_crational()}
+@tab @dots{}an exact (complex) rational number (such as @math{2/3+7/2*I})
@end multitable
@end cartouche
-@node Constants, Fundamental operations, Numbers, Basic Concepts
+@node Constants, Fundamental containers, Numbers, Basic Concepts
@c node-name, next, previous, up
@section Constants
-@cindex constants (class @code{constant})
-@cindex @code{evalf()}
+@cindex @code{constant} (class)
+@cindex @code{Pi}
+@cindex @code{Catalan}
+@cindex @code{EulerGamma}
+@cindex @code{evalf()}
Constants behave pretty much like symbols except that they return some
specific number when the method @code{.evalf()} is called.
The predefined known constants are:
@cartouche
-@multitable @columnfractions .14 .29 .57
-@item Name @tab Common Name @tab Numerical Value (35 digits)
+@multitable @columnfractions .14 .30 .56
+@item @strong{Name} @tab @strong{Common Name} @tab @strong{Numerical Value (to 35 digits)}
@item @code{Pi}
@tab Archimedes' constant
@tab 3.14159265358979323846264338327950288
@end cartouche
-@node Fundamental operations, Built-in functions, Constants, Basic Concepts
+@node Fundamental containers, Built-in functions, Constants, Basic Concepts
@c node-name, next, previous, up
-@section Fundamental operations: the @code{power}, @code{add} and @code{mul} classes
-@cindex polynomials
+@section Fundamental containers: the @code{power}, @code{add} and @code{mul} classes
+@cindex polynomial
@cindex @code{add}
@cindex @code{mul}
@cindex @code{power}
@}
@end example
+@cindex @code{pow()}
For exponentiation, you have already seen the somewhat clumsy (though C-ish)
statement @code{pow(x,2);} to represent @code{x} squared. This direct
construction is necessary since we cannot safely overload the constructor
has requested @code{2^3}.)
@end itemize
-@cindex @code{ginsh}
+@cindex @command{ginsh}
All effects are contrary to mathematical notation and differ from the
way most other CAS handle exponentiation, therefore overloading @code{^}
is ruled out for GiNaC's C++ part. The situation is different in
canonical form.
-@node Built-in functions, Important Algorithms, Fundamental operations, Basic Concepts
+@node Built-in functions, Relations, Fundamental containers, Basic Concepts
@c node-name, next, previous, up
@section Built-in functions
+@cindex @code{function} (class)
+@cindex trigonometric function
+@cindex hyperbolic function
-There are quite a number of useful functions built into GiNaC. They are
-all objects of class @code{function}. They accept one or more
+There are quite a number of useful functions hard-wired into GiNaC. For
+instance, all trigonometric and hyperbolic functions are implemented.
+They are all objects of class @code{function}. They accept one or more
expressions as arguments and return one expression. If the arguments
are not numerical, the evaluation of the function may be halted, as it
does in the next example:
+@cindex Gamma function
+@cindex @code{subs()}
@example
#include <ginac/ginac.h>
using namespace GiNaC;
gamma(15/2) -> (135135/128)*Pi^(1/2)
@end example
-Most of these functions can be differentiated, series expanded and so
-on. Read the next chapter in order to learn more about this.
+@cindex branch cut
+For functions that have a branch cut in the complex plane GiNaC follows
+the conventions for C++ as defined in the ANSI standard. In particular:
+the natural logarithm (@code{log}) and the square root (@code{sqrt})
+both have their branch cuts running along the negative real axis where
+the points on the axis itself belong to the upper part.
+
+Besides evaluation most of these functions allow differentiation, series
+expansion and so on. Read the next chapter in order to learn more about
+this.
+
+
+@node Relations, Archiving, Built-in functions, Basic Concepts
+@c node-name, next, previous, up
+@section Relations
+@cindex @code{relational} (class)
+
+Sometimes, a relation holding between two expressions must be stored
+somehow. The class @code{relational} is a convenient container for such
+purposes. A relation is by definition a container for two @code{ex} and
+a relation between them that signals equality, inequality and so on.
+They are created by simply using the C++ operators @code{==}, @code{!=},
+@code{<}, @code{<=}, @code{>} and @code{>=} between two expressions.
+
+@xref{Built-in functions}, for examples where various applications of
+the @code{.subs()} method show how objects of class relational are used
+as arguments. There they provide an intuitive syntax for substitutions.
+They can also used for creating systems of equations that are to be
+solved for unknown variables.
+
+
+@node Archiving, Important Algorithms, Relations, Basic Concepts
+@c node-name, next, previous, up
+@section Archiving Expressions
+@cindex I/O
+@cindex @code{archive} (class)
+
+GiNaC allows creating @dfn{archives} of expressions which can be stored
+to or retrieved from files. To create an archive, you declare an object
+of class @code{archive} and archive expressions in it, giving each
+expressions a unique name:
+
+@example
+#include <ginac/ginac.h>
+#include <fstream>
+using namespace GiNaC;
+
+int main()
+@{
+ symbol x("x"), y("y"), z("z");
+
+ ex foo = sin(x + 2*y) + 3*z + 41;
+ ex bar = foo + 1;
+
+ archive a;
+ a.archive_ex(foo, "foo");
+ a.archive_ex(bar, "the second one");
+ // ...
+@end example
+
+The archive can then be written to a file:
+
+@example
+ // ...
+ ofstream out("foobar.gar");
+ out << a;
+ out.close();
+ // ...
+@end example
+
+The file @file{foobar.gar} contains all information that is needed to
+reconstruct the expressions @code{foo} and @code{bar}.
+
+@cindex @command{viewgar}
+The tool @command{viewgar} that comes with GiNaC can be used to view
+the contents of GiNaC archive files:
+
+@example
+$ viewgar foobar.gar
+foo = 41+sin(x+2*y)+3*z
+the second one = 42+sin(x+2*y)+3*z
+@end example
+
+The point of writing archive files is of course that they can later be
+read in again:
+
+@example
+ // ...
+ archive a2;
+ ifstream in("foobar.gar");
+ in >> a2;
+ // ...
+@end example
+
+And the stored expressions can be retrieved by their name:
+
+@example
+ // ...
+ lst syms;
+ syms.append(x); syms.append(y);
+ ex ex1 = a2.unarchive_ex(syms, "foo");
+ ex ex2 = a2.unarchive_ex(syms, "the second one");
-@node Important Algorithms, Polynomial Expansion, Built-in functions, Top
+ cout << ex1 << endl; // prints "41+sin(x+2*y)+3*z"
+ cout << ex2 << endl; // prints "42+sin(x+2*y)+3*z"
+ cout << ex1.subs(x == 2) << endl; // prints "41+sin(2+2*y)+3*z"
+ // ...
+@}
+@end example
+
+Note that you have to supply a list of the symbols which are to be inserted
+in the expressions. Symbols in archives are stored by their name only and
+if you don't specify which symbols you have, unarchiving the expression will
+create new symbols with that name. E.g. if you hadn't included @code{x} in
+the @code{syms} list above, the @code{ex1.subs(x == 2)} statement would
+have had no effect because the @code{x} in @code{ex1} would have been a
+different symbol than the @code{x} which was defined at the beginning of
+the program, altough both would appear as @samp{x} when printed.
+
+
+
+@node Important Algorithms, Polynomial Expansion, Archiving, Top
@c node-name, next, previous, up
@chapter Important Algorithms
-@cindex polynomials
+@cindex polynomial
In this chapter the most important algorithms provided by GiNaC will be
described. Some of them are implemented as functions on expressions,
@}
@end example
+@cindex @code{subs()}
The general rule is that wherever methods accept one or more parameters
(@var{arg1}, @var{arg2}, @dots{}) the order of arguments the function
wrapper accepts is the same but preceded by the object to act on
@code{A:=x^2+3; coeff(A,x,0);} (GiNaC: @code{A=pow(x,2)+3;
coeff(A,x,0);}) it is clear that MapleV is not trying to be consistent
here. Also, users of MuPAD will in most cases feel more comfortable
-with GiNaC's convention. All function wrappers are always implemented
+with GiNaC's convention. All function wrappers are implemented
as simple inline functions which just call the corresponding method and
are only provided for users uncomfortable with OO who are dead set to
-avoid method invocations. Generally, a chain of function wrappers is
-much harder to read than a chain of methods and should therefore be
+avoid method invocations. Generally, nested function wrappers are much
+harder to read than a sequence of methods and should therefore be
avoided if possible. On the other hand, not everything in GiNaC is a
method on class @code{ex} and sometimes calling a function cannot be
avoided.
@code{collect()} accomplishes this task. Here is its declaration:
@example
-ex ex::collect(symbol const & s);
+ex ex::collect(const symbol & s);
@end example
Note that the original polynomial needs to be in expanded form in order
to be able to find the coefficients properly. The range of occuring
coefficients can be checked using the two methods
+@cindex @code{degree()}
+@cindex @code{ldegree()}
@example
-int ex::degree(symbol const & s);
-int ex::ldegree(symbol const & s);
+int ex::degree(const symbol & s);
+int ex::ldegree(const symbol & s);
@end example
where @code{degree()} returns the highest coefficient and
@code{ldegree()} the lowest one. (These two methods work also reliably
on non-expanded input polynomials). An application is illustrated in
-the next example, where a multivariate polynomial is analysed:
+the next example, where a multivariate polynomial is analyzed:
@example
#include <ginac/ginac.h>
@c node-name, next, previous, up
@section Symbolic Differentiation
@cindex differentiation
+@cindex @code{diff()}
@cindex chain rule
@cindex product rule
ex EulerNumber(unsigned n)
@{
symbol x;
- ex generator = pow(cosh(x),-1);
+ const ex generator = pow(cosh(x),-1);
return generator.diff(x,n).subs(x==0);
@}
@node Series Expansion, Extending GiNaC, Symbolic Differentiation, Important Algorithms
@c node-name, next, previous, up
@section Series Expansion
-@cindex series expansion
+@cindex @code{series()}
@cindex Taylor expansion
@cindex Laurent expansion
+@cindex @code{pseries} (class)
Expressions know how to expand themselves as a Taylor series or (more
-generally) a Laurent series. Similar to most conventional Computer
-Algebra Systems, no distinction is made between those two. There is a
-class of its own for storing such series as well as a class for storing
-the order of the series. A sample program could read:
+generally) a Laurent series. As in most conventional Computer Algebra
+Systems, no distinction is made between those two. There is a class of
+its own for storing such series (@code{class pseries}) and a built-in
+function (called @code{Order}) for storing the order term of the series.
+As a consequence, if you want to work with series, i.e. multiply two
+series, you need to call the method @code{ex::series} again to convert
+it to a series object with the usual structure (expansion plus order
+term). A sample application from special relativity could read:
@example
#include <ginac/ginac.h>
int main()
@{
- symbol x("x");
- numeric point(0);
- ex MyExpr1 = sin(x);
- ex MyExpr2 = 1/(x - pow(x, 2) - pow(x, 3));
- ex MyTailor, MySeries;
+ symbol v("v"), c("c");
+
+ ex gamma = 1/sqrt(1 - pow(v/c,2));
+ ex mass_nonrel = gamma.series(v, 0, 10);
+
+ cout << "the relativistic mass increase with v is " << endl
+ << mass_nonrel << endl;
+
+ cout << "the inverse square of this series is " << endl
+ << pow(mass_nonrel,-2).series(v, 0, 10) << endl;
- MyTailor = MyExpr1.series(x, point, 5);
- cout << MyExpr1 << " == " << MyTailor
- << " for small " << x << endl;
- MySeries = MyExpr2.series(x, point, 7);
- cout << MyExpr2 << " == " << MySeries
- << " for small " << x << endl;
// ...
@}
@end example
+Only calling the series method makes the last output simplify to
+@math{1-v^2/c^2+O(v^10)}, without that call we would just have a long
+series raised to the power @math{-2}.
+
@cindex M@'echain's formula
-As an instructive application, let us calculate the numerical value of
-Archimedes' constant
+As another instructive application, let us calculate the numerical
+value of Archimedes' constant
@tex
$\pi$
@end tex
@c node-name, next, previous, up
@section What doesn't belong into GiNaC
-@cindex @code{ginsh}
+@cindex @command{ginsh}
First of all, GiNaC's name must be read literally. It is designed to be
a library for use within C++. The tiny @command{ginsh} accompanying
GiNaC makes this even more clear: it doesn't even attempt to provide a
(using @code{Digits}). Some may be evaluated at certain points, but not
generally. This ought to be fixed. However, doing numerical
computations with GiNaC's quite abstract classes is doomed to be
-inefficient. For this purpose, the underlying bignum-package
-@acronym{CLN} is much better suited.
+inefficient. For this purpose, the underlying foundation classes
+provided by @acronym{CLN} are much better suited.
@node Symbolic functions, A Comparison With Other CAS, What does not belong into GiNaC, Extending GiNaC
The easiest and most instructive way to start with is probably to
implement your own function. Objects of class @code{function} are
-inserted into the system via a kind of "registry". They get a serial
+inserted into the system via a kind of `registry'. They get a serial
number that is used internally to identify them but you usually need not
worry about this. What you have to care for are functions that are
called when the user invokes certain methods. These are usual
look something like this:
@example
-static ex cos_eval_method(ex const & x)
+static ex cos_eval_method(const ex & x)
@{
- // if x%2*Pi return 1
- // if x%Pi return -1
- // if x%Pi/2 return 0
+ // if (!x%(2*Pi)) return 1
+ // if (!x%Pi) return -1
+ // if (!x%Pi/2) return 0
// care for other cases...
return cos(x).hold();
@}
@end example
+@cindex @code{hold()}
+@cindex evaluation
The last line returns @code{cos(x)} if we don't know what else to do and
-stops a potential recursive evaluation by saying @code{.hold()}. We
+stops a potential recursive evaluation by saying @code{.hold()}, which
+sets a flag to the expression signalint that it has been evaluated. We
should also implement a method for numerical evaluation and since we are
lazy we sweep the problem under the rug by calling someone else's
function that does so, in this case the one in class @code{numeric}:
@example
-static ex cos_evalf_method(ex const & x)
+static ex cos_evalf(const ex & x)
@{
- return sin(ex_to_numeric(x));
+ return cos(ex_to_numeric(x));
@}
@end example
-Differentiation will surely turn up and so we need to tell
-@code{sin} how to differentiate itself:
+Differentiation will surely turn up and so we need to tell @code{cos}
+what the first derivative is (higher derivatives (@code{.diff(x,3)} for
+instance are then handled automatically by @code{basic::diff} and
+@code{ex::diff}):
@example
-static ex cos_diff_method(ex const & x, unsigned diff_param)
+static ex cos_derive(const ex & x, unsigned diff_param)
@{
- return cos(x);
+ return -sin(x);
@}
@end example
are curious:
@example
-REGISTER_FUNCTION(cos, cos_eval_method, cos_evalf_method, cos_diff, NULL);
+REGISTER_FUNCTION(cos, cos_eval, cos_evalf, cos_derive, NULL);
@end example
-The first argument is the function's name, the second, third and fourth
-bind the corresponding methods to this objects and the fifth is a slot
-for inserting a method for series expansion. Also, the new function
+The first argument is the function's name used for calling it and for
+output. The second, third and fourth bind the corresponding methods to
+this objects and the fifth is a slot for inserting a method for series
+expansion. (If set to @code{NULL} it defaults to simple Taylor
+expansion, which is correct if there are no poles involved. The way
+GiNaC handles poles in case there are any is best understood by studying
+one of the examples, like the Gamma function for instance. In essence
+the function first checks if there is a pole at the evaluation point and
+falls back to Taylor expansion if there isn't. Then, the pole is
+regularized by some suitable transformation.) Also, the new function
needs to be declared somewhere. This may also be done by a convenient
preprocessor macro:
That's it. May the source be with you!
-@node A Comparison With Other CAS, Internal Structures, Symbolic functions, Top
+@node A Comparison With Other CAS, Advantages, Symbolic functions, Top
@c node-name, next, previous, up
@chapter A Comparison With Other CAS
@cindex advocacy
@emph{Mathematica} or @emph{Reduce}, where it has advantages and
disadvantages over these systems.
+@menu
+* Advantages:: Stengths of the GiNaC approach.
+* Disadvantages:: Weaknesses of the GiNaC approach.
+* Why C++?:: Attractiveness of C++.
+@end menu
-@heading Advantages
+@node Advantages, Disadvantages, A Comparison With Other CAS, A Comparison With Other CAS
+@c node-name, next, previous, up
+@section Advantages
GiNaC has several advantages over traditional Computer
Algebra Systems, like
@item
familiar language: all common CAS implement their own proprietary
grammar which you have to learn first (and maybe learn again when your
-vendor chooses to "enhance" it). With GiNaC you can write your program
+vendor decides to `enhance' it). With GiNaC you can write your program
in common C++, which is standardized.
+@cindex STL
@item
structured data types: you can build up structured data types using
@code{struct}s or @code{class}es together with STL features instead of
are part of your program. You can easily call third party libraries,
e.g. for numerical evaluation or graphical interaction. All other
approaches are much more cumbersome: they range from simply ignoring the
-problem (i.e. @emph{Maple}) to providing a method for "embedding" the
+problem (i.e. @emph{Maple}) to providing a method for `embedding' the
system (i.e. @emph{Yacas}).
@item
@end itemize
-@heading Disadvantages
+@node Disadvantages, Why C++?, Advantages, A Comparison With Other CAS
+@c node-name, next, previous, up
+@section Disadvantages
Of course it also has some disadvantages:
@item
not interactive: GiNaC programs have to be written in an editor,
-compiled and executed. You cannot play with expressions interactively.
+compiled and executed. You cannot play with expressions interactively.
However, such an extension is not inherently forbidden by design. In
-fact, two interactive interfaces are possible: First, a simple shell
-that exposes GiNaC's types to a command line can readily be written (and
-has been written) and second, as a more consistent approach we plan an
-integration with the @acronym{CINT} C++ interpreter.
+fact, two interactive interfaces are possible: First, a shell that
+exposes GiNaC's types to a command line can readily be written (the tiny
+@command{ginsh} that is part of the distribution being an example).
+Second, as a more consistent approach, an interactive interface to the
+@acronym{CINT} C++ interpreter is under development (called
+@acronym{GiNaC-cint}) that will allow an interactive interface
+consistent with the C++ language.
@item
advanced features: GiNaC cannot compete with a program like
@emph{Reduce} which exists for more than 30 years now or @emph{Maple}
which grows since 1981 by the work of dozens of programmers, with
-respect to mathematical features. Integration, factorization,
+respect to mathematical features. Integration, factorization,
non-trivial simplifications, limits etc. are missing in GiNaC (and are
not planned for the near future).
compiler), the currently used version of the CLN library (fast large
integer and arbitrary precision arithmetics) can be compiled only on
systems with a recently new C++ compiler from the GNU Compiler
-Collection (@acronym{GCC}). GiNaC uses recent language features like
-explicit constructors, mutable members, RTTI, @code{dynamic_cast}s and
-STL, so ANSI compliance is meant literally. Recent @acronym{GCC}
-versions starting at 2.95, although itself not yet ANSI compliant,
-support all needed features.
+Collection (@acronym{GCC}).@footnote{This is because CLN uses
+PROVIDE/REQUIRE like macros to let the compiler gather all static
+initializations, which works for GNU C++ only.} GiNaC uses recent
+language features like explicit constructors, mutable members, RTTI,
+@code{dynamic_cast}s and STL, so ANSI compliance is meant literally.
+Recent @acronym{GCC} versions starting at 2.95, although itself not yet
+ANSI compliant, support all needed features.
@end itemize
-@heading Why C++?
+@node Why C++?, Internal Structures, Disadvantages, A Comparison With Other CAS
+@c node-name, next, previous, up
+@section Why C++?
Why did we choose to implement GiNaC in C++ instead of Java or any other
-language? C++ is not perfect: type checking is not strict (casting is
+language? C++ is not perfect: type checking is not strict (casting is
possible), separation between interface and implementation is not
complete, object oriented design is not enforced. The main reason is
-the often scolded feature of operator overloading in C++. While it may
+the often scolded feature of operator overloading in C++. While it may
be true that operating on classes with a @code{+} operator is rarely
-meaningful, it is perfectly suited for algebraic expressions. Writing
+meaningful, it is perfectly suited for algebraic expressions. Writing
@math{3x+5y} as @code{3*x+5*y} instead of
-@code{x.times(3).plus(y.times(5))} looks much more natural. Furthermore,
-the main developers are more familiar with C++ than with any other
-programming language.
+@code{x.times(3).plus(y.times(5))} looks much more natural.
+Furthermore, the main developers are more familiar with C++ than with
+any other programming language.
-@node Internal Structures, Expressions are reference counted, A Comparison With Other CAS, Top
+@node Internal Structures, Expressions are reference counted, Why C++? , Top
@c node-name, next, previous, up
@appendix Internal Structures
implementation which is pretty close to the one in GiNaC.
-@node Internal representation of products and sums, Bibliography, 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
@cindex pair-wise representation
However, doing so results in a rather deeply nested tree which will
quickly become inefficient to manipulate. We can improve on this by
-representing the sum instead as a sequence of terms, each one being a
-pair of a purely numeric multiplicative coefficient and its rest. In
-the same spirit we can store the multiplication as a sequence of terms,
-each having a numeric exponent and a possibly complicated base, the tree
+representing the sum as a sequence of terms, each one being a pair of a
+purely numeric multiplicative coefficient and its rest. In the same
+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:
@image{reppair}
coefficient. This results in the realistic picture of internal
representation for
@tex
-$2d^3 \left( 4a + 5b - 3 \right)$
+$2d^3 \left( 4a + 5b - 3 \right)$:
@end tex
@ifnottex
-@math{2*d^3*(4*a+5*b-3)}
+@math{2*d^3*(4*a+5*b-3)}:
@end ifnottex
-:
@image{repreal}
+@cindex radical
This also allows for a better handling of numeric radicals, since
@code{sqrt(2)} can now be carried along calculations. Now it should be
clear, why both classes @code{add} and @code{mul} are derived from the
but the data structure is inherited from @code{expairseq}.
+@node Package Tools, ginac-config, Internal representation of products and sums, Top
+@c node-name, next, previous, up
+@appendix Package Tools
+
+If you are creating a software package that uses the GiNaC library,
+setting the correct command line options for the compiler and linker
+can be difficult. GiNaC includes two tools to make this process easier.
+
+@menu
+* ginac-config:: A shell script to detect compiler and linker flags.
+* AM_PATH_GINAC:: Macro for GNU automake.
+@end menu
+
+
+@node ginac-config, AM_PATH_GINAC, Package Tools, Package Tools
+@c node-name, next, previous, up
+@section @command{ginac-config}
+@cindex ginac-config
+
+@command{ginac-config} is a shell script that you can use to determine
+the compiler and linker command line options required to compile and
+link a program with the GiNaC library.
+
+@command{ginac-config} takes the following flags:
+
+@table @samp
+@item --version
+Prints out the version of GiNaC installed.
+@item --cppflags
+Prints '-I' flags pointing to the installed header files.
+@item --libs
+Prints out the linker flags necessary to link a program against GiNaC.
+@item --prefix[=@var{PREFIX}]
+If @var{PREFIX} is specified, overrides the configured value of @env{$prefix}.
+(And of exec-prefix, unless @code{--exec-prefix} is also specified)
+Otherwise, prints out the configured value of @env{$prefix}.
+@item --exec-prefix[=@var{PREFIX}]
+If @var{PREFIX} is specified, overrides the configured value of @env{$exec_prefix}.
+Otherwise, prints out the configured value of @env{$exec_prefix}.
+@end table
+
+Typically, @command{ginac-config} will be used within a configure
+script, as described below. It, however, can also be used directly from
+the command line using backquotes to compile a simple program. For
+example:
+
+@example
+c++ -o simple `ginac-config --cppflags` simple.cpp `ginac-config --libs`
+@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++
+@end example
+
+Not only is the form using @command{ginac-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.
+
+@example
+AM_PATH_GINAC([@var{MINIMUM-VERSION}, [@var{ACTION-IF-FOUND} [, @var{ACTION-IF-NOT-FOUND}]]])
+@end example
+
+This macro:
+
+@itemize @bullet
+
+@item
+Determines the location of GiNaC using @command{ginac-config}, which is
+either found in the user's path, or from the environment variable
+@env{GINACLIB_CONFIG}.
+
+@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)
+
+@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
+@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}.
+
+@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.
+@end menu
+
+
+@node Configure script options, Example package, AM_PATH_GINAC, AM_PATH_GINAC
+@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
+
+@item
+The directory where the GiNaC libraries are installed needs
+to be found by your system's dynamic linker.
+
+This is generally done by
+
+@display
+editing @file{/etc/ld.so.conf} and running @command{ldconfig}
+@end display
+
+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:
+
+@example
+LDFLAGS=-R/home/cbauer/lib ./configure
+@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
+
+@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.
+
+@end itemize
+
+Advanced note:
+
+@itemize @bullet
+@item
+configure flags
+
+@example
+--with-ginac-prefix=@var{PREFIX}
+--with-ginac-exec-prefix=@var{PREFIX}
+@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
+
+
+@node Example package, Bibliography, Configure script options, AM_PATH_GINAC
+@c node-name, next, previous, up
+@subsection Example of a package using @samp{AM_PATH_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}:
+
+@example
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+int main(void)
+@{
+ symbol x("x");
+ ex a = sin(x);
+ cout << "Derivative of " << a << " is " << a.diff(x) << endl;
+ return 0;
+@}
+@end example
+
+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
+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)
+
+AC_PROG_CXX
+AC_PROG_INSTALL
+AC_LANG_CPLUSPLUS
+
+AM_PATH_GINAC(0.4.0, [
+ LIBS="$LIBS $GINACLIB_LIBS"
+ CPPFLAGS="$CFLAGS $GINACLIB_CPPFLAGS"
+], AC_MSG_ERROR([need to have GiNaC installed]))
+
+AC_OUTPUT(Makefile)
+@end example
+
+The only command in this which is not standard for automake
+is the @samp{AM_PATH_GINAC} macro.
+
+That command does the following:
+
+@display
+If a GiNaC version greater than 0.4.0 is found, adds @env{$GINACLIB_LIBS} to
+@env{$LIBS} and @env{$GINACLIB_CPPFLAGS} to @env{$CPPFLAGS}. Otherwise, dies
+with the error message `need to have GiNaC installed'
+@end display
+
+And the @file{Makefile.am}, which will be used to build the Makefile.
+
+@example
+## Process this file with automake to produce Makefile.in
+bin_PROGRAMS = simple
+simple_SOURCES = simple.cpp
+@end example
+
+This @file{Makefile.am}, says that we are building a single executable,
+from a single sourcefile @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}.
+
+To try this example out, create a new directory and add the three
+files above to it.
+
+Now execute the following commands:
+
+@example
+$ automake --add-missing
+$ aclocal
+$ autoconf
+@end example
+
+You now have a package that can be built in the normal fashion
+
+@example
+$ ./configure
+$ make
+$ make install
+@end example
+
-@node Bibliography, Concept Index, Internal representation of products and sums, Top
+@node Bibliography, Concept Index, Example package, Top
@c node-name, next, previous, up
@appendix Bibliography
git://www.ginac.de / ginac.git / blobdiff