Expansion rules for exp(), log(), and abs().

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

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index a767d57cd5fb1c389db5c81d643591631023e1dd..d5bea846342325744ea73283293dc31c2815760d 100644 (file)
--- a/doc/tutorial/ginac.texi
+++ b/doc/tutorial/ginac.texi
@@ -5926,6 +5926,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
@@ -8679,7 +8732,7 @@ If the required version was not found, executes @var{ACTION-IF-NOT-FOUND}.
 
 @node Configure script options, Example package, Package tools, Package tools 
 @c    node-name, next, previous, up
-@subsection Configuring a package that uses GiNaC
+@appendixsection Configuring a package that uses GiNaC
 
 The directory where the GiNaC libraries are installed needs
 to be found by your system's dynamic linkers (both compile- and run-time
@@ -8732,7 +8785,7 @@ $ ./configure
 
 @node Example package, Bibliography, Configure script options, Package tools
 @c    node-name, next, previous, up
-@subsection Example of a package using GiNaC
+@appendixsection Example of a package using GiNaC
 
 The following shows how to build a simple package using automake
 and the @samp{PKG_CHECK_MODULES} macro. The program used here is @file{simple.cpp}: