- changed behaviour of numeric::is_rational() and added numeric::is_cinteger()
[ginac.git] / doc / tutorial / ginac.texi
index e6d2d1a140b9f59cf44ad63b015820763b97adb3..5a7ad9dfa2803db940a351a8fc61e2a128c028df 100644 (file)
@@ -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 <ginac/ginac.h>
+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