- speedup by declaring x_pt and so on const
[ginac.git] / doc / tutorial / ginac.texi
index af43c97312320607e6b744463d81c8e680355634..f69d45107968ec0d2943d05179d43817aeb61efc 100644 (file)
@@ -1028,7 +1028,7 @@ for exclusive or.  (It would be embarassing to return @code{1} where one
 has requested @code{2^3}.)
 @end itemize
 
-@cindex @code{ginsh}
+@cindex @command{ginsh}
 All effects are contrary to mathematical notation and differ from the
 way most other CAS handle exponentiation, therefore overloading @code{^}
 is ruled out for GiNaC's C++ part.  The situation is different in
@@ -1105,8 +1105,16 @@ gamma(x+1/2) -> gamma(x+1/2)
 gamma(15/2) -> (135135/128)*Pi^(1/2)
 @end example
 
-Most of these functions can be differentiated, series expanded and so
-on.  Read the next chapter in order to learn more about this.
+@cindex branch cut
+For functions that have a branch cut in the complex plane GiNaC follows
+the conventions for C++ as defined in the ANSI standard.  In particular:
+the natural logarithm (@code{log}) and the square root (@code{sqrt})
+both have their branch cuts running along the negative real axis where
+the points on the axis itself belong to the upper part.
+
+Besides evaluation most of these functions allow differentiation, series
+expansion and so on.  Read the next chapter in order to learn more about
+this.
 
 
 @node Relations, Important Algorithms, Built-in functions, Basic Concepts
@@ -1425,10 +1433,14 @@ When you run it, it produces the sequence @code{1}, @code{-1}, @code{5},
 @cindex Laurent expansion
 
 Expressions know how to expand themselves as a Taylor series or (more
-generally) a Laurent series.  Similar to most conventional Computer
-Algebra Systems, no distinction is made between those two.  There is a
-class of its own for storing such series as well as a class for storing
-the order of the series.  A sample program could read:
+generally) a Laurent series.  As in most conventional Computer Algebra
+Systems, no distinction is made between those two.  There is a class of
+its own for storing such series as well as a class for storing the order
+of the series.  As a consequence, if you want to work with series,
+i.e. multiply two series, you need to call the method @code{ex::series}
+again to convert it to a series object with the usual structure
+(expansion plus order term).  A sample application from special
+relativity could read:
 
 @example
 #include <ginac/ginac.h>
@@ -1436,25 +1448,28 @@ using namespace GiNaC;
 
 int main()
 @{
-    symbol x("x");
-    numeric point(0);
-    ex MyExpr1 = sin(x);
-    ex MyExpr2 = 1/(x - pow(x, 2) - pow(x, 3));
-    ex MyTailor, MySeries;
+    symbol v("v"), c("c");
+    
+    ex gamma = 1/sqrt(1 - pow(v/c,2));
+    ex mass_nonrel = gamma.series(v, 0, 10);
+    
+    cout << "the relativistic mass increase with v is " << endl
+         << mass_nonrel << endl;
+    
+    cout << "the inverse square of this series is " << endl
+         << pow(mass_nonrel,-2).series(v, 0, 10) << endl;
     
-    MyTailor = MyExpr1.series(x, point, 5);
-    cout << MyExpr1 << " == " << MyTailor
-         << " for small " << x << endl;
-    MySeries = MyExpr2.series(x, point, 7);
-    cout << MyExpr2 << " == " << MySeries
-         << " for small " << x << endl;
     // ...
 @}
 @end example
 
+Only calling the series method makes the last output simplify to
+@math{1-v^2/c^2+O(v^10)}, without that call we would just have a long
+series raised to the power @math{-2}.
+
 @cindex M@'echain's formula
-As an instructive application, let us calculate the numerical value of
-Archimedes' constant
+As another instructive application, let us calculate the numerical 
+value of Archimedes' constant
 @tex
 $\pi$
 @end tex
@@ -1535,7 +1550,7 @@ authors---they will happily incorporate them into future versions.
 @c    node-name, next, previous, up
 @section What doesn't belong into GiNaC
 
-@cindex @code{ginsh}
+@cindex @command{ginsh}
 First of all, GiNaC's name must be read literally.  It is designed to be
 a library for use within C++.  The tiny @command{ginsh} accompanying
 GiNaC makes this even more clear: it doesn't even attempt to provide a