- Bumped up version to 0.6.3.

[ginac.git] / doc / tutorial / ginac.texi

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 06e4a8ca9983817d0d3625ec34e2fb1ada7a0aee..28615659a5b71fe6f5f1de956f240730fe924d63 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -684,8 +684,8 @@ ex MyEx4 = sin(x + 2*y) + 3*z + 41; // containing a function
 ex MyEx5 = MyEx4 + 1;               // similar to above
 @end example
 
 ex MyEx5 = MyEx4 + 1;               // similar to above
 @end example
 

-Expressions are handles to other more fundamental objects, that many
-times contain other expressions thus creating a tree of expressions
+Expressions are handles to other more fundamental objects, that often
+contain other expressions thus creating a tree of expressions

 (@xref{Internal Structures}, for particular examples).  Most methods on
 @code{ex} therefore run top-down through such an expression tree.  For
 example, the method @code{has()} scans recursively for occurrences of
 (@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


@@ -707,36 +707,26 @@ 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, numbers,
 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, 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.
+containers of expressions and so on.

 
 @cindex container
 @cindex atom
 To get an idea about what kinds of symbolic composits may be built we
 
 @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
-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:
+have a look at the most important classes in the class hierarchy and
+some of the relations among the classes:

 
 @image{classhierarchy}
 
 
 @image{classhierarchy}
 

-Some of the classes shown here (the ones sitting in white boxes) are
-abstract base classes that are of no interest at all for the user.  They
-are used internally in order to avoid code duplication if two or more
-classes derived from them share certain features.  An example would be
-@code{expairseq}, which is a container for a sequence of pairs each
-consisting of one expression and a number (@code{numeric}).  What
-@emph{is} visible to the user are the derived classes @code{add} and
-@code{mul}, representing sums of terms and products, respectively.
-@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:
+The abstract classes shown here (the ones without drop-shadow) are of no
+interest for the user.  They are used internally in order to avoid code
+duplication if two or more classes derived from them share certain
+features.  An example is @code{expairseq}, a container for a sequence of
+pairs each consisting of one expression and a number (@code{numeric}).
+What @emph{is} visible to the user are the derived classes @code{add}
+and @code{mul}, representing sums and products.  @xref{Internal
+Structures}, where these two classes are described in more detail.  The
+following table shortly summarizes what kinds of mathematical objects
+are stored in the different classes:

 
 @cartouche
 @multitable @columnfractions .22 .78
 
 @cartouche
 @multitable @columnfractions .22 .78


@@ -749,8 +739,8 @@ $\pi$
 @math{Pi}
 @end ifnottex
 @item @code{numeric} @tab All kinds of numbers, @math{42}, @math{7/3*I}, @math{3.14159}@dots{}
 @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{add} @tab Sums like @math{x+y} or @math{a-(2*b)+3}
+@item @code{mul} @tab Products like @math{x*y} or @math{2*a^2*(x+y+z)/b}

 @item @code{power} @tab Exponentials such as @math{x^2}, @math{a^b}, 
 @tex
 $\sqrt{2}$
 @item @code{power} @tab Exponentials such as @math{x^2}, @math{a^b}, 
 @tex
 $\sqrt{2}$


@@ -759,15 +749,14 @@ $\sqrt{2}$
 @code{sqrt(}@math{2}@code{)}
 @end ifnottex
 @dots{}
 @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{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{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{color}, @code{coloridx} @tab Element and index of the @math{SU(3)} Lie-algebra

 @item @code{isospin} @tab Element of the @math{SU(2)} 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
+@item @code{idx} @tab Index of a general tensor object

 @end multitable
 @end cartouche
 
 @end multitable
 @end cartouche
 


@@ -1232,13 +1221,19 @@ 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.
 
 They are created by simply using the C++ operators @code{==}, @code{!=},
 @code{<}, @code{<=}, @code{>} and @code{>=} between two expressions.
 

-@xref{Mathematical 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.  More applications of this class will
-appear throughout the next chapters.
-
+@xref{Mathematical 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 are also used as arguments to the @code{ex::series}
+method, where the left hand side of the relation specifies the variable
+to expand in and the right hand side the expansion point.  They can also
+be used for creating systems of equations that are to be solved for
+unknown variables.  But the most common usage of objects of this class
+is rather inconspicuous in statements of the form @code{if
+(expand(pow(a+b,2))==a*a+2*a*b+b*b) @{...@}}.  Here, an implicit
+conversion from @code{relational} to @code{bool} takes place.  Note,
+however, that @code{==} here does not perform any simplifications, hence
+@code{expand()} must be called explicitly.

 
 
 @node Methods and Functions, Information About Expressions, Relations, Top
 
 
 @node Methods and Functions, Information About Expressions, Relations, Top


@@ -1402,7 +1397,9 @@ table:
 @item @code{crational_polynomial}
 @tab @dots{}a polynomial with (possibly complex) rational coefficients (such as @math{2/3+7/2*I})
 @item @code{rational_function}
 @item @code{crational_polynomial}
 @tab @dots{}a polynomial with (possibly complex) rational coefficients (such as @math{2/3+7/2*I})
 @item @code{rational_function}

-@tab @dots{}a rational function
+@tab @dots{}a rational function (@math{x+y}, @math{z/(x+y)})
+@item @code{algebraic}
+@tab @dots{}an algebraic object (@math{sqrt(2)}, @math{sqrt(x)-1})

 @end multitable
 @end cartouche
 
 @end multitable
 @end cartouche
 


@@ -1474,7 +1471,7 @@ bool ex::is_zero();
 for checking whether one expression is equal to another, or equal to zero,
 respectively.
 
 for checking whether one expression is equal to another, or equal to zero,
 respectively.
 

-@strong{Warning:} You will also find a @code{ex::compare()} method in the
+@strong{Warning:} You will also find an @code{ex::compare()} method in the

 GiNaC header files. This method is however only to be used internally by
 GiNaC to establish a canonical sort order for terms, and using it to compare
 expressions will give very surprising results.
 GiNaC header files. This method is however only to be used internally by
 GiNaC to establish a canonical sort order for terms, and using it to compare
 expressions will give very surprising results.


@@ -2044,6 +2041,8 @@ GiNaC contains the following predefined mathematical functions:
 @tab exponential function
 @item @code{log(x)}
 @tab natural logarithm
 @tab exponential function
 @item @code{log(x)}
 @tab natural logarithm

+@item @code{Li2(x)}
+@tab Dilogarithm

 @item @code{zeta(x)}
 @tab Riemann's zeta function
 @item @code{zeta(n, x)}
 @item @code{zeta(x)}
 @tab Riemann's zeta function
 @item @code{zeta(n, x)}


@@ -2071,10 +2070,17 @@ GiNaC contains the following predefined mathematical functions:
 
 @cindex branch cut
 For functions that have a branch cut in the complex plane GiNaC follows
 
 @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.
+the conventions for C++ as defined in the ANSI standard as far as
+possible.  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 (i.e. continuous with quadrant II).  The inverse
+trigonometric and hyperbolic functions are not defined for complex
+arguments by the C++ standard, however.  Here, we follow the conventions
+used by CLN, which in turn follow the carefully designed definitions
+in the Common Lisp standard.  Hopefully, future revisions of the C++
+standard incorporate these functions in the complex domain in a manner
+compatible with Common Lisp.

 
 
 @node Input/Output, Extending GiNaC, Built-in Functions, Methods and Functions
 
 
 @node Input/Output, Extending GiNaC, Built-in Functions, Methods and Functions


@@ -2344,11 +2350,13 @@ provided by @acronym{CLN} are much better suited.
 @section Symbolic functions
 
 The easiest and most instructive way to start with is probably to
 @section Symbolic functions
 
 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
-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
+implement your own function.  GiNaC's functions are objects of class
+@code{function}.  The preprocessor is then used to convert the function
+names to objects with a corresponding serial number that is used
+internally to identify them.  You usually need not worry about this
+number.  New functions may be inserted into the system via a kind of
+`registry'.  It is your responsibility to care for some functions that
+are called when the user invokes certain methods.  These are usual

 C++-functions accepting a number of @code{ex} as arguments and returning
 one @code{ex}.  As an example, if we have a look at a simplified
 implementation of the cosine trigonometric function, we first need a
 C++-functions accepting a number of @code{ex} as arguments and returning
 one @code{ex}.  As an example, if we have a look at a simplified
 implementation of the cosine trigonometric function, we first need a