Tutorial: how to create noncommutative symbols?

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

diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi
index b83ba1c7e1094d434e453a64e6844f91108f055b..93ed619ffc4c87b0e82de5b4fdaed6119d9e930f 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-2014 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-2014 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-2014 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.
 
@@ -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()}
@@ -6502,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
 
@@ -6515,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<symbol>(table["x"]);
+    symbol y = ex_to<symbol>(table["y"]);
 @}
 @end example
 
@@ -6689,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)
@@ -7100,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
@@ -7135,14 +7165,15 @@ functions without any special options.
 eval_func(<C++ function>)
 evalf_func(<C++ function>)
 derivative_func(<C++ function>)
+expl_derivative_func(<C++ function>)
 series_func(<C++ function>)
 conjugate_func(<C++ function>)
 @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.