documentation update

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

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 54a373433ab5615281dd3f598cec62b1e69bf3d4..98033e40767d1914fc7f8fded5e5a99f4a4127a5 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -1354,21 +1354,31 @@ second one in the range 0@dots{}@math{n-1}.
 There are a couple of ways to construct matrices, with or without preset
 elements:
 
+@cindex @code{lst_to_matrix()}
+@cindex @code{diag_matrix()}
+@cindex @code{unit_matrix()}
+@cindex @code{symbolic_matrix()}
 @example
 matrix::matrix(unsigned r, unsigned c);
 matrix::matrix(unsigned r, unsigned c, const lst & l);
 ex lst_to_matrix(const lst & l);
 ex diag_matrix(const lst & l);
+ex unit_matrix(unsigned x);
+ex unit_matrix(unsigned r, unsigned c);
+ex symbolic_matrix(unsigned r, unsigned c, const string & base_name);
+ex symbolic_matrix(unsigned r, unsigned c, const string & base_name, const string & tex_base_name);
 @end example
 
 The first two functions are @code{matrix} constructors which create a matrix
 with @samp{r} rows and @samp{c} columns. The matrix elements can be
 initialized from a (flat) list of expressions @samp{l}. Otherwise they are
 all set to zero. The @code{lst_to_matrix()} function constructs a matrix
-from a list of lists, each list representing a matrix row. Finally,
-@code{diag_matrix()} constructs a diagonal matrix given the list of diagonal
-elements. Note that the last two functions return expressions, not matrix
-objects.
+from a list of lists, each list representing a matrix row. @code{diag_matrix()}
+constructs a diagonal matrix given the list of diagonal elements.
+@code{unit_matrix()} creates an @samp{x} by @samp{x} (or @samp{r} 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 elements can be accessed and set using the parenthesis (function call)
 operator:
@@ -1382,27 +1392,32 @@ It is also possible to access the matrix elements in a linear fashion with
 the @code{op()} method. But C++-style subscripting with square brackets
 @samp{[]} is not available.
 
-Here are a couple of examples that all construct the same 2x2 diagonal
-matrix:
+Here are a couple of examples of constructing matrices:
 
 @example
 @{
     symbol a("a"), b("b");
-    ex e;
 
     matrix M(2, 2);
     M(0, 0) = a;
     M(1, 1) = b;
-    e = M;
-
-    e = matrix(2, 2, lst(a, 0, 0, b));
+    cout << M << endl;
+     // -> [[a,0],[0,b]]
 
-    e = lst_to_matrix(lst(lst(a, 0), lst(0, b)));
+    cout << matrix(2, 2, lst(a, 0, 0, b)) << endl;
+     // -> [[a,0],[0,b]]
 
-    e = diag_matrix(lst(a, b));
+    cout << lst_to_matrix(lst(lst(a, 0), lst(0, b))) << endl;
+     // -> [[a,0],[0,b]]
 
-    cout << e << endl;
+    cout << diag_matrix(lst(a, b)) << endl;
      // -> [[a,0],[0,b]]
+
+    cout << unit_matrix(3) << endl;
+     // -> [[1,0,0],[0,1,0],[0,0,1]]
+
+    cout << symbolic_matrix(2, 3, "x") << endl;
+     // -> [[x00,x01,x02],[x10,x11,x12]]
 @}
 @end example
 
@@ -1492,6 +1507,9 @@ general.
 The @code{matrix} class provides a couple of additional methods for
 computing determinants, traces, and characteristic polynomials:
 
+@cindex @code{determinant()}
+@cindex @code{trace()}
+@cindex @code{charpoly()}
 @example
 ex matrix::determinant(unsigned algo = determinant_algo::automatic) const;
 ex matrix::trace(void) const;
@@ -2381,28 +2399,29 @@ ex dirac_ONE(unsigned char rl = 0);
 multiples of the unity element, even though it's customary to omit it.
 E.g. instead of @code{dirac_gamma(mu)*(dirac_slash(q,4)+m)} you have to
 write @code{dirac_gamma(mu)*(dirac_slash(q,4)+m*dirac_ONE())}. Otherwise,
-GiNaC may produce incorrect results.
+GiNaC will complain and/or produce incorrect results.
 
 @cindex @code{dirac_gamma5()}
-There's a special element @samp{gamma5} that commutes with all other
-gammas and in 4 dimensions equals @samp{gamma~0 gamma~1 gamma~2 gamma~3},
-provided by
+There is a special element @samp{gamma5} that commutes with all other
+gammas, has a unit square, and in 4 dimensions equals
+@samp{gamma~0 gamma~1 gamma~2 gamma~3}, provided by
 
 @example
 ex dirac_gamma5(unsigned char rl = 0);
 @end example
 
-@cindex @code{dirac_gamma6()}
-@cindex @code{dirac_gamma7()}
-The two additional functions
+@cindex @code{dirac_gammaL()}
+@cindex @code{dirac_gammaR()}
+The chiral projectors @samp{(1+/-gamma5)/2} are also available as proper
+objects, constructed by
 
 @example
-ex dirac_gamma6(unsigned char rl = 0);
-ex dirac_gamma7(unsigned char rl = 0);
+ex dirac_gammaL(unsigned char rl = 0);
+ex dirac_gammaR(unsigned char rl = 0);
 @end example
 
-return @code{dirac_ONE(rl) + dirac_gamma5(rl)} and @code{dirac_ONE(rl) - dirac_gamma5(rl)},
-respectively.
+They observe the relations @samp{gammaL^2 = gammaL}, @samp{gammaR^2 = gammaR},
+and @samp{gammaL gammaR = gammaR gammaL = 0}.
 
 @cindex @code{dirac_slash()}
 Finally, the function
@@ -2417,9 +2436,11 @@ with a unique index whose dimension is given by the @code{dim} argument).
 Such slashed expressions are printed with a trailing backslash, e.g. @samp{e\}.
 
 In products of dirac gammas, superfluous unity elements are automatically
-removed, squares are replaced by their values and @samp{gamma5} is
-anticommuted to the front. The @code{simplify_indexed()} function performs
-contractions in gamma strings, for example
+removed, squares are replaced by their values, and @samp{gamma5}, @samp{gammaL}
+and @samp{gammaR} are moved to the front.
+
+The @code{simplify_indexed()} function performs contractions in gamma strings,
+for example
 
 @example
 @{