<!DOCTYPE Book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<book>
-<title>GiNaC Tutorial</title>
+<title>GiNaC MAJOR_VERSION.MINOR_VERSION Tutorial</title>
<bookinfo>
<subtitle>An open framework for symbolic computation within the C++ programming language</subtitle>
<bookbiblio>
<address><email>Richard.Kreckel@Uni-Mainz.DE</email></address>
</affiliation>
</author>
- <author>
- <surname>Others</surname>
- <affiliation>
- <address><email>whoever@ThEP.Physik.Uni-Mainz.DE</email></address>
- </affiliation>
- </author>
</authorgroup>
</bookbiblio>
</bookinfo>
computation-intense numeric applications, graphical interfaces, etc.)
under one roof.</para>
-<para>This tutorial is intended for the novice user who is new to GiNaC
-but already has some background in C++ programming. However, since a
-hand made documentation like this one is difficult to keep in sync
-with the development the actual documentation is inside the sources in
-the form of comments. That documentation may be parsed by one of the
-many Javadoc-like documentation systems. The generated HTML
-documenatation is included in the distributed sources (subdir
-<literal>doc/reference/</literal>) or can be accessed directly at URL
-<ulink
-url="http://wwwthep.physik.uni-mainz.de/GiNaC/reference/"><literal>http://wwwthep.physik.uni-mainz.de/GiNaC/reference/</literal></ulink>.
+<para>This tutorial is intended for the novice user who is new to
+GiNaC but already has some background in C++ programming. However,
+since a hand made documentation like this one is difficult to keep in
+sync with the development the actual documentation is inside the
+sources in the form of comments. That documentation may be parsed by
+one of the many Javadoc-like documentation systems. If you fail at
+generating it you may access it directly at URL <ulink
+url="http://www.ginac.de/reference/"><literal>http://www.ginac.de/reference/</literal></ulink>.
It is an invaluable resource not only for the advanced user who wishes
to extend the system (or chase bugs) but for everybody who wants to
comprehend the inner workings of GiNaC. This little tutorial on the
other hand only covers the basic things that are unlikely to change in
-the near future.
-</para>
+the near future. </para>
<sect1><title>License</title>
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 concise description of the
-<literal>ginsh</literal> syntax we refer to its accompanied
-man-page.</para>
+<literal>ginsh</literal> syntax we refer to its accompanied man-page.
+Suffice to say that assignments and comparisons in
+<literal>ginsh</literal> are written as they are in C,
+i.e. <literal>=</literal> assigns and <literal>==</literal>
+compares.</para>
<para>It can manipulate arbitrary precision integers in a very fast
way. Rational numbers are automatically converted to fractions of
<literal>0</literal>.)</para>
<para>Linear equation systems can be solved along with basic linear
-algebra manipulations over symbolic expressions. In C++ there is a
-matrix class for this purpose but we can see what it can do using
-<literal>ginsh</literal>'s notation of double brackets to type them in:
+algebra manipulations over symbolic expressions. In C++ GiNaC offers
+a matrix class for this purpose but we can see what it can do using
+<literal>ginsh</literal>'s notation of double brackets to type them
+in:
<screen>
> lsolve(a+x*y==z,x);
y^(-1)*(z-a);
</screen>
</para>
-<para>
-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):
+<para>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):
<screen>
> diff(tan(x),x);
tan(x)^2+1
</screen>
</para>
+<para>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:
+<screen>
+> in=.0254*m;
+0.0254*m
+> lb=.45359237*kg;
+0.45359237*kg
+> 200*lb/in^2;
+140613.91592783185568*kg*m^(-2)
+</screen>
+</para>
+
</sect1>
</chapter>
</screen>
<para>Configuration for a private static GiNaC library with several
components sitting in custom places (site-wide <literal>GCC</literal>
-and private <literal>CLN</literal>):</para>
+and private <literal>CLN</literal>), the compiler pursueded to be
+picky and full assertions switched on:</para>
<screen>
<prompt>$</prompt> export CXX=/usr/local/gnu/bin/c++
<prompt>$</prompt> export CPPFLAGS="${CPPFLAGS} -I${HOME}/include"
-<prompt>$</prompt> export CXXFLAGS="${CXXFLAGS} -ggdb -Wall -ansi -pedantic -O2"
+<prompt>$</prompt> export CXXFLAGS="${CXXFLAGS} -DDO_GINAC_ASSERT -ggdb -Wall -ansi -pedantic -O2"
<prompt>$</prompt> export LDFLAGS="${LDFLAGS} -L${HOME}/lib"
<prompt>$</prompt> ./configure --disable-shared --prefix=${HOME}
</screen>
Here, <literal>e1</literal> will actually be referenced three times
while <literal>e2</literal> will be referenced two times. When the
power of an expression is built, that expression needs not be
-copied. Likewise, since the derivative of a power of an expression can
+copied. Likewise, since the derivative of a power of an expression can
be easily expressed in terms of that expression, no copying of
<literal>e1</literal> is involved when <literal>e3</literal> is
constructed. So, when <literal>e3</literal> is constructed it will
</para>
<para>As a user of GiNaC, you cannot see this mechanism of
-copy-on-write semantics. When you insert an expression into a
-second expression, the result behaves exactly as if the contents of
-the first expression were inserted. But it may be useful to remember
-that this is not what happens. Knowing this will enable you to write
-much more efficient code.</para>
+copy-on-write semantics. When you insert an expression into a second
+expression, the result behaves exactly as if the contents of the first
+expression were inserted. But it may be useful to remember that this
+is not what happens. Knowing this will enable you to write much more
+efficient code. If you still have an uncertain feeling with
+copy-on-write semantics, we recommend you have a look at the
+<emphasis>C++-FAQ lite</emphasis> by Marshall Cline. Chapter 16
+covers this issue and presents an implementation which is pretty close
+to the one in GiNaC. You can find it on the Web at <ulink
+url="http://www.cerfnet.com/~mpcline/c++-faq-lite/"><literal>http://www.cerfnet.com/~mpcline/c++-faq-lite/</literal></ulink>.</para>
<para>So much for expressions. But what exactly are these expressions
handles of? This will be answered in the following sections.</para>
<sect2><title>Digression: Internal representation of products and sums</title>
<para>Although it should be completely transparent for the user of
-GiNaC a short discussion of this topic helps understanding the sources
-and also explains performance to a large degree. Consider the
-symbolic expression <literal>(a+2*b-c)*d</literal>, which could
-naively be represented by a tree of linear containers for addition and
-multiplication together with atomic leaves of symbols and integer
-numbers in this fashion:
+GiNaC a short discussion of this topic helps to understand the sources
+and also explain performance to a large degree. Consider the symbolic
+expression
+<emphasis>2*d<superscript>3</superscript>*(4*a+5*b-3)</emphasis>,
+which could naively be represented by a tree of linear containers for
+addition and multiplication, one container for exponentiation with
+base and exponent and some atomic leaves of symbols and numbers in
+this fashion:
<figure id="repres-naive-id" float="1">
-<title>Naive internal representation of <emphasis>d(a+2*b-c)</emphasis></title>
+<title>Naive internal representation-tree for <emphasis>2*d<superscript>3</superscript>*(4*a+5*b-3)</emphasis></title>
<graphic align="center" fileref="rep_naive.graext" format="GRAEXT"></graphic>
</figure>
However, doing so results in a rather deeply nested tree which will
-quickly become rather slow to manipulate. If we represent the sum
+quickly become inefficient to manipulate. If we represent the sum
instead as a sequence of terms, each having a purely numeric
-coefficient, the tree becomes much more flat.
+multiplicative coefficient and the multiplication as a sequence of
+terms, each having a numeric exponent, the tree becomes much more
+flat.
<figure id="repres-pair-id" float="1">
-<title>Better internal representation of <emphasis>d(a+2*b-c)</emphasis></title>
+<title>Pair-wise internal representation-tree for <emphasis>2*d<superscript>3</superscript>*(4*a+5*b-3)</emphasis></title>
<graphic align="center" fileref="rep_pair.graext" format="GRAEXT"></graphic>
</figure>
-The number <literal>1</literal> under the symbol <literal>d</literal>
-is a hint that multiplication objects can be treated similarly where
-the coeffiecients are interpreted as <emphasis>exponents</emphasis>
+The number <literal>3</literal> above the symbol <literal>d</literal>
+shows that <literal>mul</literal> objects are treated similarly where
+the coefficients are interpreted as <emphasis>exponents</emphasis>
now. Addition of sums of terms or multiplication of products with
-numerical exponents can be made very efficient with a
-pair-representation. Internally, this handling is done by most CAS in
+numerical exponents can be coded to be very efficient with such a
+pair-representation. Internally, this handling is done by many CAS in
this way. It typically speeds up manipulations by an order of
-magnitude. Now it should be clear, why both classes
-<literal>add</literal> and <literal>mul</literal> are derived from the
-same abstract class: the representation is the same, only the
-interpretation differs. </para>
+magnitude. The overall multiplicative factor <literal>2</literal> and
+the additive term <literal>-3</literal> look somewhat cumbersome in
+this representation, however, since they are still carrying a trivial
+exponent and multiplicative factor <literal>1</literal> respectively.
+Within GiNaC, this is avoided by adding a field that carries overall
+numeric coefficient.
+<figure id="repres-real-id" float="1">
+<title>Realistic picture of GiNaC's representation-tree for <emphasis>2*d<superscript>3</superscript>*(4*a+5*b-3)</emphasis></title>
+ <graphic align="center" fileref="rep_real.graext" format="GRAEXT"></graphic>
+</figure>
+This also allows for a better handling of numeric radicals, since
+<literal>sqrt(2)</literal> can now be carried along calculations. Now
+it should be clear, why both classes <literal>add</literal> and
+<literal>mul</literal> are derived from the same abstract class: the
+data representation is the same, only the semantics differs. In the
+class hierarchy, methods for polynomial expansion and such are
+reimplemented for <literal>add</literal> and <literal>mul</literal>,
+but the data structure is inherited from
+<literal>expairseq</literal>.</para>
</sect1>
deal out a unique name. That name may not be suitable for printing
but for internal routines when no output is desired it is often
enough. We'll come across examples of such symbols later in this
-tutorial. </para>
+tutorial.</para>
+
+<para>This implies that the stings passed to symbols at construction
+time may not be used for comparing two of them. It is perfectly
+legitimate to write <literal>symbol x("x"),y("x");</literal> but it is
+likely to lead into trouble. Here, <literal>x</literal> and
+<literal>y</literal> are different symbols and statements like
+<literal>x-y</literal> will not be simplified to zero although the
+output <literal>x-x</literal> looks funny. Such output may also occur
+when there are two different symbols in two scopes, for instance when
+you call a function that declares a symbol with a name already
+existent in a symbol in the calling function. Again, comparing them
+(using <literal>operator==</literal> for instance) will always reveal
+their difference. Watch out, please.</para>
<para>Although symbols can be assigned expressions for internal
reasons, you should not do it (and we are not going to tell you how it
find out more about <literal>CLN</literal>'s internals the reader is
refered to the documentation of that library. Suffice to say that it
is by itself build on top of another library, the GNU Multiple
-Precision library <literal>GMP</literal>, which is a extremely fast
+Precision library <literal>GMP</literal>, which is an extremely fast
library for arbitrary long integers and rationals as well as arbitrary
precision floating point numbers. It is very commonly used by several
popular cryptographic applications. <literal>CLN</literal> extends
Note that all those constructors are <emphasis>explicit</emphasis>
which means you are not allowed to write <literal>numeric
two=2;</literal>. This is because the basic objects to be handled by
-GiNaC are the expressions and we want to keep things simple and wish
-objects like <literal>pow(x,2)</literal> to be handled the same way
-as <literal>pow(x,a)</literal>, which means that we need to allow a
-general expression as base and exponent. Therefore there is an
-implicit construction from a C-integer directly to an expression
-handling a numeric in the first example. 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.
-</para>
+GiNaC are the expressions <literal>ex</literal> and we want to keep
+things simple and wish objects like <literal>pow(x,2)</literal> to be
+handled the same way as <literal>pow(x,a)</literal>, which means that
+we need to allow a general <literal>ex</literal> as base and exponent.
+Therefore there is an implicit constructor from C-integers directly to
+expressions handling 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. </para>
+
+<para>It may be tempting to construct numbers writing <literal>numeric
+r(3/2)</literal>. This would, however, call C's built-in operator
+<literal>/</literal> for integers first and result in a numeric
+holding a plain integer 1. <emphasis>Never use
+</emphasis><literal>/</literal><emphasis> on integers!</emphasis> Use
+the constructor from two integers instead, as shown in the example
+above. Writing <literal>numeric(1)/2</literal> may look funny but
+works also. </para>
<para>We have seen now the distinction between exact numbers and
floating point numbers. Clearly, the user should never have to worry
</screen>
</para>
+<para>It should be clear that objects of class
+<literal>numeric</literal> should be used for constructing numbers or
+for doing arithmetic with them. The objects one deals with most of
+the time are the polymorphic expressions <literal>ex</literal>.</para>
+
<sect2><title>Tests on numbers</title>
<para>Once you have declared some numbers, assigned them to
#include <ginac/ginac.h>
using namespace GiNaC;
+// some very important constants:
+const numeric twentyone(21);
+const numeric ten(10);
+const numeric fife(5);
+
int main()
{
- numeric twentyone(21);
- numeric ten(10);
- numeric answer(21,5);
+ numeric answer = twentyone;
+ answer /= five;
cout << answer.is_integer() << endl; // false, it's 21/5
answer *= ten;
cout << answer.is_integer() << endl; // true, it's 42 now!
}
</programlisting>
</example>
+
Note that the variable <literal>answer</literal> is constructed here
-as an integer but in an intermediate step it holds a rational number
-represented as integer numerator and denominator. When multiplied by
-10, the denominator becomes unity and the result is automatically
-converted to a pure integer again. Internally, the underlying
+as an integer by <literal>numeric</literal>'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. Internally, the underlying
<literal>CLN</literal> is responsible for this behaviour and we refer
the reader to <literal>CLN</literal>'s documentation. Suffice to say
that the same behaviour applies to complex numbers as well as return
converted to real numbers if the imaginary part becomes zero. The
full set of tests that can be applied is listed in the following
table.
+
<informaltable colsep="0" frame="topbot" pgwide="1">
<tgroup cols="2">
<colspec colnum="1" colwidth="1*">
<sect1><title>Built-in Functions</title>
-<para>This section is not here yet</para>
-
+<para>There are quite a number of useful functions built into GiNaC.
+They are all objects of class <literal>function</literal>. They
+accept one or more expressions as arguments and return one expression.
+If the arguments are not numerical, the evaluation of the functions
+may be halted, as it does in the next example:
+<example><title>Evaluation of built-in functions</title>
+<programlisting>
+#include <ginac/ginac.h>
+using namespace GiNaC;
+int main()
+{
+ symbol x("x"), y("y");
+
+ ex foo = x+y/2;
+ cout << "gamma(" << foo << ") -> " << gamma(foo) << endl;
+ ex bar = foo.subs(y==1);
+ cout << "gamma(" << bar << ") -> " << gamma(bar) << endl;
+ ex foobar= bar.subs(x==7);
+ cout << "gamma(" << foobar << ") -> " << gamma(foobar) << endl;
+ // ...
+}
+</programlisting>
+<para>This program will type out two times a function and then an
+expression that may be really useful:
+<screen>
+gamma(x+(1/2)*y) -> gamma(x+(1/2)*y)
+gamma(x+1/2) -> gamma(x+1/2)
+gamma(15/2) -> (135135/128)*Pi^(1/2)
+</screen></para>
+</example>
+Most of these functions can be differentiated, series expanded so on.
+Read the next chapter in order to learn more about this..</para>
</sect1>
instance the expression <literal>1/cosh(x)</literal>. Since the
derivative of <literal>cosh(x)</literal> is <literal>sinh(x)</literal>
and the derivative of <literal>pow(x,-1)</literal> is
-<literal>-pow(x,-2)</literal> GiNaC can readily compute the
+<literal>-pow(x,-2)</literal>, GiNaC can readily compute the
composition. It turns out that the composition is the generating
function for Euler Numbers, i.e. the so called
<emphasis>n</emphasis>th Euler number is the coefficient of
<para>As an instructive application, let us calculate the numerical
value of Archimedes' constant (for which there already exists the
built-in constant <literal>Pi</literal>) using Méchain's
-wonderful formula <literal>Pi==16*atan(1/5)-4*atan(1/239)</literal>.
+mysterious formula <literal>Pi==16*atan(1/5)-4*atan(1/239)</literal>.
We may expand the arcus tangent around <literal>0</literal> and insert
the fractions <literal>1/5</literal> and <literal>1/239</literal>.
But, as we have seen, a series in GiNaC carries an order term with it.
ex mechain_pi(int degr)
{
- symbol x("x");
+ symbol x;
ex pi_expansion = series_to_poly(atan(x).series(x,0,degr));
ex pi_approx = 16*pi_expansion.subs(x==numeric(1,5))
-4*pi_expansion.subs(x==numeric(1,239));
<chapter>
<title>Extending GiNaC</title>
-<para>Longish chapter follows here.</para>
+<para>By reading so far you should have gotten a fairly good
+understanding of GiNaC's design-patterns. From here on you should
+start reading the sources. All we can do now is issue some
+recommendations how to tackle GiNaC's many loose ends in order to
+fulfill everybody's dreams.</para>
+
+<sect1><title>What doesn't belong into GiNaC</title>
+
+<para>First of all, GiNaC's name must be read literally. It is
+designed to be a library for use within C++. The tiny
+<literal>ginsh</literal> accompanying GiNaC makes this even more
+clear: it doesn't even attempt to provide a language. There are no
+loops or conditional expressions in <literal>ginsh</literal>, it is
+merely a window into the library for the programmer to test stuff (or
+to show off). Still, the design of a complete CAS with a language of
+its own, graphical capabilites and all this on top of GiNaC is
+possible and is without doubt a nice project for the future.</para>
+
+<para>There are many built-in functions in GiNaC that do not know how
+to evaluate themselves numerically to a precision declared at runtime
+(using <literal>Digits</literal>). 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
+<literal>CLN</literal> is much better suited.</para>
+
+</sect1>
+
+<sect1><title>Other symbolic functions</title>
+
+<para>The easiest and most instructive way to start with is probably
+to implement your own function. Objects of class
+<literal>function</literal> are 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 C++-functions accepting a number of
+<literal>ex</literal> as arguments and returning one
+<literal>ex</literal>. As an example, if we have a look at a
+simplified implementation of the cosine trigonometric function, we
+first need a function that is called when one wishes to
+<literal>eval</literal> it. It could look something like this:
+
+<programlisting>
+static ex cos_eval_method(ex const & x)
+{
+ // 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();
+}
+</programlisting>
+The last line returns <literal>cos(x)</literal> if we don't know what
+else to do and stops a potential recursive evaluation by saying
+<literal>.hold()</literal>. 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 <literal>numeric</literal>:
+<programlisting>
+static ex cos_evalf_method(ex const & x)
+{
+ return sin(ex_to_numeric(x));
+}
+</programlisting>
+Differentiation will surely turn up and so we need to tell
+<literal>sin</literal> how to differentiate itself:
+<programlisting>
+static ex cos_diff_method(ex const & x, unsigned diff_param)
+{
+ return cos(x);
+}
+</programlisting>
+
+The second parameter is obligatory but uninteresting at this point.
+It is used for correct handling of the product rule only. For Taylor
+expansion, it is enough to know how to differentiate. But if the
+function you want to implement does have a pole somewhere in the
+complex plane, you need to write another method for Laurent expansion
+around that point.</para>
+
+<para>Now that everything has been written for <literal>cos</literal>,
+we need to tell the system about it. This is done by a macro and we
+are not going to descibe how it expands, please consult your
+preprocessor if you are curious:
+<programlisting>
+REGISTER_FUNCTION(cos, cos_eval_method, cos_evalf_method, cos_diff, NULL);
+</programlisting>
+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 needs to be declared somewhere. This may also be done by a
+convenient preprocessor macro:
+<programlisting>
+DECLARE_FUNCTION_1P(cos)
+</programlisting>
+The suffix <literal>_1P</literal> stands for <emphasis>one
+parameter</emphasis>. Of course, this implementation of
+<literal>cos</literal> is very incomplete and lacks several safety
+mechanisms. Please, have a look at the real implementation in GiNaC.
+(By the way: in case you are worrying about all the macros above we
+can assure you that functions are GiNaC's most macro-intense classes.
+We have done our best to avoid them where we can.)</para>
+
+<para>That's it. May the source be with you!</para>
+
+</sect1>
</chapter>
</bookbiblio>
</biblioentry>
+<biblioentry>
+ <bookbiblio>
+ <title>C++ FAQs</title>
+ <authorgroup><author><firstname>Marshall</firstname><surname>Cline</surname></author></authorgroup>
+ <isbn>0-201-58958-3</isbn>
+ <pubdate>1995</pubdate>
+ <publisher><publishername>Addison Wesley</publishername></publisher>
+ </bookbiblio>
+</biblioentry>
+
<biblioentry>
<bookbiblio>
<title>Algorithms for Computer Algebra</title>
git://www.ginac.de / ginac.git / blobdiff