This is a tutorial that documents GiNaC @value{VERSION}, an open
framework for symbolic computation within the C++ programming language.
-Copyright (C) 1999-2015 Johannes Gutenberg University Mainz, Germany
+Copyright (C) 1999-2019 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
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1999-2015 Johannes Gutenberg University Mainz, Germany
+Copyright @copyright{} 1999-2019 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
@section License
The GiNaC framework for symbolic computation within the C++ programming
-language is Copyright @copyright{} 1999-2015 Johannes Gutenberg
+language is Copyright @copyright{} 1999-2019 Johannes Gutenberg
University Mainz, Germany.
This program is free software; you can redistribute it and/or
@uref{http://pkg-config.freedesktop.org}.
Last but not least, the CLN library
is used extensively and needs to be installed on your system.
-Please get it from @uref{ftp://ftpthep.physik.uni-mainz.de/pub/gnu/}
-(it is covered by GPL) and install it prior to trying to install
-GiNaC. The configure script checks if it can find it and if it cannot
-it will refuse to continue.
+Please get it from @uref{http://www.ginac.de/CLN/} (it is licensed under
+the GPL) and install it prior to trying to install GiNaC. The configure
+script checks if it can find it and if it cannot, it will refuse to
+continue.
@node Configuration, Building GiNaC, Prerequisites, Installation
Internally, the anonymous evaluator in GiNaC is implemented by the methods
@example
-ex ex::eval(int level = 0) const;
-ex basic::eval(int level = 0) const;
+ex ex::eval() const;
+ex basic::eval() const;
@end example
but unless you are extending GiNaC with your own classes or functions, there
as "@code{\Box}" in LaTeX code (@xref{Input/output}, for more
information about the different output formats of expressions in GiNaC).
GiNaC automatically creates proper LaTeX code for symbols having names of
-greek letters (@samp{alpha}, @samp{mu}, etc.).
+greek letters (@samp{alpha}, @samp{mu}, etc.). You can retrieve the name
+and the LaTeX name of a symbol using the respective methods:
+@cindex @code{get_name()}
+@cindex @code{get_TeX_name()}
+@example
+symbol::get_name() const;
+symbol::get_TeX_name() const;
+@end example
@cindex @code{subs()}
Symbols in GiNaC can't be assigned values. If you need to store results of
ex matrix::determinant(unsigned algo=determinant_algo::automatic) const;
ex matrix::trace() const;
ex matrix::charpoly(const ex & lambda) const;
-unsigned matrix::rank() const;
+unsigned matrix::rank(unsigned algo=solve_algo::automatic) const;
@end example
-The @samp{algo} argument of @code{determinant()} allows to select
-between different algorithms for calculating the determinant. The
-asymptotic speed (as parametrized by the matrix size) can greatly differ
-between those algorithms, depending on the nature of the matrix'
-entries. The possible values are defined in the @file{flags.h} header
-file. By default, GiNaC uses a heuristic to automatically select an
-algorithm that is likely (but not guaranteed) to give the result most
-quickly.
+The optional @samp{algo} argument of @code{determinant()} and @code{rank()}
+functions allows to select between different algorithms for calculating the
+determinant and rank respectively. The asymptotic speed (as parametrized
+by the matrix size) can greatly differ between those algorithms, depending
+on the nature of the matrix' entries. The possible values are defined in
+the @file{flags.h} header file. By default, GiNaC uses a heuristic to
+automatically select an algorithm that is likely (but not guaranteed)
+to give the result most quickly.
-@cindex @code{inverse()} (matrix)
@cindex @code{solve()}
-Matrices may also be inverted using the @code{ex matrix::inverse()}
-method and linear systems may be solved with:
+Linear systems can be solved with:
@example
matrix matrix::solve(const matrix & vars, const matrix & rhs,
contain some of the indeterminates from @code{vars}. If the system is
overdetermined, an exception is thrown.
+@cindex @code{inverse()} (matrix)
+To invert a matrix, use the method:
+
+@example
+matrix matrix::inverse(unsigned algo=solve_algo::automatic) const;
+@end example
+
+The @samp{algo} argument is optional. If given, it must be one of
+@code{solve_algo} defined in @file{flags.h}.
@node Indexed objects, Non-commutative objects, Matrices, Basic concepts
@c node-name, next, previous, up
something very close to @code{dirac_gamma(mu)}, although
@code{dirac_gamma} have more efficient simplification mechanism.
@cindex @code{get_metric()}
+Also, the object created by @code{clifford_unit(mu, minkmetric())} is
+not aware about the symmetry of its metric, see the start of the previous
+paragraph. A more accurate analog of 'dirac_gamma(mu)' should be
+specifies as follows:
+
+@example
+ clifford_unit(mu, indexed(minkmetric(),sy_symm(),varidx(symbol("i"),4),varidx(symbol("j"),4)));
+@end example
+
The method @code{clifford::get_metric()} returns a metric defining this
Clifford number.
@example
ex clifford_prime(const ex & e)
- inline ex clifford_star(const ex & e) @{ return e.conjugate(); @}
- inline ex clifford_bar(const ex & e) @{ return clifford_prime(e.conjugate()); @}
+ inline ex clifford_star(const ex & e)
+ inline ex clifford_bar(const ex & e)
@end example
The automorphism of a Clifford algebra @code{clifford_prime()} simply
changes signs of all Clifford units in the expression. The reversion
-of a Clifford algebra @code{clifford_star()} coincides with the
-@code{conjugate()} method and effectively reverses the order of Clifford
+of a Clifford algebra @code{clifford_star()} reverses the order of Clifford
units in any product. Finally the main anti-automorphism
of a Clifford algebra @code{clifford_bar()} is the composition of the
previous two, i.e. it makes the reversion and changes signs of all Clifford units
@tab @dots{}a polynomial with (possibly complex) rational coefficients (such as @math{2/3+7/2*I})
@item @code{rational_function}
@tab @dots{}a rational function (@math{x+y}, @math{z/(x+y)})
-@item @code{algebraic}
-@tab @dots{}an algebraic object (@math{sqrt(2)}, @math{sqrt(x)-1})
@end multitable
@end cartouche
predicates to the STL:
@example
-class ex_is_less : public std::binary_function<ex, ex, bool> @{
+class ex_is_less @{
public:
bool operator()(const ex &lh, const ex &rh) const;
@};
-class ex_is_equal : public std::binary_function<ex, ex, bool> @{
+class ex_is_equal @{
public:
bool operator()(const ex &lh, const ex &rh) const;
@};
// count the number of expressions equal to '1'
unsigned num_ones = std::count_if(v.begin(), v.end(),
- std::bind2nd(ex_is_equal(), 1));
+ [](const ex& e) @{ return ex_is_equal()(e, 1); @});
@end example
The implementation of @code{ex_is_less} uses the member function
To evaluate them using floating-point arithmetic you need to call
@example
-ex ex::evalf(int level = 0) const;
+ex ex::evalf() const;
@end example
@cindex @code{Digits}
@cindex @code{ldegree()}
@cindex @code{coeff()}
-The degree and low degree of a polynomial can be obtained using the two
-methods
+The degree and low degree of a polynomial in expanded form can be obtained
+using the two methods
@example
int ex::degree(const ex & s);
int ex::ldegree(const ex & s);
@end example
-which also work reliably on non-expanded input polynomials (they even work
-on rational functions, returning the asymptotic degree). By definition, the
-degree of zero is zero. To extract a coefficient with a certain power from
-an expanded polynomial you use
+These functions even work on rational functions, returning the asymptotic
+degree. By definition, the degree of zero is zero. To extract a coefficient
+with a certain power from an expanded polynomial you use
@example
ex ex::coeff(const ex & s, int n);
These functions will first normalize the expression as described above and
then return the numerator, denominator, or both as a list, respectively.
-If you need both numerator and denominator, calling @code{numer_denom()} is
-faster than using @code{numer()} and @code{denom()} separately.
+If you need both numerator and denominator, call @code{numer_denom()}: it
+is faster than using @code{numer()} and @code{denom()} separately. And even
+more important: a separate evaluation of @code{numer()} and @code{denom()}
+may result in a spurious sign, e.g. for $x/(x^2-1)$ @code{numer()} may
+return $x$ and @code{denom()} $1-x^2$.
@subsection Converting to a polynomial or rational expression
@example
ex ex::to_polynomial(exmap & m);
-ex ex::to_polynomial(lst & l);
@end example
or
@example
ex ex::to_rational(exmap & m);
-ex ex::to_rational(lst & l);
@end example
-on the expression to be converted. The supplied @code{exmap} or @code{lst}
-will be filled with the generated temporary symbols and their replacement
-expressions in a format that can be used directly for the @code{subs()}
-method. It can also already contain a list of replacements from an earlier
-application of @code{.to_polynomial()} or @code{.to_rational()}, so it's
-possible to use it on multiple expressions and get consistent results.
+on the expression to be converted. The supplied @code{exmap} will be filled
+with the generated temporary symbols and their replacement expressions in a
+format that can be used directly for the @code{subs()} method. It can also
+already contain a list of replacements from an earlier application of
+@code{.to_polynomial()} or @code{.to_rational()}, so it's possible to use
+it on multiple expressions and get consistent results.
The difference between @code{.to_polynomial()} and @code{.to_rational()}
is probably best illustrated with an example:
ex a = 2*x/sin(x) - y/(3*sin(x));
cout << a << endl;
- lst lp;
- ex p = a.to_polynomial(lp);
- cout << " = " << p << "\n with " << lp << endl;
+ exmap mp;
+ ex p = a.to_polynomial(mp);
+ cout << " = " << p << "\n with " << mp << endl;
// = symbol3*symbol2*y+2*symbol2*x
// with @{symbol2==sin(x)^(-1),symbol3==-1/3@}
- lst lr;
- ex r = a.to_rational(lr);
- cout << " = " << r << "\n with " << lr << endl;
+ exmap mr;
+ ex r = a.to_rational(mr);
+ cout << " = " << r << "\n with " << mr << endl;
// = -1/3*symbol4^(-1)*y+2*symbol4^(-1)*x
// with @{symbol4==sin(x)@}
@}
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
+argument. Of course, a user can fine-tune this behavior by sequential
calls of several @code{expand()} methods with desired flags.
@node Multiple polylogarithms, Complex expressions, Built-in functions, Methods and functions
@cindex ginac-excompiler
@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. You can also export additional compiler flags via the $CXXFLAGS
-variable:
+will be installed together with GiNaC in the configured @code{$LIBEXECDIR}
+(typically @code{$PREFIX/libexec} or @code{$PREFIX/lib/ginac}). You can also
+export additional compiler flags via the @env{$CXXFLAGS} variable:
@example
setenv("CXXFLAGS", "-O3 -fomit-frame-pointer -ffast-math", 1);
@{
...
public:
- ex eval(int level = 0) const;
+ ex eval() const override;
...
@};
-ex mystring::eval(int level) const
+ex mystring::eval() const
@{
string new_str;
for (size_t i=0; i<str.length(); i++) @{
if (new_str.length() == 0)
return 0;
- else
- return mystring(new_str).hold();
+
+ return mystring(new_str).hold();
@}
@end example
-The @code{level} argument is used to limit the recursion depth of the
-evaluation. We don't have any subexpressions in the @code{mystring}
-class so we are not concerned with this. If we had, we would call the
-@code{eval()} functions of the subexpressions with @code{level - 1} as
-the argument if @code{level != 1}. The @code{hold()} member function
-sets a flag in the object that prevents further evaluation. Otherwise
-we might end up in an endless loop. When you want to return the object
-unmodified, use @code{return this->hold();}.
+The @code{hold()} member function sets a flag in the object that prevents
+further evaluation. Otherwise we might end up in an endless loop. When you
+want to return the object unmodified, use @code{return this->hold();}.
+
+If our class had subobjects, we would have to evaluate them first (unless
+they are all of type @code{ex}, which are automatically evaluated). We don't
+have any subexpressions in the @code{mystring} class, so we are not concerned
+with this.
Let's confirm that it works:
@cindex @code{calchash()}
@cindex @code{is_equal_same_type()}
@example
-unsigned calchash() const;
-bool is_equal_same_type(const basic & other) const;
+unsigned calchash() const override;
+bool is_equal_same_type(const basic & other) const override;
@end example
The @code{calchash()} method returns an @code{unsigned} hash value for the
might want to provide:
@example
-bool info(unsigned inf) const;
-ex evalf(int level = 0) const;
-ex series(const relational & r, int order, unsigned options = 0) const;
-ex derivative(const symbol & s) const;
+bool info(unsigned inf) const override;
+ex evalf() const override;
+ex series(const relational & r, int order, unsigned options = 0) const override;
+ex derivative(const symbol & s) const override;
@end example
If your class stores sub-expressions (see the scalar product example in the
@cindex @code{let_op()}
@example
-size_t nops() cont;
-ex op(size_t i) const;
-ex & let_op(size_t i);
-ex subs(const lst & ls, const lst & lr, unsigned options = 0) const;
-ex map(map_function & f) const;
+size_t nops() const override;
+ex op(size_t i) const override;
+ex & let_op(size_t i) override;
+ex subs(const lst & ls, const lst & lr, unsigned options = 0) const override;
+ex map(map_function & f) const override;
@end example
@code{let_op()} is a variant of @code{op()} that allows write access. The
git://www.ginac.de / ginac.git / blobdiff