X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=doc%2Ftutorial%2Fginac.texi;h=5a7ad9dfa2803db940a351a8fc61e2a128c028df;hp=e6d2d1a140b9f59cf44ad63b015820763b97adb3;hb=b0265215a51a081d20fe68475e080716afc2d45a;hpb=cf7ab73a8d4bda4516f28e24d53d9fabc4b95d09 diff --git a/doc/tutorial/ginac.texi b/doc/tutorial/ginac.texi index e6d2d1a1..5a7ad9df 100644 --- a/doc/tutorial/ginac.texi +++ b/doc/tutorial/ginac.texi @@ -86,6 +86,7 @@ framework for symbolic computation within the C++ programming language. * 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. * Bibliography:: * Concept Index:: @end menu @@ -203,6 +204,9 @@ $ ./hello 355687428096000*x*y+20922789888000*y^2+6402373705728000*x^2 @end example +(@xref{Package Tools}, for tools that help you when creating a software +package that uses GiNaC.) + @cindex Hermite polynomial Next, there is a more meaningful C++ program that calls a function which generates Hermite polynomials in a specified free variable. @@ -356,9 +360,9 @@ polynomials): 3*y^2+x^2 @end example -You can differentiate functions and expand them as Taylor or -Laurent series (the third argument of series is the evaluation point, -the fourth defines the order): +You can differentiate functions and expand them as Taylor or Laurent +series (the third argument of @code{series} is the evaluation point, the +fourth defines the order): @example > diff(tan(x),x); @@ -367,6 +371,9 @@ tan(x)^2+1 x-1/6*x^3+Order(x^4) > series(1/tan(x),x,0,4); x^(-1)-1/3*x+Order(x^2) +> series(gamma(2*sin(x)-2),x,Pi/2,6); +-(x-1/2*Pi)^(-2)+(-1/12*Pi^2-1/2*EulerGamma^2-1/240)*(x-1/2*Pi)^2 +-EulerGamma-1/12+Order((x-1/2*Pi)^3) @end example If you ever wanted to convert units in C or C++ and found this @@ -600,6 +607,7 @@ configuration again with the same @var{PREFIX} thus creating a do it by hand since you now know where all the files went during installation.}. + @node Basic Concepts, Expressions, Installing GiNaC, Top @c node-name, next, previous, up @chapter Basic Concepts @@ -642,7 +650,7 @@ ex MyEx5 = MyEx4 + 1; // similar to above Expressions are handles to other more fundamental objects, that many times 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} @@ -670,8 +678,9 @@ implement its own arithmetic. To give 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 -dashed line symbolizes a "points to" or "handles" relationship while the -solid lines stand for "inherits from" relationship in the class +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: @image{classhierarchy} @@ -907,9 +916,13 @@ following table. @item @code{.is_prime()} @tab object is a prime integer (probabilistic primality test) @item @code{.is_rational()} -@tab object is an exact rational number (integers are rational, too, as are complex extensions like @math{2/3+7/2*I}) +@tab object is an exact rational number (integers are rational, too) @item @code{.is_real()} @tab object is a real integer, rational or float (i.e. is not complex) +@item @code{.is_cinteger()} +@tab object is a (complex) integer, such as @math{2-3*I} +@item @code{.is_crational()} +@tab object is an exact (complex) rational number (such as @math{2/3+7/2*I}) @end multitable @end cartouche @@ -1561,9 +1574,15 @@ REGISTER_FUNCTION(cos, cos_eval_method, cos_evalf_method, cos_diff, NULL); The first argument is the function's name, the second, third and fourth bind the corresponding methods to this objects and the fifth is a slot -for inserting a method for series expansion. Also, the new function -needs to be declared somewhere. This may also be done by a convenient -preprocessor macro: +for inserting a method for series expansion. (If set to @code{NULL} it +defaults to simple Taylor expansion, which is correct if there are no +poles involved. The way GiNaC handles poles in case there are any is +best understood by studying one of the examples, like the Gamma function +for instance. In essence the function first checks if there is a pole +at the evaluation point and falls back to Taylor expansion if there +isn't. Then, the pole is regularized by some suitable transformation.) +Also, the new function needs to be declared somewhere. This may also be +done by a convenient preprocessor macro: @example DECLARE_FUNCTION_1P(cos) @@ -1802,7 +1821,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, Bibliography, 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 @@ -1870,8 +1889,281 @@ 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 +@c node-name, next, previous, up +@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 +can be difficult. GiNaC includes two tools to make this process easier. + +@menu +* ginac-config:: A shell script to detect compiler and linker flags. +* AM_PATH_GINAC:: Macro for GNU automake. +@end menu + + +@node ginac-config, AM_PATH_GINAC, Package Tools, Package Tools +@c node-name, next, previous, up +@section @command{ginac-config} +@cindex ginac-config + +@command{ginac-config} is a shell script that you can use to determine +the compiler and linker command line options required to compile and +link a program with the GiNaC library. + +@command{ginac-config} takes the following flags: + +@table @samp +@item --version +Prints out the version of GiNaC installed. +@item --cppflags +Prints '-I' flags pointing to the installed header files. +@item --libs +Prints out the linker flags necessary to link a program against GiNaC. +@item --prefix[=@var{PREFIX}] +If @var{PREFIX} is specified, overrides the configured value of @env{$prefix}. +(And of exec-prefix, unless --exec-prefix is also specified) +Otherwise, prints out the configured value of @env{$prefix}. +@item --exec-prefix[=@var{PREFIX}] +If @var{PREFIX} is specified, overrides the configured value of @env{$exec_prefix}. +Otherwise, prints out the configured value of @env{$exec_prefix}. +@end table + +Typically, @command{ginac-config} will be used within a configure script, +as described below. It, however, can also be used directly +from the command line to compile a simple program. For example: + +@example +c++ -o simple `ginac-config --cppflags` simple.cpp `ginac-config --libs` +@end example + +This command line might expand to (for example): + +@example +cc -o simple -I/usr/local/include simple.cpp -L/usr/local/lib \ + -lginac -lcln -lstdc++ +@end example + +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 +@c node-name, next, previous, up +@section @samp{AM_PATH_GINAC} +@cindex AM_PATH_GINAC + +For packages configured using GNU automake, GiNaC also provides +a macro to automate the process of checking for GiNaC. + +@example +AM_PATH_GINAC([@var{MINIMUM-VERSION}, [@var{ACTION-IF-FOUND} [, @var{ACTION-IF-NOT-FOUND}]]]) +@end example + +This macro: + +@itemize @bullet + +@item +Determines the location of GiNaC using @command{ginac-config}, which is +either found in the user's path, or from the environment variable +@env{GINACLIB_CONFIG}. + +@item +Tests the installed libraries to make sure that there version +is later than @var{MINIMUM-VERSION}. (A default version will be used +if not specified) + +@item +If the required version was found, sets the @env{GINACLIB_CPPFLAGS} variable +to the output of @command{ginac-config --cppflags} and the @env{GINACLIB_LIBS} +variable to the output of @command{ginac-config --libs}, and calls +@samp{AC_SUBST()} for these variables so they can be used in generated +makefiles, and then executes @var{ACTION-IF-FOUND}. + +@item +If the required version was not found, sets @env{GINACLIB_CPPFLAGS} and +@env{GINACLIB_LIBS} to empty strings, and executes @var{ACTION-IF-NOT-FOUND}. + +@end itemize + +This macro is in file @file{ginac.m4} which is installed in +@file{$datadir/aclocal}. Note that if automake was installed with a +different @samp{--prefix} than GiNaC, you will either have to manually +move @file{ginac.m4} to automake's @file{$datadir/aclocal}, or give +aclocal the @samp{-I} option when running it. + +@menu +* Configure script options:: Configuring a package that uses AM_PATH_GINAC. +* Example package:: Example of a package using AM_PATH_GINAC. +@end menu + + +@node Configure script options, Example package, AM_PATH_GINAC, AM_PATH_GINAC +@c node-name, next, previous, up +@subsection Configuring a package that uses @samp{AM_PATH_GINAC} + +Simply make sure that @command{ginac-config} is in your path, and run +the configure script. + +Notes: + +@itemize @bullet + +@item +The directory where the GiNaC libraries are installed needs +to be found by your system's dynamic linker. + +This is generally done by + +@display +editing @file{/etc/ld.so.conf} and running @command{ldconfig} +@end display + +or by + +@display +setting the environment variable @env{LD_LIBRARY_PATH}, +@end display + +or, as a last resort, + +@display +giving a @samp{-R} or @samp{-rpath} flag (depending on your linker) when +running configure, for instance: + +@example +LDFLAGS=-R/home/cbauer/lib ./configure +@end example +@end display + +@item +You can also specify a @command{ginac-config} not in your path by +setting the @env{GINACLIB_CONFIG} environment variable to the +name of the executable + +@item +If you move the GiNaC package from its installed location, +you will need either need to modify @command{ginac-config} script +manually to point to the new location or rebuild GiNaC. + +@end itemize + +Advanced note: + +@itemize @bullet +@item +configure flags + +@example +--with-ginac-prefix=@var{PREFIX} +--with-ginac-exec-prefix=@var{PREFIX} +@end example + +are provided to override the prefix and exec-prefix that were stored +in the @command{ginac-config} shell script by GiNaC's configure. You are +generally better off configuring GiNaC with the right path to begin with. +@end itemize + + +@node Example package, Bibliography, Configure script options, AM_PATH_GINAC +@c node-name, next, previous, up +@subsection Example of a package using @samp{AM_PATH_GINAC} + +The following shows how to build a simple package using automake +and the @samp{AM_PATH_GINAC} macro. The program used here is @file{simple.cpp}: + +@example +#include +using namespace GiNaC; + +int main(void) +@{ + symbol x("x"); + ex a = sin(x); + cout << "Derivative of " << a << " is " << a.diff(x) << endl; + return 0; +@} +@end example + +You should first read the introductory portions of the automake +Manual, if you are not already familiar with it. + +Two files are needed, @file{configure.in}, which is used to build the +configure script: + +@example +dnl Process this file with autoconf to produce a configure script. +AC_INIT(simple.cpp) +AM_INIT_AUTOMAKE(simple.cpp, 1.0.0) + +AC_PROG_CXX +AC_PROG_INSTALL +AC_LANG_CPLUSPLUS + +AM_PATH_GINAC(0.4.0, [ + LIBS="$LIBS $GINACLIB_LIBS" + CPPFLAGS="$CFLAGS $GINACLIB_CPPFLAGS" +], AC_MSG_ERROR([need to have GiNaC installed])) + +AC_OUTPUT(Makefile) +@end example + +The only command in this which is not standard for automake +is the @samp{AM_PATH_GINAC} macro. + +That command does the following: + +@display +If a GiNaC version greater than 0.4.0 is found, adds @env{$GINACLIB_LIBS} to +@env{$LIBS} and @env{$GINACLIB_CPPFLAGS} to @env{$CPPFLAGS}. Otherwise, dies +with the error message "need to have GiNaC installed" +@end display + +And the @file{Makefile.am}, which will be used to build the Makefile. + +@example +## Process this file with automake to produce Makefile.in +bin_PROGRAMS = simple +simple_SOURCES = simple.cpp +@end example + +This @file{Makefile.am}, says that we are building a single executable, +from a single sourcefile @file{simple.cpp}. Since every program +we are building uses GiNaC we simply added the GiNaC options +to @env{$LIBS} and @env{$CPPFLAGS}, but in other circumstances, we might +want to specify them on a per-program basis: for instance by +adding the lines: + +@example +simple_LDADD = $(GINACLIB_LIBS) +INCLUDES = $(GINACLIB_CPPFLAGS) +@end example + +to the @file{Makefile.am}. + +To try this example out, create a new directory and add the three +files above to it. + +Now execute the following commands: + +@example +$ automake --add-missing +$ aclocal +$ autoconf +@end example + +You now have a package that can be built in the normal fashion + +@example +$ ./configure +$ make +$ make install +@end example + -@node Bibliography, Concept Index, Internal representation of products and sums, Top +@node Bibliography, Concept Index, Example package, Top @c node-name, next, previous, up @appendix Bibliography