added a section about automatic evaluation
authorChristian Bauer <Christian.Bauer@uni-mainz.de>
Wed, 19 Feb 2003 22:55:25 +0000 (22:55 +0000)
committerChristian Bauer <Christian.Bauer@uni-mainz.de>
Wed, 19 Feb 2003 22:55:25 +0000 (22:55 +0000)
doc/tutorial/ginac.texi

index 80000ff..022a9a2 100644 (file)
@@ -672,12 +672,13 @@ meta-class 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::                    Pre-defined 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 @@ meta-class 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    node-name, 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    node-name, 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*x-1
+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 re-ordered
+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{y-x}) 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
+re-evaluate their results.
+
+
+@node Error handling, The Class Hierarchy, Automatic evaluation, Basic Concepts
+@c    node-name, next, previous, up
+@section Error handling
+@cindex exceptions
+@cindex @code{pole_error} (class)
+
+GiNaC reports run-time errors by throwing C++ exceptions. All exceptions
+generated by GiNaC are subclassed from the standard @code{exception} class
+defined in the @file{<stdexcept>} 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 run-time 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 <iostream>
+#include <stdexcept>
+#include <ginac/ginac.h>
+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    node-name, 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    node-name, next, previous, up
-@section Error handling
-@cindex exceptions
-@cindex @code{pole_error} (class)
-
-GiNaC reports run-time errors by throwing C++ exceptions. All exceptions
-generated by GiNaC are subclassed from the standard @code{exception} class
-defined in the @file{<stdexcept>} 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 run-time 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 <iostream>
-#include <stdexcept>
-#include <ginac/ginac.h>
-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    node-name, 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    node-name, 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+4-x} 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{a-a} 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    node-name, 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.