@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.
@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})
@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
@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)
@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
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
@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.
git://www.ginac.de / ginac.git / commitdiff