X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=d5bea846342325744ea73283293dc31c2815760d;hp=29c0d479e58c272313fe97e4637e3b9f43f695da;hb=e5c76f659e2e882da3d5dba60502d6851f782bf3;hpb=67edef78ce992a8f6ad704bfac228b8dec6eacd2 diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index 29c0d479..d5bea846 100644 --- 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-2010 Johannes Gutenberg University Mainz, Germany +Copyright (C) 1999-2011 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-2010 Johannes Gutenberg University Mainz, Germany +Copyright @copyright{} 1999-2011 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-2010 Johannes Gutenberg +language is Copyright @copyright{} 1999-2011 Johannes Gutenberg University Mainz, Germany. This program is free software; you can redistribute it and/or @@ -4263,7 +4263,7 @@ In the first form, @code{subs()} accepts a relational of the form @{ symbol x("x"), y("y"); - ex e1 = 2*x^2-4*x+3; + ex e1 = 2*x*x-4*x+3; cout << "e1(7) = " << e1.subs(x == 7) << endl; // -> 73 @@ -4637,7 +4637,7 @@ often as is possible without getting negative exponents. For example @code{(x^(-3)*y^(-2)*z).subs(1/(x*y)==c, subs_options::algebraic)} will return @code{x^(-1)*c^2*z}. -@strong{Note:} this only works for multiplications +@strong{Please notice:} this only works for multiplications and not for locating @code{x+y} within @code{x+y+z}. @@ -5912,20 +5912,72 @@ GiNaC contains the following predefined mathematical functions: @end cartouche @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 as far as -possible. 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 (i.e. continuous with quadrant II). The inverse -trigonometric and hyperbolic functions are not defined for complex -arguments by the C++ standard, however. In GiNaC we follow the -conventions used by CLN, which in turn follow the carefully designed -definitions in the Common Lisp standard. It should be noted that this -convention is identical to the one used by the C99 standard and by most -serious CAS. It is to be expected that future revisions of the C++ -standard incorporate these functions in the complex domain in a manner -compatible with C99. +For functions that have a branch cut in the complex plane, GiNaC +follows the conventions of C/C++ for systems that do not support a +signed zero. In particular: the natural logarithm (@code{log}) and +the square root (@code{sqrt}) both have their branch cuts running +along the negative real axis. The @code{asin}, @code{acos}, and +@code{atanh} functions all have two branch cuts starting at +/-1 and +running away towards infinity along the real axis. The @code{atan} and +@code{asinh} functions have two branch cuts starting at +/-i and +running away towards infinity along the imaginary axis. The +@code{acosh} function has one branch cut starting at +1 and running +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 @@ -6149,12 +6201,13 @@ For example, @} @end example -If you declare your own GiNaC functions, then they will conjugate themselves -by conjugating their arguments. This is the default strategy. If you want to -change this behavior, you have to supply a specialized conjugation method -for your function (see @ref{Symbolic functions} and the GiNaC source-code -for @code{abs} as an example). Also, specialized methods can be provided -to take real and imaginary parts of user-defined functions. +If you declare your own GiNaC functions and you want to conjugate them, you +will have to supply a specialized conjugation method for them (see +@ref{Symbolic functions} and the GiNaC source-code for @code{abs} as an +example). GiNaC does not automatically conjugate user-supplied functions +by conjugating their arguments because this would be incorrect on branch +cuts. Also, specialized methods can be provided to take real and imaginary +parts of user-defined functions. @node Solving linear systems of equations, Input/output, Complex expressions, Methods and functions @c node-name, next, previous, up @@ -6569,7 +6622,7 @@ pointer types at the moment: @cindex Monte Carlo integration @code{FUNCP_2P} allows for two variables in the expression. @code{FUNCP_CUBA} is the correct type to be used with the CUBA library -(@uref{http://www.feynarts/cuba}) for numerical integrations. The details for the +(@uref{http://www.feynarts.de/cuba}) for numerical integrations. The details for the parameters of @code{FUNCP_CUBA} are explained in the CUBA manual. @cindex compile_ex @@ -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}: