X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=93ed619ffc4c87b0e82de5b4fdaed6119d9e930f;hp=a767d57cd5fb1c389db5c81d643591631023e1dd;hb=27213d158e5ec4b606b4f4d0766bf75eeb18673f;hpb=4077d8b144e2e5f3db75cf95fbb590981b2eb8d4 diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index a767d57c..93ed619f 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-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 @@ -3033,6 +3033,8 @@ canonicalize themselves according to rules specified in the implementation of the non-commutative classes. The drawback is that to work with other than the built-in algebras you have to implement new classes yourself. Both symbols and user-defined functions can be specified as being non-commutative. +For symbols, this is done by subclassing class symbol; for functions, +by explicitly setting the return type (@pxref{Symbolic functions}). @cindex @code{return_type()} @cindex @code{return_type_tinfo()} @@ -3334,7 +3336,7 @@ 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)}, although @code{dirac_gamma} have more efficient simplification mechanism. -@cindex @code{clifford::get_metric()} +@cindex @code{get_metric()} The method @code{clifford::get_metric()} returns a metric defining this Clifford number. @@ -5772,11 +5774,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 +5860,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 +5931,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 @@ -6449,7 +6507,7 @@ to map input (sub)strings to arbitrary expressions: table["x"] = x+log(y)+1; parser reader(table); ex e = reader("5*x^3 - x^2"); - // e = 5*(x+log(y)+1)^3 + (x+log(y)+1)^2 + // e = 5*(x+log(y)+1)^3 - (x+log(y)+1)^2 @} @end example @@ -6462,8 +6520,8 @@ with @code{get_syms()} method: parser reader; ex e = reader("2*x+sin(y)"); symtab table = reader.get_syms(); - symbol x = reader["x"]; - symbol y = reader["y"]; + symbol x = ex_to(table["x"]); + symbol y = ex_to(table["y"]); @} @end example @@ -6486,7 +6544,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 @@ -6634,7 +6694,13 @@ ones supplied to @code{compile_ex} should appear in the expression. @code{compile_ex} uses the shell script @code{ginac-excompiler} to start the C compiler and produce the object files. This shell script comes with GiNaC and will be installed together with GiNaC in the configured @code{$PREFIX/bin} -directory. +directory. You can also export additional compiler flags via the $CXXFLAGS +variable: + +@example +setenv("CXXFLAGS", "-O3 -fomit-frame-pointer -ffast-math", 1); +compile_ex(...); +@end example @subsection Archiving @cindex @code{archive} (class) @@ -7045,6 +7111,25 @@ specifies which parameter to differentiate in a partial derivative in case the function has more than one parameter, and its main application is for correct handling of the chain rule. +Derivatives of some functions, for example @code{abs()} and +@code{Order()}, could not be evaluated through the chain rule. In such +cases the full derivative may be specified as shown for @code{Order()}: + +@example +static ex Order_expl_derivative(const ex & arg, const symbol & s) +@{ + return Order(arg.diff(s)); +@} +@end example + +That is, we need to supply a procedure, which returns the expression of +derivative with respect to the variable @code{s} for the argument +@code{arg}. This procedure need to be registered with the function +through the option @code{expl_derivative_func} (see the next +Subsection). In contrast, a partial derivative, e.g. as was defined for +@code{cos()} above, needs to be registered through the option +@code{derivative_func}. + An implementation of the series expansion is not needed for @code{cos()} as it doesn't have any poles and GiNaC can do Taylor expansion by itself (as long as it knows what the derivative of @code{cos()} is). @code{tan()}, on @@ -7080,14 +7165,15 @@ functions without any special options. eval_func() evalf_func() derivative_func() +expl_derivative_func() series_func() conjugate_func() @end example These specify the C++ functions that implement symbolic evaluation, -numeric evaluation, partial derivatives, and series expansion, respectively. -They correspond to the GiNaC methods @code{eval()}, @code{evalf()}, -@code{diff()} and @code{series()}. +numeric evaluation, partial derivatives, explicit derivative, and series +expansion, respectively. They correspond to the GiNaC methods +@code{eval()}, @code{evalf()}, @code{diff()} and @code{series()}. The @code{eval_func()} function needs to use @code{.hold()} if no further automatic evaluation is desired or possible. @@ -8679,7 +8765,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 +8818,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}: