From ded2e4a35496e9a3c6c540965f53e2acbe11fa15 Mon Sep 17 00:00:00 2001
From: Christian Bauer
Date: Wed, 19 Feb 2003 22:55:25 +0000
Subject: [PATCH] added a section about automatic evaluation

doc/tutorial/ginac.texi  208 ++++++++++++++++++++++++++
1 file changed, 134 insertions(+), 74 deletions()
diff git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 80000ff9..022a9a27 100644
 a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ 672,12 +672,13 @@ metaclass for storing all mathematical objects.
@menu
* Expressions:: The fundamental GiNaC class.
* The Class Hierarchy:: Overview of GiNaC's classes.
+* Automatic evaluation:: Evaluation and canonicalization.
* Error handling:: How the library reports errors.
+* The Class Hierarchy:: Overview of GiNaC's classes.
* Symbols:: Symbolic objects.
* Numbers:: Numerical objects.
* Constants:: Predefined constants.
* Fundamental containers:: The power, add and mul classes.
+* Fundamental containers:: Sums, products and powers.
* Lists:: Lists of expressions.
* Mathematical functions:: Mathematical functions.
* Relations:: Equality, Inequality and all that.
@@ 687,7 +688,7 @@ metaclass for storing all mathematical objects.
@end menu
@node Expressions, The Class Hierarchy, Basic Concepts, Basic Concepts
+@node Expressions, Automatic evaluation, Basic Concepts, Basic Concepts
@c nodename, next, previous, up
@section Expressions
@cindex expression (class @code{ex})
@@ 721,7 +722,131 @@ hierarchy and describe the classes of objects that are handled by
@code{ex}.
@node The Class Hierarchy, Error handling, Expressions, Basic Concepts
+@node Automatic evaluation, Error handling, Expressions, Basic Concepts
+@c nodename, next, previous, up
+@section Automatic evaluation and canonicalization of expressions
+@cindex evaluation
+
+GiNaC performs some automatic transformations on expressions, to simplify
+them and put them into a canonical form. Some examples:
+
+@example
+ex MyEx1 = 2*x  1 + x; // 3*x1
+ex MyEx2 = x  x; // 0
+ex MyEx3 = cos(2*Pi); // 1
+ex MyEx4 = x*y/x; // y
+@end example
+
+This behavior is usually referred to as @dfn{automatic} or @dfn{anonymous
+evaluation}. GiNaC only performs transformations that are
+
+@itemize @bullet
+@item
+at most of complexity @math{O(n log n)}
+@item
+algebraically correct, possibly except for a set of measure zero (e.g.
+@math{x/x} is transformed to @math{1} although this is incorrect for @math{x=0})
+@end itemize
+
+There are two types of automatic transformations in GiNaC that may not
+behave in an entirely obvious way at first glance:
+
+@itemize
+@item
+The terms of sums and products (and some other things like the arguments of
+symmetric functions, the indices of symmetric tensors etc.) are reordered
+into a canonical form that is deterministic, but not lexicographical or in
+any other way easily guessable (it almost always depends on the number and
+order of the symbols you define). However, constructing the same expression
+twice, either implicitly or explicitly, will always result in the same
+canonical form.
+@item
+Expressions of the form 'number times sum' are automatically expanded (this
+has to do with GiNaC's internal representation of sums and products). For
+example
+@example
+ex MyEx5 = 2*(x + y); // 2*x+2*y
+ex MyEx6 = z*(x + y); // z*(x+y)
+@end example
+@end itemize
+
+The general rule is that when you construct expressions, GiNaC automatically
+creates them in canonical form, which might differ from the form you typed in
+your program. This may create some awkward looking output (@samp{y+x} instead
+of @samp{yx}) but allows for more efficient operation and usually yields
+some immediate simplifications.
+
+@cindex @code{eval()}
+Internally, the anonymous evaluator in GiNaC is implemented by the methods
+
+@example
+ex ex::eval(int level = 0) const;
+ex basic::eval(int level = 0) const;
+@end example
+
+but unless you are extending GiNaC with your own classes or functions, there
+should never be any reason to call them explicitly. All GiNaC methods that
+transform expressions, like @code{subs()} or @code{normal()}, automatically
+reevaluate their results.
+
+
+@node Error handling, The Class Hierarchy, Automatic evaluation, Basic Concepts
+@c nodename, next, previous, up
+@section Error handling
+@cindex exceptions
+@cindex @code{pole_error} (class)
+
+GiNaC reports runtime errors by throwing C++ exceptions. All exceptions
+generated by GiNaC are subclassed from the standard @code{exception} class
+defined in the @file{} header. In addition to the predefined
+@code{logic_error}, @code{domain_error}, @code{out_of_range},
+@code{invalid_argument}, @code{runtime_error}, @code{range_error} and
+@code{overflow_error} types, GiNaC also defines a @code{pole_error}
+exception that gets thrown when trying to evaluate a mathematical function
+at a singularity.
+
+The @code{pole_error} class has a member function
+
+@example
+int pole_error::degree(void) const;
+@end example
+
+that returns the order of the singularity (or 0 when the pole is
+logarithmic or the order is undefined).
+
+When using GiNaC it is useful to arrange for exceptions to be catched in
+the main program even if you don't want to do any special error handling.
+Otherwise whenever an error occurs in GiNaC, it will be delegated to the
+default exception handler of your C++ compiler's runtime system which
+usually only aborts the program without giving any information what went
+wrong.
+
+Here is an example for a @code{main()} function that catches and prints
+exceptions generated by GiNaC:
+
+@example
+#include
+#include
+#include
+using namespace std;
+using namespace GiNaC;
+
+int main(void)
+@{
+ try @{
+ ...
+ // code using GiNaC
+ ...
+ @} catch (exception &p) @{
+ cerr << p.what() << endl;
+ return 1;
+ @}
+ return 0;
+@}
+@end example
+
+
+@node The Class Hierarchy, Symbols, Error handling, Basic Concepts
@c nodename, next, previous, up
@section The Class Hierarchy
@@ 788,63 +913,7 @@ $\sqrt{2}$
@end cartouche
@node Error handling, Symbols, The Class Hierarchy, Basic Concepts
@c nodename, next, previous, up
@section Error handling
@cindex exceptions
@cindex @code{pole_error} (class)

GiNaC reports runtime errors by throwing C++ exceptions. All exceptions
generated by GiNaC are subclassed from the standard @code{exception} class
defined in the @file{} header. In addition to the predefined
@code{logic_error}, @code{domain_error}, @code{out_of_range},
@code{invalid_argument}, @code{runtime_error}, @code{range_error} and
@code{overflow_error} types, GiNaC also defines a @code{pole_error}
exception that gets thrown when trying to evaluate a mathematical function
at a singularity.

The @code{pole_error} class has a member function

@example
int pole_error::degree(void) const;
@end example

that returns the order of the singularity (or 0 when the pole is
logarithmic or the order is undefined).

When using GiNaC it is useful to arrange for exceptions to be catched in
the main program even if you don't want to do any special error handling.
Otherwise whenever an error occurs in GiNaC, it will be delegated to the
default exception handler of your C++ compiler's runtime system which
usually only aborts the program without giving any information what went
wrong.

Here is an example for a @code{main()} function that catches and prints
exceptions generated by GiNaC:

@example
#include
#include
#include
using namespace std;
using namespace GiNaC;

int main(void)
@{
 try @{
 ...
 // code using GiNaC
 ...
 @} catch (exception &p) @{
 cerr << p.what() << endl;
 return 1;
 @}
 return 0;
@}
@end example


@node Symbols, Numbers, Error handling, Basic Concepts
+@node Symbols, Numbers, The Class Hierarchy, Basic Concepts
@c nodename, next, previous, up
@section Symbols
@cindex @code{symbol} (class)
@@ 1125,13 +1194,13 @@ The predefined known constants are:
@node Fundamental containers, Lists, Constants, Basic Concepts
@c nodename, next, previous, up
@section Fundamental containers: the @code{power}, @code{add} and @code{mul} classes
+@section Sums, products and powers
@cindex polynomial
@cindex @code{add}
@cindex @code{mul}
@cindex @code{power}
Simple polynomial expressions are written down in GiNaC pretty much like
+Simple rational expressions are written down in GiNaC pretty much like
in other CAS or like expressions involving numerical variables in C.
The necessary operators @code{+}, @code{}, @code{*} and @code{/} have
been overloaded to achieve this goal. When you run the following
@@ 1193,15 +1262,6 @@ arbitrary number of slots for expressions to be inserted. Again, simple
and safe simplifications are carried out like transforming
@code{3*x+4x} to @code{2*x+4}.
The general rule is that when you construct such objects, GiNaC
automatically creates them in canonical form, which might differ from
the form you typed in your program. This allows for rapid comparison of
expressions, since after all @code{aa} is simply zero. Note, that the
canonical form is not necessarily lexicographical ordering or in any way
easily guessable. It is only guaranteed that constructing the same
expression twice, either implicitly or explicitly, results in the same
canonical form.

@node Lists, Mathematical functions, Fundamental containers, Basic Concepts
@c nodename, next, previous, up
@@ 5126,9 +5186,9 @@ concatenation. You would have to implement this yourself.
@subsection Automatic evaluation
@cindex @code{hold()}
@cindex @code{eval()}
@cindex evaluation
+@cindex @code{eval()}
+@cindex @code{hold()}
When dealing with objects that are just a little more complicated than the
simple string objects we have implemented, chances are that you will want to
have some automatic simplifications or canonicalizations performed on them.

2.38.1