X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=4195678e8e0f5d266cad5cc179d95d7bda6b50d9;hp=af8c4a7d5178bfbb341687083aa5d1413bb94f5e;hb=f303227c240827857e2fb0631c537f553a9845e2;hpb=97388e4743a865ed81bf2afab1558783c8e0d67d diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index af8c4a7d..4195678e 100644 --- a/doc/tutorial/ginac.texi +++ b/doc/tutorial/ginac.texi @@ -23,7 +23,7 @@ This is a tutorial that documents GiNaC @value{VERSION}, an open framework for symbolic computation within the C++ programming language. -Copyright (C) 1999-2005 Johannes Gutenberg University Mainz, Germany +Copyright (C) 1999-2006 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 @@ -47,12 +47,11 @@ notice identical to this one. @title GiNaC @value{VERSION} @subtitle An open framework for symbolic computation within the C++ programming language @subtitle @value{UPDATED} -@author The GiNaC Group: -@author Christian Bauer, Alexander Frink, Richard Kreckel, Jens Vollinga +@author @uref{http://www.ginac.de} @page @vskip 0pt plus 1filll -Copyright @copyright{} 1999-2005 Johannes Gutenberg University Mainz, Germany +Copyright @copyright{} 1999-2006 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 @@ -79,20 +78,20 @@ framework for symbolic computation within the C++ programming language. @menu * Introduction:: GiNaC's purpose. -* A Tour of GiNaC:: A quick tour of the library. +* A tour of GiNaC:: A quick tour of the library. * Installation:: How to install the package. -* Basic Concepts:: Description of fundamental classes. -* Methods and Functions:: Algorithms for symbolic manipulations. +* Basic concepts:: Description of fundamental classes. +* Methods and functions:: Algorithms for symbolic manipulations. * Extending GiNaC:: How to extend the library. -* A Comparison With Other CAS:: Compares GiNaC to traditional CAS. -* Internal Structures:: Description of some internal structures. -* Package Tools:: Configuring packages to work with GiNaC. +* A comparison with other CAS:: Compares GiNaC to traditional CAS. +* Internal structures:: Description of some internal structures. +* Package tools:: Configuring packages to work with GiNaC. * Bibliography:: -* Concept Index:: +* Concept index:: @end menu -@node Introduction, A Tour of GiNaC, Top, Top +@node Introduction, A tour of GiNaC, Top, Top @c node-name, next, previous, up @chapter Introduction @cindex history of GiNaC @@ -135,7 +134,7 @@ the near future. @section License The GiNaC framework for symbolic computation within the C++ programming -language is Copyright @copyright{} 1999-2005 Johannes Gutenberg +language is Copyright @copyright{} 1999-2006 Johannes Gutenberg University Mainz, Germany. This program is free software; you can redistribute it and/or @@ -154,7 +153,7 @@ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -@node A Tour of GiNaC, How to use it from within C++, Introduction, Top +@node A tour of GiNaC, How to use it from within C++, Introduction, Top @c node-name, next, previous, up @chapter A Tour of GiNaC @@ -168,7 +167,7 @@ leaves many open questions. @end menu -@node How to use it from within C++, What it can do for you, A Tour of GiNaC, A Tour of GiNaC +@node How to use it from within C++, What it can do for you, A tour of GiNaC, A tour of GiNaC @c node-name, next, previous, up @section How to use it from within C++ @@ -206,7 +205,7 @@ $ ./hello 355687428096000*x*y+20922789888000*y^2+6402373705728000*x^2 @end example -(@xref{Package Tools}, for tools that help you when creating a software +(@xref{Package tools}, for tools that help you when creating a software package that uses GiNaC.) @cindex Hermite polynomial @@ -256,7 +255,7 @@ the @command{ginsh}, a simple GiNaC interactive shell that provides a convenient window into GiNaC's capabilities. -@node What it can do for you, Installation, How to use it from within C++, A Tour of GiNaC +@node What it can do for you, Installation, How to use it from within C++, A tour of GiNaC @c node-name, next, previous, up @section What it can do for you @@ -638,7 +637,7 @@ subdirectories. It is therefore safe to go into any subdirectory @var{target} there in case something went wrong. -@node Installing GiNaC, Basic Concepts, Building GiNaC, Installation +@node Installing GiNaC, Basic concepts, Building GiNaC, Installation @c node-name, next, previous, up @section Installing GiNaC @cindex installation @@ -691,9 +690,9 @@ do it by hand since you now know where all the files went during installation.}. -@node Basic Concepts, Expressions, Installing GiNaC, Top +@node Basic concepts, Expressions, Installing GiNaC, Top @c node-name, next, previous, up -@chapter Basic Concepts +@chapter Basic concepts This chapter will describe the different fundamental objects that can be handled by GiNaC. But before doing so, it is worthwhile introducing you @@ -704,7 +703,7 @@ meta-class for storing all mathematical objects. * Expressions:: The fundamental GiNaC class. * Automatic evaluation:: Evaluation and canonicalization. * Error handling:: How the library reports errors. -* The Class Hierarchy:: Overview of GiNaC's classes. +* The class hierarchy:: Overview of GiNaC's classes. * Symbols:: Symbolic objects. * Numbers:: Numerical objects. * Constants:: Pre-defined constants. @@ -716,11 +715,11 @@ meta-class for storing all mathematical objects. * Matrices:: Matrices. * Indexed objects:: Handling indexed quantities. * Non-commutative objects:: Algebras with non-commutative products. -* Hash Maps:: A faster alternative to std::map<>. +* Hash maps:: A faster alternative to std::map<>. @end menu -@node Expressions, Automatic evaluation, Basic Concepts, Basic Concepts +@node Expressions, Automatic evaluation, Basic concepts, Basic concepts @c node-name, next, previous, up @section Expressions @cindex expression (class @code{ex}) @@ -742,7 +741,7 @@ ex MyEx5 = MyEx4 + 1; // similar to above Expressions are handles to other more fundamental objects, that often contain other expressions thus creating a tree of expressions -(@xref{Internal Structures}, for particular examples). Most methods on +(@xref{Internal structures}, for particular examples). Most methods on @code{ex} therefore run top-down through such an expression tree. For example, the method @code{has()} scans recursively for occurrences of something inside an expression. Thus, if you have declared @code{MyEx4} @@ -769,11 +768,11 @@ as @code{std::set}. Unsorted containers such as @code{std::vector<>} and @code{std::list<>} don't pose a problem. A @code{std::vector} works as expected. -@xref{Information About Expressions}, for more about comparing and ordering +@xref{Information about expressions}, for more about comparing and ordering expressions. -@node Automatic evaluation, Error handling, Expressions, Basic Concepts +@node Automatic evaluation, Error handling, Expressions, Basic concepts @c node-name, next, previous, up @section Automatic evaluation and canonicalization of expressions @cindex evaluation @@ -847,7 +846,7 @@ transform expressions, like @code{subs()} or @code{normal()}, automatically re-evaluate their results. -@node Error handling, The Class Hierarchy, Automatic evaluation, Basic Concepts +@node Error handling, The class hierarchy, Automatic evaluation, Basic concepts @c node-name, next, previous, up @section Error handling @cindex exceptions @@ -903,9 +902,9 @@ int main() @end example -@node The Class Hierarchy, Symbols, Error handling, Basic Concepts +@node The class hierarchy, Symbols, Error handling, Basic concepts @c node-name, next, previous, up -@section The Class Hierarchy +@section The class hierarchy GiNaC's class hierarchy consists of several classes representing mathematical objects, all of which (except for @code{ex} and some @@ -929,7 +928,7 @@ features. An example is @code{expairseq}, a container for a sequence of pairs each consisting of one expression and a number (@code{numeric}). What @emph{is} visible to the user are the derived classes @code{add} and @code{mul}, representing sums and products. @xref{Internal -Structures}, where these two classes are described in more detail. The +structures}, where these two classes are described in more detail. The following table shortly summarizes what kinds of mathematical objects are stored in the different classes: @@ -977,7 +976,7 @@ $\sin 2x$ @end cartouche -@node Symbols, Numbers, The Class Hierarchy, Basic Concepts +@node Symbols, Numbers, The class hierarchy, Basic concepts @c node-name, next, previous, up @section Symbols @cindex @code{symbol} (class) @@ -1128,7 +1127,7 @@ definitions. As we said, the names of symbols primarily serve for purposes of expression output. But there are actually two instances where GiNaC uses the names for identifying symbols: When constructing an expression from a string, and when -recreating an expression from an archive (@pxref{Input/Output}). +recreating an expression from an archive (@pxref{Input/output}). In addition to its name, a symbol may contain a special string that is used in LaTeX output: @@ -1137,7 +1136,7 @@ symbol x("x", "\\Box"); @end example This creates a symbol that is printed as "@code{x}" in normal output, but -as "@code{\Box}" in LaTeX code (@xref{Input/Output}, for more +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.). @@ -1147,21 +1146,27 @@ Symbols in GiNaC can't be assigned values. If you need to store results of calculations and give them a name, use C++ variables of type @code{ex}. If you want to replace a symbol in an expression with something else, you can invoke the expression's @code{.subs()} method -(@pxref{Substituting Expressions}). +(@pxref{Substituting expressions}). @cindex @code{realsymbol()} By default, symbols are expected to stand in for complex values, i.e. they live in the complex domain. As a consequence, operations like complex conjugation, -for example (@pxref{Complex Conjugation}), do @emph{not} evaluate if applied +for example (@pxref{Complex expressions}), do @emph{not} evaluate if applied to such symbols. Likewise @code{log(exp(x))} does not evaluate to @code{x}, because of the unknown imaginary part of @code{x}. -On the other hand, if you are sure that your symbols will hold only real values, you -would like to have such functions evaluated. Therefore GiNaC allows you to specify +On the other hand, if you are sure that your symbols will hold only real +values, you would like to have such functions evaluated. Therefore GiNaC +allows you to specify the domain of the symbol. Instead of @code{symbol x("x");} you can write @code{realsymbol x("x");} to tell GiNaC that @code{x} stands in for real values. +@cindex @code{possymbol()} +Furthermore, it is also possible to declare a symbol as positive. This will, +for instance, enable the automatic simplification of @code{abs(x)} into +@code{x}. This is done by declaying the symbol as @code{possymbol x("x");}. -@node Numbers, Constants, Symbols, Basic Concepts + +@node Numbers, Constants, Symbols, Basic concepts @c node-name, next, previous, up @section Numbers @cindex @code{numeric} (class) @@ -1393,6 +1398,8 @@ evaluated immediately: @cindex @code{imag()} @item @code{csgn(z)} @tab complex sign (returns an @code{int}) +@item @code{step(x)} +@tab step function (returns an @code{numeric}) @item @code{numer(z)} @tab numerator of rational or complex rational number @item @code{denom(z)} @@ -1509,7 +1516,7 @@ rational number will return a floating-point approximation. Both part of complex numbers. -@node Constants, Fundamental containers, Numbers, Basic Concepts +@node Constants, Fundamental containers, Numbers, Basic concepts @c node-name, next, previous, up @section Constants @cindex @code{constant} (class) @@ -1539,7 +1546,7 @@ The predefined known constants are: @end cartouche -@node Fundamental containers, Lists, Constants, Basic Concepts +@node Fundamental containers, Lists, Constants, Basic concepts @c node-name, next, previous, up @section Sums, products and powers @cindex polynomial @@ -1610,7 +1617,7 @@ and safe simplifications are carried out like transforming @code{3*x+4-x} to @code{2*x+4}. -@node Lists, Mathematical functions, Fundamental containers, Basic Concepts +@node Lists, Mathematical functions, Fundamental containers, Basic concepts @c node-name, next, previous, up @section Lists of expressions @cindex @code{lst} (class) @@ -1775,7 +1782,7 @@ elements with @code{unique()}: @end example -@node Mathematical functions, Relations, Lists, Basic Concepts +@node Mathematical functions, Relations, Lists, Basic concepts @c node-name, next, previous, up @section Mathematical functions @cindex @code{function} (class) @@ -1784,7 +1791,7 @@ elements with @code{unique()}: There are quite a number of useful functions hard-wired into GiNaC. For instance, all trigonometric and hyperbolic functions are implemented -(@xref{Built-in Functions}, for a complete list). +(@xref{Built-in functions}, for a complete list). These functions (better called @emph{pseudofunctions}) are all objects of class @code{function}. They accept one or more expressions as @@ -1827,7 +1834,7 @@ point number of class @code{numeric} you should call wrapped inside an @code{ex}. -@node Relations, Integrals, Mathematical functions, Basic Concepts +@node Relations, Integrals, Mathematical functions, Basic concepts @c node-name, next, previous, up @section Relations @cindex @code{relational} (class) @@ -1853,7 +1860,7 @@ conversion from @code{relational} to @code{bool} takes place. Note, however, that @code{==} here does not perform any simplifications, hence @code{expand()} must be called explicitly. -@node Integrals, Matrices, Relations, Basic Concepts +@node Integrals, Matrices, Relations, Basic concepts @c node-name, next, previous, up @section Integrals @cindex @code{integral} (class) @@ -1914,7 +1921,7 @@ respectively calling @code{.op(0)}, @code{.op(1)}, @code{.op(2)}, and as expected. Note that it makes no sense to differentiate an integral with respect to the integration variable. -@node Matrices, Indexed objects, Integrals, Basic Concepts +@node Matrices, Indexed objects, Integrals, Basic concepts @c node-name, next, previous, up @section Matrices @cindex @code{matrix} (class) @@ -2051,6 +2058,12 @@ Here are a couple of examples for constructing matrices: @} @end example +@cindex @code{is_zero_matrix()} +The method @code{matrix::is_zero_matrix()} returns @code{true} only if +all entries of the matrix are zeros. There is also method +@code{ex::is_zero_matrix()} which returns @code{true} only if the +expression is zero or a zero matrix. + @cindex @code{transpose()} There are three ways to do arithmetic with matrices. The first (and most direct one) is to use the methods provided by the @code{matrix} class: @@ -2178,7 +2191,7 @@ contain some of the indeterminates from @code{vars}. If the system is overdetermined, an exception is thrown. -@node Indexed objects, Non-commutative objects, Matrices, Basic Concepts +@node Indexed objects, Non-commutative objects, Matrices, Basic concepts @c node-name, next, previous, up @section Indexed objects @@ -2327,7 +2340,7 @@ bool idx::is_dim_symbolic(); for checking whether the value and dimension are numeric or symbolic (non-numeric). Using the @code{info()} method of an index (see @ref{Information -About Expressions}) returns information about the index value. +about expressions}) returns information about the index value. @cindex @code{varidx} (class) If you need co- and contravariant indices, use the @code{varidx} class: @@ -2418,7 +2431,7 @@ and the same or opposite variance. Sometimes you will want to substitute one symbolic index with another symbolic or numeric index, for example when calculating one specific element of a tensor expression. This is done with the @code{.subs()} method, as it -is done for symbols (see @ref{Substituting Expressions}). +is done for symbols (see @ref{Substituting expressions}). You have two possibilities here. You can either substitute the whole index by another index or expression: @@ -2715,11 +2728,7 @@ arithmetic class, you just pass it to @code{simplify_indexed()}): The @code{scalar_products} object @code{sp} acts as a storage for the scalar products added to it with the @code{.add()} method. This method takes three arguments: the two expressions of which the scalar product is -taken, and the expression to replace it with. After @code{sp.add(A, B, 0)}, -@code{simplify_indexed()} will replace all scalar products of indexed -objects that have the symbols @code{A} and @code{B} as base expressions -with the single value 0. The number, type and dimension of the indices -don't matter; @samp{A~mu~nu*B.mu.nu} would also be replaced by 0. +taken, and the expression to replace it with. @cindex @code{expand()} The example above also illustrates a feature of the @code{expand()} method: @@ -2954,7 +2963,7 @@ one form for @samp{F} and explicitly multiply it with a matrix representation of the metric tensor. -@node Non-commutative objects, Hash Maps, Indexed objects, Basic Concepts +@node Non-commutative objects, Hash maps, Indexed objects, Basic concepts @c node-name, next, previous, up @section Non-commutative objects @@ -3011,10 +3020,8 @@ expressions. Also, non-commutative products in GiNaC are more intelligent than in other computer algebra systems; they can, for example, automatically 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. Symbols -always commutate and it's not possible to construct non-commutative products -using symbols to represent the algebra elements or generators. User-defined -functions can, however, be specified as being non-commutative. +the built-in algebras you have to implement new classes yourself. Both +symbols and user-defined functions can be specified as being non-commutative. @cindex @code{return_type()} @cindex @code{return_type_tinfo()} @@ -3292,30 +3299,19 @@ and contain symbolic entries. Such generators are created by the function @example - ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0, - bool anticommuting = false); + ex clifford_unit(const ex & mu, const ex & metr, unsigned char rl = 0); @end example -where @code{mu} should be a @code{varidx} class object indexing the -generators, an index @code{mu} with a numeric value may be of type -@code{idx} as well. +where @code{mu} should be a @code{idx} (or descendant) class object +indexing the generators. Parameter @code{metr} defines the metric @math{M(i, j)} and can be represented by a square @code{matrix}, @code{tensormetric} or @code{indexed} class -object. Optional parameter @code{rl} allows to distinguish different -Clifford algebras, which will commute with each other. The last -optional parameter @code{anticommuting} defines if the anticommuting -assumption (i.e. -@tex -$e_i e_j + e_j e_i = 0$) -@end tex -@ifnottex -e~i e~j + e~j e~i = 0) -@end ifnottex -will be used for contraction of Clifford units. If the @code{metric} is -supplied by a @code{matrix} object, then the value of -@code{anticommuting} is calculated automatically and the supplied one -will be ignored. One can overcome this by giving @code{metric} through -matrix wrapped into an @code{indexed} object. +object. In fact, any expression either with two free indices or without +indices at all is admitted as @code{metr}. In the later case an @code{indexed} +object with two newly created indices with @code{metr} as its +@code{op(0)} will be used. +Optional parameter @code{rl} allows to distinguish different +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 @@ -3323,9 +3319,6 @@ something very close to @code{dirac_gamma(mu)}, although @cindex @code{clifford::get_metric()} The method @code{clifford::get_metric()} returns a metric defining this Clifford number. -@cindex @code{clifford::is_anticommuting()} -The method @code{clifford::is_anticommuting()} returns the -@code{anticommuting} property of a unit. If the matrix @math{M(i, j)} is in fact symmetric you may prefer to create the Clifford algebra units with a call like that @@ -3344,14 +3337,14 @@ ways. For example @example @{ ... - varidx nu(symbol("nu"), 4); + idx i(symbol("i"), 4); realsymbol s("s"); ex M = diag_matrix(lst(1, -1, 0, s)); - ex e = clifford_unit(nu, M); - ex e0 = e.subs(nu == 0); - ex e1 = e.subs(nu == 1); - ex e2 = e.subs(nu == 2); - ex e3 = e.subs(nu == 3); + ex e = clifford_unit(i, M); + ex e0 = e.subs(i == 0); + ex e1 = e.subs(i == 1); + ex e2 = e.subs(i == 2); + ex e3 = e.subs(i == 3); ... @} @end example @@ -3370,7 +3363,7 @@ A similar effect can be achieved from the function @example ex lst_to_clifford(const ex & v, const ex & mu, const ex & metr, - unsigned char rl = 0, bool anticommuting = false); + unsigned char rl = 0); ex lst_to_clifford(const ex & v, const ex & e); @end example @@ -3392,19 +3385,19 @@ $v^0 e_0 + v^1 e_1 + ... + v^n e_n$ with @samp{e.k} directly supplied in the second form of the procedure. In the first form the Clifford unit @samp{e.k} is generated by the call of -@code{clifford_unit(mu, metr, rl, anticommuting)}. The previous code may be rewritten +@code{clifford_unit(mu, metr, rl)}. The previous code may be rewritten with the help of @code{lst_to_clifford()} as follows @example @{ ... - varidx nu(symbol("nu"), 4); + idx i(symbol("i"), 4); realsymbol s("s"); ex M = diag_matrix(lst(1, -1, 0, s)); - ex e0 = lst_to_clifford(lst(1, 0, 0, 0), nu, M); - ex e1 = lst_to_clifford(lst(0, 1, 0, 0), nu, M); - ex e2 = lst_to_clifford(lst(0, 0, 1, 0), nu, M); - ex e3 = lst_to_clifford(lst(0, 0, 0, 1), nu, M); + ex e0 = lst_to_clifford(lst(1, 0, 0, 0), i, M); + ex e1 = lst_to_clifford(lst(0, 1, 0, 0), i, M); + ex e2 = lst_to_clifford(lst(0, 0, 1, 0), i, M); + ex e3 = lst_to_clifford(lst(0, 0, 0, 1), i, M); ... @} @end example @@ -3535,9 +3528,9 @@ The next provided function is @example ex clifford_moebius_map(const ex & a, const ex & b, const ex & c, const ex & d, const ex & v, const ex & G, - unsigned char rl = 0, bool anticommuting = false); + unsigned char rl = 0); ex clifford_moebius_map(const ex & M, const ex & v, const ex & G, - unsigned char rl = 0, bool anticommuting = false); + unsigned char rl = 0); @end example It takes a list or vector @code{v} and makes the Moebius (conformal or @@ -3545,9 +3538,9 @@ linear-fractional) transformation @samp{v -> (av+b)/(cv+d)} defined by the matrix @samp{M = [[a, b], [c, d]]}. The parameter @code{G} defines the metric of the surrounding (pseudo-)Euclidean space. This can be an indexed object, tensormetric, matrix or a Clifford unit, in the later -case the optional parameters @code{rl} and @code{anticommuting} are ignored -even if supplied. The returned value of this function is a list of -components of the resulting vector. +case the optional parameter @code{rl} is ignored even if supplied. +Depending from the type of @code{v} the returned value of this function +is either a vector or a list holding vector's components. @cindex @code{clifford_max_label()} Finally the function @@ -3717,7 +3710,7 @@ example: @end example -@node Hash Maps, Methods and Functions, Non-commutative objects, Basic Concepts +@node Hash maps, Methods and functions, Non-commutative objects, Basic concepts @c node-name, next, previous, up @section Hash Maps @cindex hash maps @@ -3753,9 +3746,9 @@ table @end itemize -@node Methods and Functions, Information About Expressions, Hash Maps, Top +@node Methods and functions, Information about expressions, Hash maps, Top @c node-name, next, previous, up -@chapter Methods and Functions +@chapter Methods and functions @cindex polynomial In this chapter the most important algorithms provided by GiNaC will be @@ -3794,27 +3787,26 @@ method on class @code{ex} and sometimes calling a function cannot be avoided. @menu -* Information About Expressions:: -* Numerical Evaluation:: -* Substituting Expressions:: -* Pattern Matching and Advanced Substitutions:: -* Applying a Function on Subexpressions:: -* Visitors and Tree Traversal:: -* Polynomial Arithmetic:: Working with polynomials. -* Rational Expressions:: Working with rational functions. -* Symbolic Differentiation:: -* Series Expansion:: Taylor and Laurent expansion. +* Information about expressions:: +* Numerical evaluation:: +* Substituting expressions:: +* Pattern matching and advanced substitutions:: +* Applying a function on subexpressions:: +* Visitors and tree traversal:: +* Polynomial arithmetic:: Working with polynomials. +* Rational expressions:: Working with rational functions. +* Symbolic differentiation:: +* Series expansion:: Taylor and Laurent expansion. * Symmetrization:: -* Built-in Functions:: List of predefined mathematical functions. +* Built-in functions:: List of predefined mathematical functions. * Multiple polylogarithms:: -* Complex Conjugation:: -* Built-in Functions:: List of predefined mathematical functions. -* Solving Linear Systems of Equations:: -* Input/Output:: Input and output of expressions. +* Complex expressions:: +* Solving linear systems of equations:: +* Input/output:: Input and output of expressions. @end menu -@node Information About Expressions, Numerical Evaluation, Methods and Functions, Methods and Functions +@node Information about expressions, Numerical evaluation, Methods and functions, Methods and functions @c node-name, next, previous, up @section Getting information about expressions @@ -3841,7 +3833,7 @@ unsigned ex::return_type_tinfo() const; When the test made by @code{is_a()} returns true, it is safe to call one of the functions @code{ex_to()}, where @code{T} is one of the -class names (@xref{The Class Hierarchy}, for a list of all classes). For +class names (@xref{The class hierarchy}, for a list of all classes). For example, assuming @code{e} is an @code{ex}: @example @@ -3855,7 +3847,7 @@ example, assuming @code{e} is an @code{ex}: @code{is_a(e)} allows you to check whether the top-level object of an expression @samp{e} is an instance of the GiNaC class @samp{T} -(@xref{The Class Hierarchy}, for a list of all classes). This is most useful, +(@xref{The class hierarchy}, for a list of all classes). This is most useful, e.g., for checking whether an expression is a number, a sum, or a product: @example @@ -3887,7 +3879,7 @@ table: @item @code{numeric} @tab @dots{}a number (same as @code{is_a(...)}) @item @code{real} -@tab @dots{}a real integer, rational or float (i.e. is not complex) +@tab @dots{}a real number, symbol or constant (i.e. is not complex) @item @code{rational} @tab @dots{}an exact rational number (integers are rational, too) @item @code{integer} @@ -4098,7 +4090,8 @@ bool ex::is_zero(); @end example for checking whether one expression is equal to another, or equal to zero, -respectively. +respectively. See also the method @code{ex::is_zero_matrix()}, +@pxref{Matrices}. @subsection Ordering expressions @@ -4171,9 +4164,9 @@ if @code{*this} sorts before @code{other}, and @math{1} if @code{*this} sorts after @code{other}. -@node Numerical Evaluation, Substituting Expressions, Information About Expressions, Methods and Functions +@node Numerical evaluation, Substituting expressions, Information about expressions, Methods and functions @c node-name, next, previous, up -@section Numerical Evaluation +@section Numerical evaluation @cindex @code{evalf()} GiNaC keeps algebraic expressions, numbers and constants in their exact form. @@ -4211,7 +4204,7 @@ call @code{evalf()} followed by @code{numeric::to_double()}, like this: @end example -@node Substituting Expressions, Pattern Matching and Advanced Substitutions, Numerical Evaluation, Methods and Functions +@node Substituting expressions, Pattern matching and advanced substitutions, Numerical evaluation, Methods and functions @c node-name, next, previous, up @section Substituting expressions @cindex @code{subs()} @@ -4279,13 +4272,17 @@ contain the same number of elements). Using this form, you would write @end example The optional last argument to @code{subs()} is a combination of -@code{subs_options} flags. There are two options available: +@code{subs_options} flags. There are three options available: @code{subs_options::no_pattern} disables pattern matching, which makes large @code{subs()} operations significantly faster if you are not using patterns. The second option, @code{subs_options::algebraic} enables algebraic substitutions in products and powers. -@ref{Pattern Matching and Advanced Substitutions}, for more information -about patterns and algebraic substitutions. +@ref{Pattern matching and advanced substitutions}, for more information +about patterns and algebraic substitutions. The third option, +@code{subs_options::no_index_renaming} disables the feature that dummy +indices are renamed if the subsitution could give a result in which a +dummy index occurs more than two times. This is sometimes necessary if +you want to use @code{subs()} to rename your dummy indices. @code{subs()} performs syntactic substitution of any complete algebraic object; it does not try to match sub-expressions as is demonstrated by the @@ -4314,7 +4311,7 @@ A more powerful form of substitution using wildcards is described in the next section. -@node Pattern Matching and Advanced Substitutions, Applying a Function on Subexpressions, Substituting Expressions, Methods and Functions +@node Pattern matching and advanced substitutions, Applying a function on subexpressions, Substituting expressions, Methods and functions @c node-name, next, previous, up @section Pattern matching and advanced substitutions @cindex @code{wildcard} (class) @@ -4589,61 +4586,27 @@ The last example would be written in C++ in this way: @} @end example -@subsection Algebraic substitutions -Supplying the @code{subs_options::algebraic} option to @code{subs()} -enables smarter, algebraic substitutions in products and powers. If you want -to substitute some factors of a product, you only need to list these factors -in your pattern. Furthermore, if an (integer) power of some expression occurs -in your pattern and in the expression that you want the substitution to occur -in, it can be substituted as many times as possible, without getting negative -powers. - -An example clarifies it all (hopefully): - -@example -cout << (a*a*a*a+b*b*b*b+pow(x+y,4)).subs(wild()*wild()==pow(wild(),3), - subs_options::algebraic) << endl; -// --> (y+x)^6+b^6+a^6 - -cout << ((a+b+c)*(a+b+c)).subs(a+b==x,subs_options::algebraic) << endl; -// --> (c+b+a)^2 -// Powers and products are smart, but addition is just the same. - -cout << ((a+b+c)*(a+b+c)).subs(a+b+wild()==x+wild(), subs_options::algebraic) - << endl; -// --> (x+c)^2 -// As I said: addition is just the same. - -cout << (pow(a,5)*pow(b,7)+2*b).subs(b*b*a==x,subs_options::algebraic) << endl; -// --> x^3*b*a^2+2*b - -cout << (pow(a,-5)*pow(b,-7)+2*b).subs(1/(b*b*a)==x,subs_options::algebraic) - << endl; -// --> 2*b+x^3*b^(-1)*a^(-2) - -cout << (4*x*x*x-2*x*x+5*x-1).subs(x==a,subs_options::algebraic) << endl; -// --> -1-2*a^2+4*a^3+5*a - -cout << (4*x*x*x-2*x*x+5*x-1).subs(pow(x,wild())==pow(a,wild()), - subs_options::algebraic) << endl; -// --> -1+5*x+4*x^3-2*x^2 -// You should not really need this kind of patterns very often now. -// But perhaps this it's-not-a-bug-it's-a-feature (c/sh)ould still change. - -cout << ex(sin(1+sin(x))).subs(sin(wild())==cos(wild()), - subs_options::algebraic) << endl; -// --> cos(1+cos(x)) - -cout << expand((a*sin(x+y)*sin(x+y)+a*cos(x+y)*cos(x+y)+b) - .subs((pow(cos(wild()),2)==1-pow(sin(wild()),2)), - subs_options::algebraic)) << endl; -// --> b+a -@end example - - -@node Applying a Function on Subexpressions, Visitors and Tree Traversal, Pattern Matching and Advanced Substitutions, Methods and Functions +@subsection The option algebraic +Both @code{has()} and @code{subs()} take an optional argument to pass them +extra options. This section describes what happens if you give the former +the option @code{has_options::algebraic} or the latter +@code{subs:options::algebraic}. In that case the matching condition for +powers and multiplications is changed in such a way that they become +more intuitive. Intuition says that @code{x*y} is a part of @code{x*y*z}. +If you use these options you will find that +@code{(x*y*z).has(x*y, has_options::algebraic)} indeed returns true. +Besides matching some of the factors of a product also powers match as +often as is possible without getting negative exponents. For example +@code{(x^5*y^2*z).subs(x^2*y^2==c, subs_options::algebraic)} will return +@code{x*c^2*z}. This also works with negative powers: +@code{(x^(-3)*y^(-2)*z).subs(1/(x*y)==c, subs_options::algebraic)} will +return @code{x^(-1)*c^2*z}. Note that this only works for multiplications +and not for locating @code{x+y} within @code{x+y+z}. + + +@node Applying a function on subexpressions, Visitors and tree traversal, Pattern matching and advanced substitutions, Methods and functions @c node-name, next, previous, up -@section Applying a Function on Subexpressions +@section Applying a function on subexpressions @cindex tree traversal @cindex @code{map()} @@ -4786,9 +4749,9 @@ argument. You can not use functions like @samp{diff()}, @samp{op()}, @end example -@node Visitors and Tree Traversal, Polynomial Arithmetic, Applying a Function on Subexpressions, Methods and Functions +@node Visitors and tree traversal, Polynomial arithmetic, Applying a function on subexpressions, Methods and functions @c node-name, next, previous, up -@section Visitors and Tree Traversal +@section Visitors and tree traversal @cindex tree traversal @cindex @code{visitor} (class) @cindex @code{accept()} @@ -5008,10 +4971,26 @@ lst gather_indices(const ex & e) @end example -@node Polynomial Arithmetic, Rational Expressions, Visitors and Tree Traversal, Methods and Functions +@node Polynomial arithmetic, Rational expressions, Visitors and tree traversal, Methods and functions @c node-name, next, previous, up @section Polynomial arithmetic +@subsection Testing whether an expression is a polynomial +@cindex @code{is_polynomial()} + +Testing whether an expression is a polynomial in one or more variables +can be done with the method +@example +bool ex::is_polynomial(const ex & vars) const; +@end example +In the case of more than +one variable, the variables are given as a list. + +@example +(x*y*sin(y)).is_polynomial(x) // Returns true. +(x*y*sin(y)).is_polynomial(lst(x,y)) // Returns false. +@end example + @subsection Expanding and collecting @cindex @code{expand()} @cindex @code{collect()} @@ -5366,7 +5345,7 @@ Note also, how factors with the same exponents are not fully factorized with this method. -@node Rational Expressions, Symbolic Differentiation, Polynomial Arithmetic, Methods and Functions +@node Rational expressions, Symbolic differentiation, Polynomial arithmetic, Methods and functions @c node-name, next, previous, up @section Rational expressions @@ -5492,7 +5471,7 @@ The following more useful example will print @samp{sin(x)-cos(x)}: @end example -@node Symbolic Differentiation, Series Expansion, Rational Expressions, Methods and Functions +@node Symbolic differentiation, Series expansion, Rational expressions, Methods and functions @c node-name, next, previous, up @section Symbolic differentiation @cindex differentiation @@ -5558,7 +5537,7 @@ When you run it, it produces the sequence @code{1}, @code{-1}, @code{5}, @code{i} by two since all odd Euler numbers vanish anyways. -@node Series Expansion, Symmetrization, Symbolic Differentiation, Methods and Functions +@node Series expansion, Symmetrization, Symbolic differentiation, Methods and functions @c node-name, next, previous, up @section Series expansion @cindex @code{series()} @@ -5671,7 +5650,7 @@ program, it will type out: @end example -@node Symmetrization, Built-in Functions, Series Expansion, Methods and Functions +@node Symmetrization, Built-in functions, Series expansion, Methods and functions @c node-name, next, previous, up @section Symmetrization @cindex @code{symmetrize()} @@ -5717,7 +5696,7 @@ almost any kind of object (anything that is @code{subs()}able): @} @end example -@node Built-in Functions, Multiple polylogarithms, Symmetrization, Methods and Functions +@node Built-in functions, Multiple polylogarithms, Symmetrization, Methods and functions @c node-name, next, previous, up @section Predefined mathematical functions @c @@ -5731,12 +5710,20 @@ GiNaC contains the following predefined mathematical functions: @item @code{abs(x)} @tab absolute value @cindex @code{abs()} +@item @code{step(x)} +@tab step function +@cindex @code{step()} @item @code{csgn(x)} @tab complex sign @cindex @code{conjugate()} @item @code{conjugate(x)} @tab complex conjugation -@cindex @code{csgn()} +@cindex @code{real_part()} +@item @code{real_part(x)} +@tab real part +@cindex @code{imag_part()} +@item @code{imag_part(x)} +@tab imaginary part @item @code{sqrt(x)} @tab square root (not a GiNaC function, rather an alias for @code{pow(x, numeric(1, 2))}) @cindex @code{sqrt()} @@ -5853,7 +5840,7 @@ 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. -@node Multiple polylogarithms, Complex Conjugation, Built-in Functions, Methods and Functions +@node Multiple polylogarithms, Complex expressions, Built-in functions, Methods and functions @c node-name, next, previous, up @subsection Multiple polylogarithms @@ -6013,21 +6000,32 @@ J.Borwein, D.Bradley, D.Broadhurst, P.Lisonek, Trans.Amer.Math.Soc. 353/3 (2001) @cite{Numerical Evaluation of Multiple Polylogarithms}, J.Vollinga, S.Weinzierl, hep-ph/0410259 -@node Complex Conjugation, Solving Linear Systems of Equations, Multiple polylogarithms, Methods and Functions +@node Complex expressions, Solving linear systems of equations, Multiple polylogarithms, Methods and functions @c node-name, next, previous, up -@section Complex Conjugation +@section Complex expressions @c @cindex @code{conjugate()} -The method +For dealing with complex expressions there are the methods @example ex ex::conjugate(); +ex ex::real_part(); +ex ex::imag_part(); @end example -returns the complex conjugate of the expression. For all built-in functions and objects the -conjugation gives the expected results: +that return respectively the complex conjugate, the real part and the +imaginary part of an expression. Complex conjugation works as expected +for all built-in functinos and objects. Taking real and imaginary +parts has not yet been implemented for all built-in functions. In cases where +it is not known how to conjugate or take a real/imaginary part one +of the functions @code{conjugate}, @code{real_part} or @code{imag_part} +is returned. For instance, in case of a complex symbol @code{x} +(symbols are complex by default), one could not simplify +@code{conjugate(x)}. In the case of strings of gamma matrices, +the @code{conjugate} method takes the Dirac conjugate. +For example, @example @{ varidx a(symbol("a"), 4), b(symbol("b"), 4); @@ -6041,15 +6039,16 @@ conjugation gives the expected results: @} @end example -For symbols in the complex domain the conjugation can not be evaluated and the GiNaC function -@code{conjugate} is returned. GiNaC functions conjugate by applying the conjugation to their -arguments. This is the default strategy. If you want to define your own functions and 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). +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. -@node Solving Linear Systems of Equations, Input/Output, Complex Conjugation, Methods and Functions +@node Solving linear systems of equations, Input/output, Complex expressions, Methods and functions @c node-name, next, previous, up -@section Solving Linear Systems of Equations +@section Solving linear systems of equations @cindex @code{lsolve()} The function @code{lsolve()} provides a convenient wrapper around some @@ -6063,7 +6062,7 @@ ex lsolve(const ex & eqns, const ex & symbols, Here, @code{eqns} is a @code{lst} of equalities (i.e. class @code{relational}) while @code{symbols} is a @code{lst} of -indeterminates. (@xref{The Class Hierarchy}, for an exposition of class +indeterminates. (@xref{The class hierarchy}, for an exposition of class @code{lst}). It returns the @code{lst} of solutions as an expression. As an example, @@ -6088,7 +6087,7 @@ to @code{lsolve()}: it accepts the same parameters as around that method. -@node Input/Output, Extending GiNaC, Solving Linear Systems of Equations, Methods and Functions +@node Input/output, Extending GiNaC, Solving linear systems of equations, Methods and functions @c node-name, next, previous, up @section Input and output of expressions @cindex I/O @@ -6530,7 +6529,7 @@ Be warned, however, that the set of properties and their meaning for each class may change between GiNaC versions. -@node Extending GiNaC, What does not belong into GiNaC, Input/Output, Top +@node Extending GiNaC, What does not belong into GiNaC, Input/output, Top @c node-name, next, previous, up @chapter Extending GiNaC @@ -6888,7 +6887,7 @@ code for the @code{psi()} function (@file{inifcns.h} and @section GiNaC's expression output system GiNaC allows the output of expressions in a variety of different formats -(@pxref{Input/Output}). This section will explain how expression output +(@pxref{Input/output}). This section will explain how expression output is implemented internally, and how to define your own output formats or change the output format of built-in algebraic objects. You will also want to read this section if you plan to write your own algebraic classes or @@ -7570,7 +7569,7 @@ Note that the unarchiving constructor is @code{sprod::structure} and not @code{sprod::unarchive()} function. -@node Adding classes, A Comparison With Other CAS, Structures, Extending GiNaC +@node Adding classes, A comparison with other CAS, Structures, Extending GiNaC @c node-name, next, previous, up @section Adding classes @@ -7854,7 +7853,7 @@ ex e = mystring("Hello, world!"); cout << is_a(e) << endl; // -> 1 (true) -cout << e.bp->class_name() << endl; +cout << ex_to(e).class_name() << endl; // -> mystring @end example @@ -8078,7 +8077,7 @@ should become a need. That's it. May the source be with you! -@node A Comparison With Other CAS, Advantages, Adding classes, Top +@node A comparison with other CAS, Advantages, Adding classes, Top @c node-name, next, previous, up @chapter A Comparison With Other CAS @cindex advocacy @@ -8094,7 +8093,7 @@ disadvantages over these systems. * Why C++?:: Attractiveness of C++. @end menu -@node Advantages, Disadvantages, A Comparison With Other CAS, A Comparison With Other CAS +@node Advantages, Disadvantages, A comparison with other CAS, A comparison with other CAS @c node-name, next, previous, up @section Advantages @@ -8174,7 +8173,7 @@ speed with other CAS. @end itemize -@node Disadvantages, Why C++?, Advantages, A Comparison With Other CAS +@node Disadvantages, Why C++?, Advantages, A comparison with other CAS @c node-name, next, previous, up @section Disadvantages @@ -8209,7 +8208,7 @@ yet ANSI compliant, support all needed features. @end itemize -@node Why C++?, Internal Structures, Disadvantages, A Comparison With Other CAS +@node Why C++?, Internal structures, Disadvantages, A comparison with other CAS @c node-name, next, previous, up @section Why C++? @@ -8226,16 +8225,16 @@ Furthermore, the main developers are more familiar with C++ than with any other programming language. -@node Internal Structures, Expressions are reference counted, Why C++? , Top +@node Internal structures, Expressions are reference counted, Why C++? , Top @c node-name, next, previous, up -@appendix Internal Structures +@appendix Internal structures @menu * Expressions are reference counted:: * Internal representation of products and sums:: @end menu -@node Expressions are reference counted, Internal representation of products and sums, Internal Structures, Internal Structures +@node Expressions are reference counted, Internal representation of products and sums, Internal structures, Internal structures @c node-name, next, previous, up @appendixsection Expressions are reference counted @@ -8324,7 +8323,7 @@ Marshall Cline. Chapter 16 covers this issue and presents an implementation which is pretty close to the one in GiNaC. -@node Internal representation of products and sums, Package Tools, Expressions are reference counted, Internal Structures +@node Internal representation of products and sums, Package tools, Expressions are reference counted, Internal structures @c node-name, next, previous, up @appendixsection Internal representation of products and sums @@ -8392,9 +8391,9 @@ expansion and the like are reimplemented for @code{add} and @code{mul}, but the data structure is inherited from @code{expairseq}. -@node Package Tools, ginac-config, Internal representation of products and sums, Top +@node Package tools, ginac-config, Internal representation of products and sums, Top @c node-name, next, previous, up -@appendix Package Tools +@appendix Package tools If you are creating a software package that uses the GiNaC library, setting the correct command line options for the compiler and linker @@ -8406,7 +8405,7 @@ can be difficult. GiNaC includes two tools to make this process easier. @end menu -@node ginac-config, AM_PATH_GINAC, Package Tools, Package Tools +@node ginac-config, AM_PATH_GINAC, Package tools, Package tools @c node-name, next, previous, up @section @command{ginac-config} @cindex ginac-config @@ -8453,7 +8452,7 @@ Not only is the form using @command{ginac-config} easier to type, it will work on any system, no matter how GiNaC was configured. -@node AM_PATH_GINAC, Configure script options, ginac-config, Package Tools +@node AM_PATH_GINAC, Configure script options, ginac-config, Package tools @c node-name, next, previous, up @section @samp{AM_PATH_GINAC} @cindex AM_PATH_GINAC @@ -8666,7 +8665,7 @@ $ make install @end example -@node Bibliography, Concept Index, Example package, Top +@node Bibliography, Concept index, Example package, Top @c node-name, next, previous, up @appendix Bibliography @@ -8711,9 +8710,9 @@ ISBN 3-540-66572-2, 2001, Springer, Heidelberg @end itemize -@node Concept Index, , Bibliography, Top +@node Concept index, , Bibliography, Top @c node-name, next, previous, up -@unnumbered Concept Index +@unnumbered Concept index @printindex cp