Put a reference on eta function into tutorial.

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

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index 732487061da055bb2522796a5c95f91d96c34b43..21e31b2c98501fc7581ceed6c3013e978dbbc3f1 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -24,7 +24,7 @@
 This is a tutorial that documents GiNaC @value{VERSION}, an open
 framework for symbolic computation within the C++ programming language.
 
-Copyright (C) 1999-2011 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2015 Johannes Gutenberg University Mainz, Germany
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -52,7 +52,7 @@ notice identical to this one.
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2011 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2015 Johannes Gutenberg University Mainz, Germany
 @sp 2
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -135,7 +135,7 @@ the near future.
 
 @section License
 The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999-2011 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2015 Johannes Gutenberg
 University Mainz, Germany.
 
 This program is free software; you can redistribute it and/or
@@ -5772,11 +5772,11 @@ almost any kind of object (anything that is @code{subs()}able):
     idx i(symbol("i"), 3), j(symbol("j"), 3), k(symbol("k"), 3);
     symbol A("A"), B("B"), a("a"), b("b"), c("c");
                                            
-    cout << indexed(A, i, j).symmetrize() << endl;
+    cout << ex(indexed(A, i, j)).symmetrize() << endl;
      // -> 1/2*A.j.i+1/2*A.i.j
-    cout << indexed(A, i, j, k).antisymmetrize(lst(i, j)) << endl;
+    cout << ex(indexed(A, i, j, k)).antisymmetrize(lst(i, j)) << endl;
      // -> -1/2*A.j.i.k+1/2*A.i.j.k
-    cout << lst(a, b, c).symmetrize_cyclic(lst(a, b, c)) << endl;
+    cout << ex(lst(a, b, c)).symmetrize_cyclic(lst(a, b, c)) << endl;
      // -> 1/3*@{a,b,c@}+1/3*@{b,c,a@}+1/3*@{c,a,b@}
 @}
 @end example
@@ -5858,6 +5858,9 @@ GiNaC contains the following predefined mathematical functions:
 @item @code{log(x)}
 @tab natural logarithm
 @cindex @code{log()}
+@item @code{eta(x,y)}
+@tab Eta function: @code{eta(x,y) = log(x*y) - log(x) - log(y)}
+@cindex @code{eta()}
 @item @code{Li2(x)}
 @tab dilogarithm
 @cindex @code{Li2()}
@@ -5926,6 +5929,59 @@ towards -infinity.  These functions are continuous as the branch cut
 is approached coming around the finite endpoint of the cut in a
 counter clockwise direction.
 
+@c
+@subsection Expanding functions
+@cindex expand trancedent functions
+@cindex @code{expand_options::expand_transcendental}
+@cindex @code{expand_options::expand_function_args}
+GiNaC knows several expansion laws for trancedent functions, e.g.
+@tex
+$e^{a+b}=e^a e^b$,
+$|zw|=|z|\cdot |w|$
+@end tex
+@ifnottex
+@command{exp(a+b)=exp(a) exp(b), |zw|=|z| |w|}
+@end ifnottex
+or
+@tex
+$\log(c*d)=\log(c)+\log(d)$,
+@end tex
+@ifnottex
+@command{log(cd)=log(c)+log(d)}
+@end ifnottex
+(for positive
+@tex
+$c,\ d$
+@end tex
+@ifnottex
+@command{c, d}
+@end ifnottex
+). In order to use these rules you need to call @code{expand()} method
+with the option @code{expand_options::expand_transcendental}. Another
+relevant option is @code{expand_options::expand_function_args}. Their
+usage and interaction can be seen from the following example:
+@example
+@{
+       symbol x("x"),  y("y");
+       ex e=exp(pow(x+y,2));
+       cout << e.expand() << endl;
+       // -> exp((x+y)^2)
+       cout << e.expand(expand_options::expand_transcendental) << endl;
+       // -> exp((x+y)^2)
+       cout << e.expand(expand_options::expand_function_args) << endl;
+       // -> exp(2*x*y+x^2+y^2)
+       cout << e.expand(expand_options::expand_function_args
+                       | expand_options::expand_transcendental) << endl;
+       // -> exp(y^2)*exp(2*x*y)*exp(x^2)
+@}
+@end example
+If both flags are set (as in the last call), then GiNaC tries to get
+the maximal expansion. For example, for the exponent GiNaC firstly expands
+the argument and then the function. For the logarithm and absolute value,
+GiNaC uses the opposite order: firstly expands the function and then its
+argument. Of course, a user can fine-tune this behaviour by sequential
+calls of several @code{expand()} methods with desired flags.
+
 @node Multiple polylogarithms, Complex expressions, Built-in functions, Methods and functions
 @c    node-name, next, previous, up
 @subsection Multiple polylogarithms
@@ -6486,7 +6542,9 @@ Sometimes you might want to prevent GiNaC from inserting these extra symbols
 @}
 @end example
 
-With this parser, it's also easy to implement interactive GiNaC programs:
+With this parser, it's also easy to implement interactive GiNaC programs.
+When running the following program interactively, remember to send an
+EOF marker after the input, e.g. by pressing Ctrl-D on an empty line:
 
 @example
 #include <iostream>