- added one more sample for our friends at NASA. :-)
[ginac.git] / doc / tutorial / tutorial.sgml.in
index cd8b053b0c465486cc6e784be0673a055e8cc5ac..aa0cb9009d08c3d34a330fe2a95d518ea7a2ee50 100644 (file)
@@ -1,7 +1,7 @@
 <!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>
@@ -50,22 +44,19 @@ together with more established areas of computer science (like
 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>
 
@@ -106,7 +97,8 @@ pointless) bivariate polynomial with some large coefficients:
 <example>
 <title>My first GiNaC program (a bivariate polynomial)</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -123,8 +115,8 @@ int main()
 <para>Assuming the file is called <literal>hello.cc</literal>, on 
 our system we can compile and run it like this:</para>
 <screen>
-<prompt>sysprompt></prompt> c++ hello.cc -o hello -lcln -lginac
-<prompt>sysprompt></prompt> ./hello
+<prompt>$</prompt> c++ hello.cc -o hello -lcln -lginac
+<prompt>$</prompt> ./hello
 355687428096000*x*y+20922789888000*y^2+6402373705728000*x^2
 </screen>
 </example>
@@ -136,7 +128,8 @@ variable.
 <example>
 <title>My second GiNaC program (Hermite polynomials)</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 ex HermitePoly(symbol x, int deg)
 {
@@ -179,8 +172,11 @@ shell that provides a convenient window into GiNaC's capabilities.
 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
@@ -243,9 +239,10 @@ allow one to conclude that <literal>42*Pi</literal> is equal to
 <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);
@@ -277,10 +274,9 @@ polynomials):
 </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
@@ -291,6 +287,20 @@ x^(-1)-1/3*x+Order(x^2)
 </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>
@@ -303,7 +313,7 @@ x^(-1)-1/3*x+Order(x^2)
 easily installed on your system by three steps: configuration, build,
 installation.</para>
 
-<sect1 id="ind123"><title id="CLN-main">Prerequistes</title>
+<sect1><title id="CLN-main">Prerequistes</title>
 
 <para>In order to install GiNaC on your system, some prerequistes need
 to be met.  First of all, you need to have a C++-compiler adhering to
@@ -338,15 +348,10 @@ with the <literal>--help</literal> option.  The most important ones
 will be shortly described in what follows:
 <itemizedlist>
   <listitem>
-    <para><literal>--enable-shared</literal>: When given, this option
-    switches on the build of a shared library, i.e. a
-    <literal>.so</literal>-file. A static libarary (i.e. a
-    <literal>.a</literal>-file) is still built. For this to succeed,
-    GNU libtool needs to be installed on your system. Hence,
-    <literal>configure</literal> checks if it can find an executable
-    <literal>libtool</literal> in the <literal>PATH</literal>. If it
-    doesn't this option is ignored and the default restored, which
-    means that only a static library will be build.</para>
+    <para><literal>--disable-shared</literal>: When given, this option
+    switches off the build of a shared library, i.e. a 
+    <literal>.so</literal>-file.  This may be convenient when developing
+    because it considerably speeds up compilation.</para>
   </listitem>
   <listitem>
     <para><literal>--prefix=</literal><emphasis>PREFIX</emphasis>: The
@@ -367,11 +372,11 @@ will be shortly described in what follows:
     <para><literal>--includedir=</literal><emphasis>INCLUDEDIR</emphasis>:
     Use this option in case you want to have the header files
     installed in some other directory than
-    <emphasis>PREFIX</emphasis><literal>/include/GiNaC/</literal>. For
+    <emphasis>PREFIX</emphasis><literal>/include/ginac/</literal>. For
     instance, if you specify
     <literal>--includedir=/usr/include</literal> you will end up with
     the header files sitting in the directory
-    <literal>/usr/include/GiNaC/</literal>. Note that the subdirectory
+    <literal>/usr/include/ginac/</literal>. Note that the subdirectory
     <literal>GiNaC</literal> 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
@@ -407,18 +412,19 @@ your login shell.)
 configure-script</title> <para>Simple configuration for a site-wide
 GiNaC library assuming everything is in default paths:</para>
 <screen>
-<prompt>sysprompt></prompt> export CXXFLAGS="-Wall -O2"
-<prompt>sysprompt></prompt> ./configure --enable-shared
+<prompt>$</prompt> export CXXFLAGS="-Wall -O2"
+<prompt>$</prompt> ./configure
 </screen>
-<para>Configuration for a private GiNaC library with several
+<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>sysprompt></prompt> export CXX=/usr/local/gnu/bin/c++
-<prompt>sysprompt></prompt> export CPPFLAGS="${CPPFLAGS} -I${HOME}/include"
-<prompt>sysprompt></prompt> export CXXFLAGS="${CXXFLAGS} -ggdb -Wall -ansi -pedantic -O2"
-<prompt>sysprompt></prompt> export LDFLAGS="${LDFLAGS} -L${HOME}/lib"
-<prompt>sysprompt></prompt> ./configure --enable-shared --prefix=${HOME}
+<prompt>$</prompt> export CXX=/usr/local/gnu/bin/c++
+<prompt>$</prompt> export CPPFLAGS="${CPPFLAGS} -I${HOME}/include"
+<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>
 </example>
 </para>
@@ -436,11 +442,11 @@ suite by typing <literal>make check</literal>.  This will compile some
 sample programs, run them and compare the output to reference output.
 Each of the checks should return a message <literal>passed</literal>
 together with the CPU time used for that particular test.  If it does
-not, something went wrong.  This is mostly intended to be a check if
-something was broken during the development, but not a sanity check of
-your system.  Another intent is to allow people to fiddle around with
-optimization.  If <literal>CLN</literal> was installed all right this
-step is unlikely to return any errors.</para>
+not, something went wrong.  This is mostly intended to be a QA-check
+if something was broken during the development, but not a sanity check
+of your system.  Another intent is to allow people to fiddle around
+with optimization.  If <literal>CLN</literal> was installed all right
+this step is unlikely to return any errors.</para>
 
 </sect1>
 
@@ -463,8 +469,8 @@ directories will be created if they don't already exist):
   </listitem>
   <listitem>
     <para>All the header files will be installed into
-    <emphasis>PREFIX</emphasis><literal>/include/GiNaC/</literal> (or
-    <emphasis>INCLUDEDIR</emphasis><literal>/GiNaC/</literal>, if
+    <emphasis>PREFIX</emphasis><literal>/include/ginac/</literal> (or
+    <emphasis>INCLUDEDIR</emphasis><literal>/ginac/</literal>, if
     specified).</para>
   </listitem>
   <listitem>
@@ -543,7 +549,8 @@ the copying takes place as soon as you try to change the second.
 Consider the simple sequence of code:
 <example><title>Simple copy-on-write semantics</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -576,7 +583,8 @@ less trivial example of differentiation using the chain-rule should
 make clear how powerful this can be.  <example><title>Advanced
 copy-on-write semantics</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -595,7 +603,7 @@ int main()
 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
@@ -606,11 +614,16 @@ argument of <literal>cos()</literal> only holds a reference to
 </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>
@@ -653,50 +666,87 @@ two classes and motivate the use of pairs in sums and products here.</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>
 
 <sect1><title>Symbols</title>
 
 <para>Symbols are for symbolic manipulation what atoms are for
-chemistry.  You can declare objects of type symbol as any other object
-simply by saying <literal>symbol x,y;</literal>.  There is, however, a
-catch in here having to do with the fact that C++ is a compiled
-language.  The information about the symbol's name is thrown away by
-the compiler but at a later stage you may want to print expressions
-holding your symbols.  In order to avoid confusion GiNaC's symbols are
-able to know their own name.  This is accomplished by declaring its
-name for output at construction time in the fashion <literal>symbol
-x("x");</literal>.</para>
+chemistry.  You can declare objects of class <literal>symbol</literal>
+as any other object simply by saying <literal>symbol x,y;</literal>.
+There is, however, a catch in here having to do with the fact that C++
+is a compiled language.  The information about the symbol's name is
+thrown away by the compiler but at a later stage you may want to print
+expressions holding your symbols.  In order to avoid confusion GiNaC's
+symbols are able to know their own name.  This is accomplished by
+declaring its name for output at construction time in the fashion
+<literal>symbol x("x");</literal>.  If you declare a symbol using the
+default constructor (i.e. without string-argument) the system will
+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>
+
+<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
@@ -715,7 +765,7 @@ for Numbers or alternatively for Common Lisp Numbers.  In order to
 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
@@ -734,9 +784,10 @@ some useful constants.</para>
 shows the four most important constructors: construction from
 C-integer, construction of fractions from two integers, construction
 from C-float and construction from a string.
-<example><title>Sample C++ program</title>
+<example><title>Construction of numbers</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -753,16 +804,24 @@ int main()
 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
@@ -776,8 +835,8 @@ objects of class numeric that are constructed from then on will be
 stored with a precision matching that number of decimal digits:
 <example><title>Controlling the precision of floating point numbers</title>
 <programlisting> 
-#include
-&lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 void foo()
 {
@@ -809,6 +868,11 @@ in 60 digits:
 </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
@@ -822,14 +886,19 @@ back to invocations of certain CLN functions.)</para>
 with some multiple of its denominator and check what comes out:
 <example><title>Sample test on objects of type numeric</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+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 &lt;&lt; answer.is_integer() &lt;&lt; endl;  // false, it's 21/5
     answer *= ten;
     cout &lt;&lt; answer.is_integer() &lt;&lt; endl;  // true, it's 42 now!
@@ -837,11 +906,13 @@ int main()
 }
 </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
@@ -849,6 +920,7 @@ values of certain functions.  Complex numbers are automatically
 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*">
@@ -963,7 +1035,8 @@ type <literal>add</literal> is called to hold the sum of that
 <literal>mul</literal> object and the number one:
 <example><title>Construction of <literal>add</literal> and <literal>mul</literal> objects</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -1040,9 +1113,39 @@ explicitly, results in the same canonical form.</para>
 
 <sect1><title>Built-in Functions</title>
 
-<para>This chapter 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 &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
+int main()
+{
+    symbol x("x"), y("y");
+    
+    ex foo = x+y/2;
+    cout &lt;&lt; "gamma(" &lt;&lt; foo &lt;&lt; ") -> " &lt;&lt; gamma(foo) &lt;&lt; endl;
+    ex bar = foo.subs(y==1);
+    cout &lt;&lt; "gamma(" &lt;&lt; bar &lt;&lt; ") -> " &lt;&lt; gamma(bar) &lt;&lt; endl;
+    ex foobar= bar.subs(x==7);
+    cout &lt;&lt; "gamma(" &lt;&lt; foobar &lt;&lt; ") -> " &lt;&lt; gamma(foobar) &lt;&lt; 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>
 
@@ -1060,7 +1163,8 @@ it, so you can alternatively call it in a functional way as shown in
 the simple example:
 <example><title>Methods vs. wrapper functions</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -1127,7 +1231,7 @@ a univariate polynomial in one of the variables with the coefficients
 being polynomials in the remaining variables.  The method
 <literal>collect()</literal> accomplishes this task:
 <funcsynopsis>
-  <funcsynopsisinfo>#include &lt;GiNaC/ginac.h></funcsynopsisinfo>
+  <funcsynopsisinfo>#include &lt;ginac/ginac.h></funcsynopsisinfo>
   <funcdef>ex <function>ex::collect</function></funcdef>
   <paramdef>symbol const & <parameter>s</parameter></paramdef>
 </funcsynopsis>
@@ -1135,7 +1239,7 @@ 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
 <funcsynopsis>
-  <funcsynopsisinfo>#include &lt;GiNaC/ginac.h></funcsynopsisinfo>
+  <funcsynopsisinfo>#include &lt;ginac/ginac.h></funcsynopsisinfo>
   <funcdef>int <function>ex::degree</function></funcdef>
   <paramdef>symbol const & <parameter>s</parameter></paramdef>
 </funcsynopsis>
@@ -1150,7 +1254,8 @@ in the following example:
 
 <example><title>Collecting expressions in multivariate polynomials</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -1183,7 +1288,7 @@ not within the user's sphere of influence.</para>
 
 </sect1>
 
-<sect1 id="gcd-main"><title>Polynomial Arithmetic</title>
+<sect1><title>Polynomial Arithmetic</title>
 
 <sect2><title>GCD and LCM</title>
 
@@ -1209,7 +1314,8 @@ and <function>lcm(a,b)</function> returns the product of
 <literal>a</literal> and <literal>b</literal>.
 <example><title>Polynomal GCD/LCM</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -1232,11 +1338,38 @@ int main()
 <sect2><title>The <function>normal</function> method</title>
 
 <para>While in common symbolic code <function>gcd()</function> and
-<function>lcm()</function> are not too heavily used, some basic
-simplification occurs frequently.  Therefore
-<function>.normal()</function>, which provides some basic form of
-simplification, has become a method of class <literal>ex</literal>,
-just like <literal>.expand()</literal>.</para>
+<function>lcm()</function> are not too heavily used, simplification
+occurs frequently.  Therefore <function>.normal()</function>, which
+provides some basic form of simplification, has become a method of
+class <literal>ex</literal>, just like <literal>.expand()</literal>.
+It converts a rational function into an equivalent rational function
+where numererator and denominator are coprime.  This means, it finds
+the GCD of numerator and denominator and cancels it.  If it encounters
+some object which does not belong to the domain of rationals (a
+function for instance), that object is replaced by a temporary symbol.
+This means that both expressions <literal>t1</literal> and
+<literal>t2</literal> are indeed simplified in this little program:
+<example><title>Cancellation of polynomial GCD (with obstacles)</title>
+<programlisting>
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
+
+int main()
+{
+    symbol x("x");
+    ex t1 = (pow(x,2) + 2*x + 1)/(x + 1);
+    ex t2 = (pow(sin(x),2) + 2*sin(x) + 1)/(sin(x) + 1);
+    cout &lt;&lt; "t1 is " &lt;&lt; t1.normal() &lt;&lt; endl;
+    cout &lt;&lt; "t2 is " &lt;&lt; t2.normal() &lt;&lt; endl;
+    // ...
+}
+</programlisting>
+</example>
+
+Of course this works for multivariate polynomials too, so the ratio of
+the sample-polynomials from the section about GCD and LCM above would
+be normalized to <literal>P_a/P_b</literal> =
+<literal>(4*y+z)/(y+3*z)</literal>.</para>
 
 </sect2>
 
@@ -1244,10 +1377,13 @@ just like <literal>.expand()</literal>.</para>
 
 <sect1><title>Symbolic Differentiation</title>
 
-<para>
+<para>GiNaC's objects know how to differentiate themselves.  Thus, a
+polynomial (class <literal>add</literal>) knows that its derivative is
+the sum of the derivatives of all the monomials:
 <example><title>Simple polynomial differentiation</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -1261,20 +1397,48 @@ int main()
 }
 </programlisting>
 </example>
-</para>
-
-<para>
-<example><title>Differentiation with nontrivial functions</title>
+If a second integer parameter <emphasis>n</emphasis> is given the
+<function>diff</function> method returns the <emphasis>n</emphasis>th
+derivative.</para>
+
+<para>If <emphasis>every</emphasis> object and every function is told
+what its derivative is, all derivatives of composed objects can be
+calculated using the chain rule and the product rule.  Consider, for
+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
+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
+<literal>x^n/n!</literal> in the expansion of
+<literal>1/cosh(x)</literal>.  We may use this identity to code a
+function that generates Euler numbers in just three lines:
+<example><title>Differentiation with nontrivial functions: Euler numbers</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
+
+ex EulerNumber(unsigned n)
+{
+    symbol x;
+    ex generator = pow(cosh(x),-1);
+    return generator.diff(x,n).subs(x==0);
+}
 
 int main()
 {
-    // To Be Done...
+    for (unsigned i=0; i&lt;11; i+=2)
+        cout &lt;&lt; EulerNumber(i) &lt;&lt; endl;
+    return 0;
 }
 </programlisting>
 </example>
-</para>
+When you run it, it produces the sequence <literal>1</literal>,
+<literal>-1</literal>, <literal>5</literal>, <literal>-61</literal>,
+<literal>1385</literal>, <literal>-50521</literal>.  We increment the
+loop variable <literal>i</literal> by two since all odd Euler numbers
+vanish anyways.</para>
 
 </sect1>
 
@@ -1287,7 +1451,8 @@ 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:
 <example><title>Series expansion</title>
 <programlisting>
-#include &lt;GiNaC/ginac.h&gt;
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
 
 int main()
 {
@@ -1297,18 +1462,69 @@ int main()
     ex MyExpr2 = 1/(x - pow(x, 2) - pow(x, 3));
     ex MyTailor, MySeries;
     
-    MyTailor = MyExpr1.series(x, numZERO(), 5);
+    MyTailor = MyExpr1.series(x, point, 5);
     cout &lt;&lt; MyExpr1 &lt;&lt; " == " &lt;&lt; MyTailor
          &lt;&lt; " for small " &lt;&lt; x &lt;&lt; endl;
-    MySeries = MyExpr2.series(x, numZERO(), 7);
+    MySeries = MyExpr2.series(x, point, 7);
     cout &lt;&lt; MyExpr2 &lt;&lt; " == " &lt;&lt; MySeries
          &lt;&lt; " for small " &lt;&lt; x &lt;&lt; endl;
-    \\ ...
+    // ...
 }
 </programlisting>
 </example>
 </para>
 
+<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&eacute;chain's
+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.
+The function <literal>series_to_poly</literal> may be used to strip 
+this off:
+<example><title>Series expansion using M&eacute;chain's formula for 
+<literal>Pi</literal></title>
+<programlisting>
+#include &lt;ginac/ginac.h&gt;
+using namespace GiNaC;
+
+ex mechain_pi(int degr)
+{
+    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));
+    return pi_approx;
+}
+
+int main()
+{
+    ex pi_frac;
+    for (int i=2; i&lt;12; i+=2) {
+        pi_frac = mechain_pi(i);
+        cout &lt;&lt; i &lt;&lt; ":\t" &lt;&lt; pi_frac &lt;&lt; endl
+             &lt;&lt; "\t" &lt;&lt; pi_frac.evalf() &lt;&lt; endl;
+    }
+    return 0;
+}
+</programlisting>
+<para>When you run this program, it will type out:</para>
+<screen>
+2:      3804/1195
+        3.1832635983263598326
+4:      5359397032/1706489875
+        3.1405970293260603143
+6:      38279241713339684/12184551018734375
+        3.141621029325034425
+8:      76528487109180192540976/24359780855939418203125
+        3.141591772182177295
+10:     327853873402258685803048818236/104359128170408663038552734375
+        3.1415926824043995174
+</screen>
+</example>
+</para>
+
 </sect1>
 
 </chapter>
@@ -1317,7 +1533,113 @@ int main()
 <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>
 
@@ -1496,6 +1818,16 @@ language.</para>
   </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>
@@ -1534,24 +1866,4 @@ language.</para>
 </bibliodiv>
 </bibliography>
 
-
-<index id="index">
-<title>Index</title>
-
-<indexentry>
-  <primaryie linkends="CLN-main">CLN</primaryie>
-  <secondaryie linkends="ind123">obtaining</secondaryie>
-</indexentry>
-
-<indexentry id="ind-gcd">
-  <primaryie linkends="gcd-main">gcd</primaryie>
-</indexentry>
-
-<indexentry>
-  <primaryie>lcm</primaryie>
-  <seeie linkend="ind-gcd">gcd</seeie>
-</indexentry>
-
-</index>
-
 </book>