X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=ad044074eb19bed8933314c00d0b0d622ed49812;hp=ca952ebe82756d06259268901475b80d6acc50c8;hb=6de869e3c497de0a136c2905b2dcc248d1e7b7fb;hpb=438e3ba56f3e9172f234df57e7c59f95353e4eaf diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index ca952ebe..ad044074 100644 --- a/doc/tutorial/ginac.texi +++ b/doc/tutorial/ginac.texi @@ -684,8 +684,8 @@ ex MyEx4 = sin(x + 2*y) + 3*z + 41; // containing a function ex MyEx5 = MyEx4 + 1; // similar to above @end example -Expressions are handles to other more fundamental objects, that many -times contain other expressions thus creating a tree of expressions +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 @code{ex} therefore run top-down through such an expression tree. For example, the method @code{has()} scans recursively for occurrences of @@ -707,36 +707,26 @@ mathematical objects, all of which (except for @code{ex} and some helpers) are internally derived from one abstract base class called @code{basic}. You do not have to deal with objects of class @code{basic}, instead you'll be dealing with symbols, numbers, -containers of expressions and so on. You'll soon learn in this chapter -how many of the functions on symbols are really classes. This is -because simple symbolic arithmetic is not supported by languages like -C++ so in a certain way GiNaC has to implement its own arithmetic. +containers of expressions and so on. @cindex container @cindex atom To get an idea about what kinds of symbolic composits may be built we -have a look at the most important classes in the class hierarchy. The -oval classes are atomic ones and the squared classes are containers. -The dashed line symbolizes a `points to' or `handles' relationship while -the solid lines stand for `inherits from' relationship in the class -hierarchy: +have a look at the most important classes in the class hierarchy and +some of the relations among the classes: @image{classhierarchy} -Some of the classes shown here (the ones sitting in white boxes) are -abstract base classes that are of no interest at all for the user. They -are used internally in order to avoid code duplication if two or more -classes derived from them share certain features. An example would be -@code{expairseq}, which is 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 of terms and products, respectively. -@xref{Internal Structures}, where these two classes are described in -more detail. - -At this point, we only summarize what kind of mathematical objects are -stored in the different classes in above diagram in order to give you a -overview: +The abstract classes shown here (the ones without drop-shadow) are of no +interest for the user. They are used internally in order to avoid code +duplication if two or more classes derived from them share certain +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 +following table shortly summarizes what kinds of mathematical objects +are stored in the different classes: @cartouche @multitable @columnfractions .22 .78 @@ -749,8 +739,8 @@ $\pi$ @math{Pi} @end ifnottex @item @code{numeric} @tab All kinds of numbers, @math{42}, @math{7/3*I}, @math{3.14159}@dots{} -@item @code{add} @tab Sums like @math{x+y} or @math{a+(2*b)+3} -@item @code{mul} @tab Products like @math{x*y} or @math{a*(x+y+z)*b*2} +@item @code{add} @tab Sums like @math{x+y} or @math{a-(2*b)+3} +@item @code{mul} @tab Products like @math{x*y} or @math{2*a^2*(x+y+z)/b} @item @code{power} @tab Exponentials such as @math{x^2}, @math{a^b}, @tex $\sqrt{2}$ @@ -759,15 +749,14 @@ $\sqrt{2}$ @code{sqrt(}@math{2}@code{)} @end ifnottex @dots{} -@item @code{pseries} @tab Power Series, e.g. @math{x+1/6*x^3+1/120*x^5+O(x^7)} +@item @code{pseries} @tab Power Series, e.g. @math{x-1/6*x^3+1/120*x^5+O(x^7)} @item @code{function} @tab A symbolic function like @math{sin(2*x)} @item @code{lst} @tab Lists of expressions [@math{x}, @math{2*y}, @math{3+z}] @item @code{matrix} @tab @math{n}x@math{m} matrices of expressions @item @code{relational} @tab A relation like the identity @math{x}@code{==}@math{y} -@item @code{color} @tab Element of the @math{SU(3)} Lie-algebra +@item @code{color}, @code{coloridx} @tab Element and index of the @math{SU(3)} Lie-algebra @item @code{isospin} @tab Element of the @math{SU(2)} Lie-algebra -@item @code{idx} @tab Index of a tensor object -@item @code{coloridx} @tab Index of a @math{SU(3)} tensor +@item @code{idx} @tab Index of a general tensor object @end multitable @end cartouche @@ -1232,13 +1221,19 @@ a relation between them that signals equality, inequality and so on. They are created by simply using the C++ operators @code{==}, @code{!=}, @code{<}, @code{<=}, @code{>} and @code{>=} between two expressions. -@xref{Mathematical functions}, for examples where various applications of -the @code{.subs()} method show how objects of class relational are used -as arguments. There they provide an intuitive syntax for substitutions. -They can also used for creating systems of equations that are to be -solved for unknown variables. More applications of this class will -appear throughout the next chapters. - +@xref{Mathematical functions}, for examples where various applications +of the @code{.subs()} method show how objects of class relational are +used as arguments. There they provide an intuitive syntax for +substitutions. They are also used as arguments to the @code{ex::series} +method, where the left hand side of the relation specifies the variable +to expand in and the right hand side the expansion point. They can also +be used for creating systems of equations that are to be solved for +unknown variables. But the most common usage of objects of this class +is rather inconspicuous in statements of the form @code{if +(expand(pow(a+b,2))==a*a+2*a*b+b*b) @{...@}}. Here, an implicit +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 Methods and Functions, Information About Expressions, Relations, Top @@ -1402,7 +1397,9 @@ table: @item @code{crational_polynomial} @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 +@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 @@ -1474,7 +1471,7 @@ bool ex::is_zero(); for checking whether one expression is equal to another, or equal to zero, respectively. -@strong{Warning:} You will also find a @code{ex::compare()} method in the +@strong{Warning:} You will also find an @code{ex::compare()} method in the GiNaC header files. This method is however only to be used internally by GiNaC to establish a canonical sort order for terms, and using it to compare expressions will give very surprising results. @@ -2091,8 +2088,8 @@ The easiest way to print an expression is to write it to a stream: @example @{ symbol x("x"); - ex e = 7+4.2*pow(x,2); - cout << e << endl; // prints '7+4.2*x^2' + ex e = 4.5+pow(x,2)*3/2; + cout << e << endl; // prints '4.5+3/2*x^2' // ... @end example @@ -2123,9 +2120,9 @@ and mostly affect the way in which floating point numbers are written: The above example will produce (note the @code{x^2} being converted to @code{x*x}): @example -float f = 4.200000e+00*(x*x)+7.000000e+00; -double d = 4.200000e+00*(x*x)+7.000000e+00; -cl_N n = cl_F("4.2000000000000001776")*(x*x)+cl_F("7.0"); +float f = (3.000000e+00/2.000000e+00)*(x*x)+4.500000e+00; +double d = (3.000000e+00/2.000000e+00)*(x*x)+4.500000e+00; +cl_N n = (cl_F("3.0")/cl_F("2.0"))*(x*x)+cl_F("4.5"); @end example Finally, there are the two methods @code{printraw()} and @code{printtree()} intended for GiNaC @@ -2142,16 +2139,16 @@ debugging purposes: produces @example -ex(+((power(ex(symbol(name=x,serial=1,hash=150875740,flags=11)),ex(numeric(2)),hash=2,flags=3),numeric(4.2000000000000001776L0)),,hash=0,flags=3)) +ex(+((power(ex(symbol(name=x,serial=1,hash=150875740,flags=11)),ex(numeric(2)),hash=2,flags=3),numeric(3/2)),,hash=0,flags=3)) type=Q25GiNaC3add, hash=0 (0x0), flags=3, nops=2 power: hash=2 (0x2), flags=3 x (symbol): serial=1, hash=150875740 (0x8fe2e5c), flags=11 2 (numeric): hash=2147483714 (0x80000042), flags=11 - 4.2000000000000001776L0 (numeric): hash=3006477126 (0xb3333346), flags=11 + 3/2 (numeric): hash=2147483745 (0x80000061), flags=11 ----- overall_coeff - 7 (numeric): hash=2147483763 (0x80000073), flags=11 + 4.5L0 (numeric): hash=2147483723 (0x8000004b), flags=11 ===== @end example @@ -2344,11 +2341,13 @@ provided by @acronym{CLN} are much better suited. @section Symbolic functions The easiest and most instructive way to start with is probably to -implement your own function. Objects of class @code{function} are -inserted into the system via a kind of `registry'. They get a serial -number that is used internally to identify them but you usually need not -worry about this. What you have to care for are functions that are -called when the user invokes certain methods. These are usual +implement your own function. GiNaC's functions are objects of class +@code{function}. The preprocessor is then used to convert the function +names to objects with a corresponding serial number that is used +internally to identify them. You usually need not worry about this +number. New functions may be inserted into the system via a kind of +`registry'. It is your responsibility to care for some functions that +are called when the user invokes certain methods. These are usual C++-functions accepting a number of @code{ex} as arguments and returning one @code{ex}. As an example, if we have a look at a simplified implementation of the cosine trigonometric function, we first need a