From: Christian Bauer Date: Wed, 19 Feb 2003 22:55:25 +0000 (+0000) Subject: added a section about automatic evaluation X-Git-Tag: release_1-0-14~7 X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=commitdiff_plain;h=ded2e4a35496e9a3c6c540965f53e2acbe11fa15 added a section about automatic evaluation --- 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 @@ 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{} 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 +#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 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{} 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 -#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 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.