* Make timer class a little bit more lightweight and accurate.

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

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 1d63162a25c5fba0fd8d55ab37b865c7712f7378..af8c4a7d5178bfbb341687083aa5d1413bb94f5e 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -417,6 +417,27 @@ x^(-1)-0.5772156649015328606+(0.9890559953279725555)*x
 Here we have made use of the @command{ginsh}-command @code{%} to pop the
 previously evaluated element from @command{ginsh}'s internal stack.
 
 Here we have made use of the @command{ginsh}-command @code{%} to pop the
 previously evaluated element from @command{ginsh}'s internal stack.
 

+Often, functions don't have roots in closed form.  Nevertheless, it's
+quite easy to compute a solution numerically, to arbitrary precision:
+
+@cindex fsolve
+@example
+> Digits=50:
+> fsolve(cos(x)==x,x,0,2);
+0.7390851332151606416553120876738734040134117589007574649658
+> f=exp(sin(x))-x:
+> X=fsolve(f,x,-10,10);
+2.2191071489137460325957851882042901681753665565320678854155
+> subs(f,x==X);
+-6.372367644529809108115521591070847222364418220770475144296E-58
+@end example
+
+Notice how the final result above differs slightly from zero by about
+@math{6*10^(-58)}.  This is because with 50 decimal digits precision the
+root cannot be represented more accurately than @code{X}.  Such
+inaccuracies are to be expected when computing with finite floating
+point values.
+

 If you ever wanted to convert units in C or C++ and found this is
 cumbersome, here is the solution.  Symbolic types can always be used as
 tags for different types of objects.  Converting from wrong units to the
 If you ever wanted to convert units in C or C++ and found this is
 cumbersome, here is the solution.  Symbolic types can always be used as
 tags for different types of objects.  Converting from wrong units to the


@@ -460,12 +481,10 @@ so if you have a different compiler you are on your own.  For the
 configuration to succeed you need a Posix compliant shell installed in
 @file{/bin/sh}, GNU @command{bash} is fine.  Perl is needed by the built
 process as well, since some of the source files are automatically
 configuration to succeed you need a Posix compliant shell installed in
 @file{/bin/sh}, GNU @command{bash} is fine.  Perl is needed by the built
 process as well, since some of the source files are automatically

-generated by Perl scripts.  Last but not least, Bruno Haible's library
-CLN is extensively used and needs to be installed on your system.
-Please get it either from @uref{ftp://ftp.santafe.edu/pub/gnu/}, from
-@uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/, GiNaC's FTP site} or
-from @uref{ftp://ftp.ilog.fr/pub/Users/haible/gnu/, Bruno Haible's FTP
-site} (it is covered by GPL) and install it prior to trying to install
+generated by Perl scripts.  Last but not least, the CLN library
+is used extensively and needs to be installed on your system.
+Please get it from @uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/}
+(it is covered by GPL) and install it prior to trying to install

 GiNaC.  The configure script checks if it can find it and if it cannot
 it will refuse to continue.
 
 GiNaC.  The configure script checks if it can find it and if it cannot
 it will refuse to continue.
 


@@ -1889,7 +1908,7 @@ much work if an expression contains the same integral multiple times,
 a lookup table is used.
 
 If you know that an expression holds an integral, you can get the
 a lookup table is used.
 
 If you know that an expression holds an integral, you can get the

-integration variable, the left boundary, right boundary and integrant by
+integration variable, the left boundary, right boundary and integrand by

 respectively calling @code{.op(0)}, @code{.op(1)}, @code{.op(2)}, and
 @code{.op(3)}. Differentiating integrals with respect to variables works
 as expected. Note that it makes no sense to differentiate an integral
 respectively calling @code{.op(0)}, @code{.op(1)}, @code{.op(2)}, and
 @code{.op(3)}. Differentiating integrals with respect to variables works
 as expected. Note that it makes no sense to differentiate an integral


@@ -1953,6 +1972,38 @@ by @samp{c}) unit matrix. And finally, @code{symbolic_matrix} constructs a
 matrix filled with newly generated symbols made of the specified base name
 and the position of each element in the matrix.
 
 matrix filled with newly generated symbols made of the specified base name
 and the position of each element in the matrix.
 

+Matrices often arise by omitting elements of another matrix. For
+instance, the submatrix @code{S} of a matrix @code{M} takes a
+rectangular block from @code{M}. The reduced matrix @code{R} is defined
+by removing one row and one column from a matrix @code{M}. (The
+determinant of a reduced matrix is called a @emph{Minor} of @code{M} and
+can be used for computing the inverse using Cramer's rule.)
+
+@cindex @code{sub_matrix()}
+@cindex @code{reduced_matrix()}
+@example
+ex sub_matrix(const matrix&m, unsigned r, unsigned nr, unsigned c, unsigned nc);
+ex reduced_matrix(const matrix& m, unsigned r, unsigned c);
+@end example
+
+The function @code{sub_matrix()} takes a row offset @code{r} and a
+column offset @code{c} and takes a block of @code{nr} rows and @code{nc}
+columns. The function @code{reduced_matrix()} has two integer arguments
+that specify which row and column to remove:
+
+@example
+@{
+    matrix m(3,3);
+    m = 11, 12, 13,
+        21, 22, 23,
+        31, 32, 33;
+    cout << reduced_matrix(m, 1, 1) << endl;
+    // -> [[11,13],[31,33]]
+    cout << sub_matrix(m, 1, 2, 1, 2) << endl;
+    // -> [[22,23],[32,33]]
+@}
+@end example
+

 Matrix elements can be accessed and set using the parenthesis (function call)
 operator:
 
 Matrix elements can be accessed and set using the parenthesis (function call)
 operator:
 


@@ -2567,6 +2618,47 @@ of a sum are consistent:
 @}
 @end example
 
 @}
 @end example
 

+@cindex @code{expand_dummy_sum()}
+A dummy index summation like 
+@tex
+$ a_i b^i$
+@end tex
+@ifnottex
+a.i b~i
+@end ifnottex
+can be expanded for indices with numeric
+dimensions (e.g. 3)  into the explicit sum like
+@tex
+$a_1b^1+a_2b^2+a_3b^3 $.
+@end tex
+@ifnottex
+a.1 b~1 + a.2 b~2 + a.3 b~3.
+@end ifnottex
+This is performed by the function
+
+@example
+    ex expand_dummy_sum(const ex & e, bool subs_idx = false);
+@end example
+
+which takes an expression @code{e} and returns the expanded sum for all
+dummy indices with numeric dimensions. If the parameter @code{subs_idx}
+is set to @code{true} then all substitutions are made by @code{idx} class
+indices, i.e. without variance. In this case the above sum 
+@tex
+$ a_i b^i$
+@end tex
+@ifnottex
+a.i b~i
+@end ifnottex
+will be expanded to
+@tex
+$a_1b_1+a_2b_2+a_3b_3 $.
+@end tex
+@ifnottex
+a.1 b.1 + a.2 b.2 + a.3 b.3.
+@end ifnottex
+
+

 @cindex @code{simplify_indexed()}
 @subsection Simplifying indexed expressions
 
 @cindex @code{simplify_indexed()}
 @subsection Simplifying indexed expressions
 


@@ -3189,27 +3281,51 @@ generators
 @end tex 
 satisfying the identities 
 @tex
 @end tex 
 satisfying the identities 
 @tex

-$e_i e_j + e_j e_i = M(i, j) $
+$e_i e_j + e_j e_i = M(i, j) + M(j, i) $

 @end tex
 @ifnottex
 @end tex
 @ifnottex

-e~i e~j + e~j e~i = M(i, j)
+e~i e~j + e~j e~i = M(i, j) + M(j, i) 

 @end ifnottex
 @end ifnottex

-for some matrix (@code{metric})
-@math{M(i, j)}, which may be non-symmetric and containing symbolic
-entries. Such generators are created by the function
+for some bilinear form (@code{metric})
+@math{M(i, j)}, which may be non-symmetric (see arXiv:math.QA/9911180) 
+and contain symbolic entries. Such generators are created by the
+function 

 
 @example
 
 @example

-    ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0);
+    ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0, 
+                                bool anticommuting = false);    

 @end example
 
 where @code{mu} should be a @code{varidx} class object indexing the
 @end example
 
 where @code{mu} should be a @code{varidx} class object indexing the

-generators, @code{metr} defines the metric @math{M(i, j)} and can be
+generators, an index @code{mu} with a numeric value may be of type
+@code{idx} as well.
+Parameter @code{metr} defines the metric @math{M(i, j)} and can be

 represented by a square @code{matrix}, @code{tensormetric} or @code{indexed} class
 represented by a square @code{matrix}, @code{tensormetric} or @code{indexed} class

-object, optional parameter @code{rl} allows to distinguish different
-Clifford algebras (which will commute with each other). Note that the call
-@code{clifford_unit(mu, minkmetric())} creates something very close to
-@code{dirac_gamma(mu)}. The method @code{clifford::get_metric()} returns a
-metric defining this Clifford number.
+object. Optional parameter @code{rl} allows to distinguish different
+Clifford algebras, which will commute with each other. The last
+optional parameter @code{anticommuting} defines if the anticommuting
+assumption (i.e.
+@tex
+$e_i e_j + e_j e_i = 0$)
+@end tex
+@ifnottex
+e~i e~j + e~j e~i = 0)
+@end ifnottex
+will be used for contraction of Clifford units. If the @code{metric} is
+supplied by a @code{matrix} object, then the value of
+@code{anticommuting} is calculated automatically and the supplied one
+will be ignored. One can overcome this by giving @code{metric} through
+matrix wrapped into an @code{indexed} object.
+
+Note that the call @code{clifford_unit(mu, minkmetric())} creates
+something very close to @code{dirac_gamma(mu)}, although
+@code{dirac_gamma} have more efficient simplification mechanism. 
+@cindex @code{clifford::get_metric()}
+The method @code{clifford::get_metric()} returns a metric defining this
+Clifford number.
+@cindex @code{clifford::is_anticommuting()}
+The method @code{clifford::is_anticommuting()} returns the
+@code{anticommuting} property of a unit.

 
 If the matrix @math{M(i, j)} is in fact symmetric you may prefer to create
 the Clifford algebra units with a call like that
 
 If the matrix @math{M(i, j)} is in fact symmetric you may prefer to create
 the Clifford algebra units with a call like that


@@ -3218,7 +3334,9 @@ the Clifford algebra units with a call like that
     ex e = clifford_unit(mu, indexed(M, sy_symm(), i, j));
 @end example
 
     ex e = clifford_unit(mu, indexed(M, sy_symm(), i, j));
 @end example
 

-since this may yield some further automatic simplifications.
+since this may yield some further automatic simplifications. Again, for a
+metric defined through a @code{matrix} such a symmetry is detected
+automatically. 

 
 Individual generators of a Clifford algebra can be accessed in several
 ways. For example 
 
 Individual generators of a Clifford algebra can be accessed in several
 ways. For example 


@@ -3243,7 +3361,8 @@ will produce four anti-commuting generators of a Clifford algebra with propertie
 $e_0^2=1 $, $e_1^2=-1$,  $e_2^2=0$ and $e_3^2=s$.
 @end tex
 @ifnottex
 $e_0^2=1 $, $e_1^2=-1$,  $e_2^2=0$ and $e_3^2=s$.
 @end tex
 @ifnottex

-@code{pow(e0, 2) = 1},  @code{pow(e1, 2) = -1},   @code{pow(e2, 2) = 0} and   @code{pow(e3, 2) = s}. 
+@code{pow(e0, 2) = 1}, @code{pow(e1, 2) = -1}, @code{pow(e2, 2) = 0} and
+@code{pow(e3, 2) = s}.

 @end ifnottex
 
 @cindex @code{lst_to_clifford()}
 @end ifnottex
 
 @cindex @code{lst_to_clifford()}


@@ -3251,7 +3370,7 @@ A similar effect can be achieved from the function
 
 @example
     ex lst_to_clifford(const ex & v, const ex & mu,  const ex & metr,
 
 @example
     ex lst_to_clifford(const ex & v, const ex & mu,  const ex & metr,

-                       unsigned char rl = 0);
+                       unsigned char rl = 0, bool anticommuting = false);

     ex lst_to_clifford(const ex & v, const ex & e);
 @end example
 
     ex lst_to_clifford(const ex & v, const ex & e);
 @end example
 


@@ -3273,7 +3392,7 @@ $v^0 e_0 + v^1 e_1 + ... + v^n e_n$
 with @samp{e.k}
 directly supplied in the second form of the procedure. In the first form
 the Clifford unit @samp{e.k} is generated by the call of
 with @samp{e.k}
 directly supplied in the second form of the procedure. In the first form
 the Clifford unit @samp{e.k} is generated by the call of

-@code{clifford_unit(mu, metr, rl)}. The previous code may be rewritten
+@code{clifford_unit(mu, metr, rl, anticommuting)}. The previous code may be rewritten

 with the help of @code{lst_to_clifford()} as follows
 
 @example
 with the help of @code{lst_to_clifford()} as follows
 
 @example


@@ -3321,7 +3440,7 @@ $(e c_k + c_k e)/c_k^2$. If $c_k^2$
 @ifnottex
 @samp{(e c.k + c.k e)/pow(c.k, 2)}.   If @samp{pow(c.k, 2)} 
 @end ifnottex
 @ifnottex
 @samp{(e c.k + c.k e)/pow(c.k, 2)}.   If @samp{pow(c.k, 2)} 
 @end ifnottex

-is zero or is not a @code{numeric} for some @samp{k}
+is zero or is not @code{numeric} for some @samp{k}

 then the method will be automatically changed to symbolic. The same effect
 is obtained by the assignment (@code{algebraic = false}) in the procedure call.
 
 then the method will be automatically changed to symbolic. The same effect
 is obtained by the assignment (@code{algebraic = false}) in the procedure call.
 


@@ -3410,30 +3529,44 @@ expression by the function
 The function @code{canonicalize_clifford()} works for a
 generic Clifford algebra in a similar way as for Dirac gammas.
 
 The function @code{canonicalize_clifford()} works for a
 generic Clifford algebra in a similar way as for Dirac gammas.
 

-The last provided function is
+The next provided function is

 
 @cindex @code{clifford_moebius_map()}
 @example
     ex clifford_moebius_map(const ex & a, const ex & b, const ex & c,
                             const ex & d, const ex & v, const ex & G,
 
 @cindex @code{clifford_moebius_map()}
 @example
     ex clifford_moebius_map(const ex & a, const ex & b, const ex & c,
                             const ex & d, const ex & v, const ex & G,

-                            unsigned char rl = 0);
+                            unsigned char rl = 0, bool anticommuting = false);

     ex clifford_moebius_map(const ex & M, const ex & v, const ex & G,
     ex clifford_moebius_map(const ex & M, const ex & v, const ex & G,

-                            unsigned char rl = 0);
+                            unsigned char rl = 0, bool anticommuting = false);

 @end example 
 
 It takes a list or vector @code{v} and makes the Moebius (conformal or
 linear-fractional) transformation @samp{v -> (av+b)/(cv+d)} defined by
 the matrix @samp{M = [[a, b], [c, d]]}. The parameter @code{G} defines
 @end example 
 
 It takes a list or vector @code{v} and makes the Moebius (conformal or
 linear-fractional) transformation @samp{v -> (av+b)/(cv+d)} defined by
 the matrix @samp{M = [[a, b], [c, d]]}. The parameter @code{G} defines

-the metric of the surrounding (pseudo-)Euclidean space. This can be a
-matrix or a Clifford unit, in the later case the parameter @code{rl} is
-ignored even if supplied.  The returned value of this function is a list
-of components of the resulting vector.
+the metric of the surrounding (pseudo-)Euclidean space. This can be an
+indexed object, tensormetric, matrix or a Clifford unit, in the later
+case the optional parameters @code{rl} and @code{anticommuting} are ignored
+even if supplied.  The returned value of this function is a list of
+components of the resulting vector.

 
 

-LaTeX output for Clifford units looks like @code{\clifford[1]@{e@}^@{@{\nu@}@}},
-where @code{1} is the @code{representation_label} and @code{\nu} is the
-index of the corresponding unit. This provides a flexible typesetting
-with a suitable defintion of the @code{\clifford} command. For example, the
-definition 
+@cindex @code{clifford_max_label()}
+Finally the function
+
+@example
+char clifford_max_label(const ex & e, bool ignore_ONE = false);
+@end example
+
+can detect a presence of Clifford objects in the expression @code{e}: if
+such objects are found it returns the maximal
+@code{representation_label} of them, otherwise @code{-1}. The optional
+parameter @code{ignore_ONE} indicates if @code{dirac_ONE} objects should
+be ignored during the search.
+ 
+LaTeX output for Clifford units looks like
+@code{\clifford[1]@{e@}^@{@{\nu@}@}}, where @code{1} is the
+@code{representation_label} and @code{\nu} is the index of the
+corresponding unit. This provides a flexible typesetting with a suitable
+defintion of the @code{\clifford} command. For example, the definition

 @example
     \newcommand@{\clifford@}[1][]@{@}
 @end example
 @example
     \newcommand@{\clifford@}[1][]@{@}
 @end example


@@ -5143,7 +5276,8 @@ The functions @code{gcd()} and @code{lcm()} accept two expressions
 @code{a} and @code{b} as arguments and return a new expression, their
 greatest common divisor or least common multiple, respectively.  If the
 polynomials @code{a} and @code{b} are coprime @code{gcd(a,b)} returns 1
 @code{a} and @code{b} as arguments and return a new expression, their
 greatest common divisor or least common multiple, respectively.  If the
 polynomials @code{a} and @code{b} are coprime @code{gcd(a,b)} returns 1

-and @code{lcm(a,b)} returns the product of @code{a} and @code{b}.
+and @code{lcm(a,b)} returns the product of @code{a} and @code{b}. Note that all
+the coefficients must be rationals.

 
 @example
 #include <ginac/ginac.h>
 
 @example
 #include <ginac/ginac.h>