X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=04b8908ddf536511abf27102e3971fc302033441;hb=20e7104d50663d8c616d9a43e1012ab543ffb5a9;hp=f69d45107968ec0d2943d05179d43817aeb61efc;hpb=a6bb52b00bf185271774e7d56215923700a3ec40;p=ginac.git diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index f69d4510..04b8908d 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 Johannes Gutenberg University Mainz, Germany +Copyright (C) 1999-2000 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 Johannes Gutenberg University Mainz, Germany +Copyright @copyright{} 1999-2000 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,8 +135,8 @@ the near future. @section License The GiNaC framework for symbolic computation within the C++ programming -language is Copyright @copyright{} 1999 Johannes Gutenberg University Mainz, -Germany. +language is Copyright @copyright{} 1999-2000 Johannes Gutenberg +University Mainz, Germany. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as @@ -389,7 +389,7 @@ previously evaluated element from @command{ginsh}'s internal stack. If you ever wanted to convert units in C or C++ and found this is cumbersome, here is the solution. Symbolic types can always be used as tags for different types of objects. Converting from wrong units to the -metric system is therefore easy: +metric system is now easy: @example > in=.0254*m; @@ -636,6 +636,7 @@ meta-class for storing all mathematical objects. * Fundamental containers:: The power, add and mul classes. * Built-in functions:: Mathematical functions. * Relations:: Equality, Inequality and all that. +* Archiving:: Storing expression libraries in files. @end menu @@ -709,11 +710,47 @@ consisting of one expression and a number (@code{numeric}). What @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: + +@cartouche +@multitable @columnfractions .22 .78 +@item @code{symbol} @tab Algebraic symbols @math{a}, @math{x}, @math{y}@dots{} +@item @code{constant} @tab Constants like +@tex +$\pi$ +@end tex +@ifnottex +@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{power} @tab Exponentials such as @math{x^2}, @math{a^b}, +@tex +$\sqrt{2}$ +@end tex +@ifnottex +@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{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{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 +@end multitable +@end cartouche @node Symbols, Numbers, The Class Hierarchy, Basic Concepts @c node-name, next, previous, up @section Symbols -@cindex Symbols (class @code{symbol}) +@cindex @code{symbol} (class) @cindex hierarchy of classes @cindex atom @@ -752,7 +789,7 @@ can use the expression's @code{.subs()} method. @node Numbers, Constants, Symbols, Basic Concepts @c node-name, next, previous, up @section Numbers -@cindex numbers (class @code{numeric}) +@cindex @code{numeric} (class) @cindex GMP @cindex CLN @@ -950,7 +987,7 @@ following table. @node Constants, Fundamental containers, Numbers, Basic Concepts @c node-name, next, previous, up @section Constants -@cindex constants (class @code{constant}) +@cindex @code{constant} (class) @cindex @code{Pi} @cindex @code{Catalan} @@ -1065,7 +1102,7 @@ canonical form. @node Built-in functions, Relations, Fundamental containers, Basic Concepts @c node-name, next, previous, up @section Built-in functions -@cindex functions (class @code{function}) +@cindex @code{function} (class) @cindex trigonometric function @cindex hyperbolic function @@ -1117,10 +1154,10 @@ expansion and so on. Read the next chapter in order to learn more about this. -@node Relations, Important Algorithms, Built-in functions, Basic Concepts +@node Relations, Archiving, Built-in functions, Basic Concepts @c node-name, next, previous, up @section Relations -@cindex relations (class @code{relational}) +@cindex @code{relational} (class) Sometimes, a relation holding between two expressions must be stored somehow. The class @code{relational} is a convenient container for such @@ -1134,7 +1171,98 @@ the @code{.subs()} method show how objects of class relational are used as arguments. There they provide an intuitive syntax for substitutions. -@node Important Algorithms, Polynomial Expansion, Relations, Top +@node Archiving, Important Algorithms, Relations, Basic Concepts +@c node-name, next, previous, up +@section Archiving Expressions +@cindex I/O +@cindex @code{archive} (class) + +GiNaC allows creating @dfn{archives} of expressions which can be stored +to or retrieved from files. To create an archive, you declare an object +of class @code{archive} and archive expressions in it, giving each +expressions a unique name: + +@example +#include +#include +using namespace GiNaC; + +int main() +@{ + symbol x("x"), y("y"), z("z"); + + ex foo = sin(x + 2*y) + 3*z + 41; + ex bar = foo + 1; + + archive a; + a.archive_ex(foo, "foo"); + a.archive_ex(bar, "the second one"); + // ... +@end example + +The archive can then be written to a file: + +@example + // ... + ofstream out("foobar.gar"); + out << a; + out.close(); + // ... +@end example + +The file @file{foobar.gar} contains all information that is needed to +reconstruct the expressions @code{foo} and @code{bar}. + +@cindex @command{viewgar} +The tool @command{viewgar} that comes with GiNaC can be used to view +the contents of GiNaC archive files: + +@example +$ viewgar foobar.gar +foo = 41+sin(x+2*y)+3*z +the second one = 42+sin(x+2*y)+3*z +@end example + +The point of writing archive files is of course that they can later be +read in again: + +@example + // ... + archive a2; + ifstream in("foobar.gar"); + in >> a2; + // ... +@end example + +And the stored expressions can be retrieved by their name: + +@example + // ... + lst syms; + syms.append(x); syms.append(y); + + ex ex1 = a2.unarchive_ex(syms, "foo"); + ex ex2 = a2.unarchive_ex(syms, "the second one"); + + cout << ex1 << endl; // prints "41+sin(x+2*y)+3*z" + cout << ex2 << endl; // prints "42+sin(x+2*y)+3*z" + cout << ex1.subs(x == 2) << endl; // prints "41+sin(2+2*y)+3*z" + // ... +@} +@end example + +Note that you have to supply a list of the symbols which are to be inserted +in the expressions. Symbols in archives are stored by their name only and +if you don't specify which symbols you have, unarchiving the expression will +create new symbols with that name. E.g. if you hadn't included @code{x} in +the @code{syms} list above, the @code{ex1.subs(x == 2)} statement would +have had no effect because the @code{x} in @code{ex1} would have been a +different symbol than the @code{x} which was defined at the beginning of +the program, altough both would appear as @samp{x} when printed. + + + +@node Important Algorithms, Polynomial Expansion, Archiving, Top @c node-name, next, previous, up @chapter Important Algorithms @cindex polynomial @@ -1226,7 +1354,7 @@ being polynomials in the remaining variables. The method @code{collect()} accomplishes this task. Here is its declaration: @example -ex ex::collect(symbol const & s); +ex ex::collect(const symbol & s); @end example Note that the original polynomial needs to be in expanded form in order @@ -1236,8 +1364,8 @@ coefficients can be checked using the two methods @cindex @code{degree()} @cindex @code{ldegree()} @example -int ex::degree(symbol const & s); -int ex::ldegree(symbol const & s); +int ex::degree(const symbol & s); +int ex::ldegree(const symbol & s); @end example where @code{degree()} returns the highest coefficient and @@ -1428,19 +1556,20 @@ When you run it, it produces the sequence @code{1}, @code{-1}, @code{5}, @node Series Expansion, Extending GiNaC, Symbolic Differentiation, Important Algorithms @c node-name, next, previous, up @section Series Expansion -@cindex series expansion +@cindex @code{series()} @cindex Taylor expansion @cindex Laurent expansion +@cindex @code{pseries} (class) Expressions know how to expand themselves as a Taylor series or (more generally) a Laurent series. As in most conventional Computer Algebra Systems, no distinction is made between those two. There is a class of -its own for storing such series as well as a class for storing the order -of the series. As a consequence, if you want to work with series, -i.e. multiply two series, you need to call the method @code{ex::series} -again to convert it to a series object with the usual structure -(expansion plus order term). A sample application from special -relativity could read: +its own for storing such series (@code{class pseries}) and a built-in +function (called @code{Order}) for storing the order term of the series. +As a consequence, if you want to work with series, i.e. multiply two +series, you need to call the method @code{ex::series} again to convert +it to a series object with the usual structure (expansion plus order +term). A sample application from special relativity could read: @example #include @@ -1587,7 +1716,7 @@ function that is called when one wishes to @code{eval} it. It could look something like this: @example -static ex cos_eval_method(ex const & x) +static ex cos_eval_method(const ex & x) @{ // if (!x%(2*Pi)) return 1 // if (!x%Pi) return -1 @@ -1606,7 +1735,7 @@ lazy we sweep the problem under the rug by calling someone else's function that does so, in this case the one in class @code{numeric}: @example -static ex cos_evalf_method(ex const & x) +static ex cos_evalf_method(const ex & x) @{ return sin(ex_to_numeric(x)); @} @@ -1616,7 +1745,7 @@ Differentiation will surely turn up and so we need to tell @code{sin} how to differentiate itself: @example -static ex cos_diff_method(ex const & x, unsigned diff_param) +static ex cos_diff_method(const ex & x, unsigned diff_param) @{ return cos(x); @}