synced to 1.1

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

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index cd47cf3c094148523429fed6f98e831017e73671..34b919edb5a1241bb4b9d4efa590f839fec16366 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -742,7 +742,13 @@ evaluation}. GiNaC only performs transformations that are
 
 @itemize @bullet
 @item
-at most of complexity @math{O(n log n)}
+at most of complexity
+@tex
+$O(n\log n)$
+@end tex
+@ifnottex
+@math{O(n log n)}
+@end ifnottex
 @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})
@@ -899,7 +905,13 @@ $\sqrt{2}$
 @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{function} @tab A symbolic function like @math{sin(2*x)}
+@item @code{function} @tab A symbolic function like
+@tex
+$\sin 2x$
+@end tex
+@ifnottex
+@math{sin(2*x)}
+@end ifnottex
 @item @code{lst} @tab Lists of expressions @{@math{x}, @math{2*y}, @math{3+z}@}
 @item @code{matrix} @tab @math{m}x@math{n} matrices of expressions
 @item @code{relational} @tab A relation like the identity @math{x}@code{==}@math{y}
@@ -1162,6 +1174,30 @@ can be applied is listed in the following table.
 @end multitable
 @end cartouche
 
+@subsection Converting numbers
+
+Sometimes it is desirable to convert a @code{numeric} object back to a
+built-in arithmetic type (@code{int}, @code{double}, etc.). The @code{numeric}
+class provides a couple of methods for this purpose:
+
+@cindex @code{to_int()}
+@cindex @code{to_long()}
+@cindex @code{to_double()}
+@cindex @code{to_cl_N()}
+@example
+int numeric::to_int() const;
+long numeric::to_long() const;
+double numeric::to_double() const;
+cln::cl_N numeric::to_cl_N() const;
+@end example
+
+@code{to_int()} and @code{to_long()} only work when the number they are
+applied on is an exact integer. Otherwise the program will halt with a
+message like @samp{Not a 32-bit integer}. @code{to_double()} applied on a
+rational number will return a floating-point approximation. Both
+@code{to_int()/to_long()} and @code{to_double()} discard the imaginary
+part of complex numbers.
+
 
 @node Constants, Fundamental containers, Numbers, Basic Concepts
 @c    node-name, next, previous, up
@@ -2876,6 +2912,7 @@ avoided.
 
 @menu
 * Information About Expressions::
+* Numerical Evaluation::
 * Substituting Expressions::
 * Pattern Matching and Advanced Substitutions::
 * Applying a Function on Subexpressions::
@@ -2891,7 +2928,7 @@ avoided.
 @end menu
 
 
-@node Information About Expressions, Substituting Expressions, Methods and Functions, Methods and Functions
+@node Information About Expressions, Numerical Evaluation, Methods and Functions, Methods and Functions
 @c    node-name, next, previous, up
 @section Getting information about expressions
 
@@ -3159,7 +3196,47 @@ if @code{*this} sorts before @code{other}, and @math{1} if @code{*this} sorts
 after @code{other}.
 
 
-@node Substituting Expressions, Pattern Matching and Advanced Substitutions, Information About Expressions, Methods and Functions
+@node Numerical Evaluation, Substituting Expressions, Information About Expressions, Methods and Functions
+@c    node-name, next, previous, up
+@section Numercial Evaluation
+@cindex @code{evalf()}
+
+GiNaC keeps algebraic expressions, numbers and constants in their exact form.
+To evaluate them using floating-point arithmetic you need to call
+
+@example
+ex ex::evalf(int level = 0) const;
+@end example
+
+@cindex @code{Digits}
+The accuracy of the evaluation is controlled by the global object @code{Digits}
+which can be assigned an integer value. The default value of @code{Digits}
+is 17. @xref{Numbers}, for more information and examples.
+
+To evaluate an expression to a @code{double} floating-point number you can
+call @code{evalf()} followed by @code{numeric::to_double()}, like this:
+
+@example
+@{
+    // Approximate sin(x/Pi)
+    symbol x("x");
+    ex e = series(sin(x/Pi), x == 0, 6);
+
+    // Evaluate numerically at x=0.1
+    ex f = evalf(e.subs(x == 0.1));
+
+    // ex_to<numeric> is an unsafe cast, so check the type first
+    if (is_a<numeric>(f)) @{
+        double d = ex_to<numeric>(f).to_double();
+        cout << d << endl;
+         // -> 0.0318256
+    @} else
+        // error
+@}
+@end example
+
+
+@node Substituting Expressions, Pattern Matching and Advanced Substitutions, Numerical Evaluation, Methods and Functions
 @c    node-name, next, previous, up
 @section Substituting expressions
 @cindex @code{subs()}