1 Installing rheolef
********************

(Source file: `configure.ac') 

             ./configure
             make
             make install
Successfull compilation and installation   require the GNU `make'
command.    Check your installation by running a small test:
             make installcheck

1.1 Reading the documentation
=============================

`rheolef' comes with three documentations:


   * an users guide with a set of complete examples

   * a reference manual for unix commands an C++ classes

   * the full browsable source code in html format

All these documentations are downloadable in various formats from the
`rheolef' home page.    These files are also locally installed   during
the `make install' stage.  The users guide is generated in `pdf' format:
              evince usrman.pdf

The reference manual is generated in `html' format:
              firefox http://ljk.imag.fr/membres/Pierre.Saramito/rheolef/rheolef.html
   and you could add it to your bookmarks.    Moreover, after
performing `make install',   unix manuals are available for commands
and classes:


              man field
              man 3 field
   The browsable source code is generated in `html' format:
              firefox http://ljk.imag.fr/membres/Pierre.Saramito/rheolef/source_html/

1.2 Using and alternative installation directory
================================================

The default install prefix is `/usr/local'.     If you prefer an
alternative directory, e.g. `HOME/sys',    you should enter:
              ./configure --prefix=$HOME/sys
   In that case, you have to add the folowing lines at the end    of
your `.profile' or `.bash_profile' file:
              export PATH="$PATH:$HOME/sys/bin"
              export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$HOME/sys/lib"
              export MANPATH="$MANPATH:$HOME/man"
   assuming you are using the `sh' or the `bash' unix interpreter.
Conversely, if you are using `csh' or `tcsh', add    at the bottom of
your `.cshrc' file:
              set path = ($path $HOME/sys/bin)
              setenv LD_LIBRARY_PATH "$LD_LIBRARY_PATH:$HOME/sys/lib"
              setenv MANPATH "$MANPATH:$HOME/sys/man"
      If you are unure about unix interpreter, get the SHELL value:
              echo $SHELL
   Then, you have to _source_ the modified file, e.g.:
              source ~/.cshrc
   hpux users should replace `LD_LIBRARY_PATH' by `SHLIB_PATH'.     If
you are unure, get the shared library path variable:
              rheolef-config --shlibpath-var
   Check also your installation by compiling a sample    program with
the installed library:
              make installcheck
   Since it is a common mistake, you can later, at each time, test
your run-time environment sanity with:
              rheolef-config --check

1.3 Recommanded library
=======================

The use of implicit numerical schemes leads to the   resolution of
large sparse linear systems.    `rheolef' installation optionally
recognizes both   `umfpack' and `spooles', two multifrontal direct
solvers libraries, and   `taucs', an out-of-core sparse direct solver,
When no efficient sparse direct solver library is not available,
rheolef uses a direct solver based upon a traditionnal skyline Choleski
factorisation   combined with a reverse Cuthill-Mc Kee reordering.
Here is the time complexity for 2d and 3d regular grid-based   Poisson
problems.
                              skyline     multifrontal
             factorization    N^2         N log N
              2d
             resolution       N^3/2       N log N

             factorization    N^7/3       N^2
              3d
             resolution       N^5/2       N^4/3
   The out-of-core strategy is efficient for very large problems   or
if your computer has few memory.    The complexity estimation has been
shown by A. George,   NESTED DISSECTION OF A REGULAR FINITE ELEMENT
MESH,   SIAM J. Numer. Anal., 10:345-363, 1973.

1.4 The umfpack library
=======================

The `umfpack' library, if present, is auto-detected and used.    It is
widely available, as a debian package.

1.5 The spooles library
=======================

The optional `spooles-2.2' multifrontal linear solver   from A. George,
october 1998, is recommended for solving efficiently   large linear
systems.

It is available at `http://www.netlib.org/linalg/spooles/'.    This
library is free software.    A default skyline strategy is used when
it is not founded by `configure'.    Both the version 2.2. and the
older `2.0' library interface are supported   by `rheolef'.

First build the spooles library:
              cd /usr/local/src
              mkdir spooles-2.2
              gzip -dc < ../spooles.2.2.tar.gz | tar xvf -
              make CC=gcc CFLAGS="-O9" lib
   Better, you can build spooles as a shared library, as follow
(assuming GNU C++):
              make CC=gcc CFLAGS="-O9 -fPIC" lib
              mkdir tmp
              cd tmp/
              ar x ../spooles.a
              gcc -shared -o ../libspooles.so *.o
              cd ..
              rm -rf tmp spooles.a
              make clean
   Note that on `hpux' systems, the `.sl' suffix is used     instead of
the `.so' one.  Then, go to the rheolef directory:
              ./configure --with-spooles=/usr/local/src/spooles-2.2
              make
              make install

1.6 The taucs library
=====================

The optional `taucs-2.0' out-of-core sparse linear solver   from S.
Toledo and D. Chen, may 2002, is recommended   for very large linear
systems   or if your computer has few memory.    `taucs' can factor a
matrix whose factors are larger than   the main memory by storing the
factors on disk files.    In that case, this strategy is significantly
faster than paging activity   when running an in-core algorithm such as
`spooles'.

It is available at `http://www.tau.ac.il/~stoledo/taucs/'.    This
library is free software.

The `taucs' installation requires `metis', `lapack' and `blas'
libraries. Assuming all these libraries are installed in
`/usr/local/lib'   and the taucs header `taucs.h' is located in
`/usr/local/include',   the configuration for `rheolef' writes:

              ./configure --with-taucs-ldadd='-ltaucs -llapack -lblas -lmetis -lg2c'
   An alternative is to `blas' is to use the more efficient `atlas'
libraries.    See the installation notes for the taucs library.

1.7 Too long compilations
=========================

On platforms with small memory, the `c++' compilation could be long.
By default, the `configure' scripts uses a `-O2'  compilation level.
Turn it off either by:

              setenv CXXFLAGS "-O0"
              ./configure
              make
   or by editing directly `config/config.mk'.

1.8 Portability issues
======================

rheolef is based on STL. Therefore you need a compiler     that
supports the ANSI C++ standards. STL and rheolef especially depend
heavily on the template support of the compiler.

current version of rheolef has only been tested with
              GNU  C++ compiler (g++-2.95.4, 2.96, 3.0.2, 3.0.4, 4.0, 4.3)
              Compaq C++ compiler (V6.3, V6.5)
       on the following operating systems:
              linux debian, pentium 3 and 4, using GNU C++
              mac os x (i386-apple-darwin9.8.0), using GNU C++
              sun solaris 2.8, ultrasparc, using GNU C++
              compacq OSF1 alpha (V5.1, V4.0), using Compacq C++
     The GNU C++ compiler is a free software   available at
`http://www.gnu.org'.    The Compacq C++ compiler is available on
Compacq (DEC) platforms.

Previous versions was tested also on the     KAI  C++ compiler
(KCC-3.2b) and the     CRAY C++ compiler (CC-3.0.2.0).      on the
following operating systems:
              aix 4.1 ibm sp2, multiprocessor based on rs6000
              cray unicos t3e, multiprocessor based on 64 bits dec alpha
              cray unicos c94
              hpux 9.05 and 10.20, hppa
              linux (redhat, suze and slackware), pentium (2,3,pro)
              sgi irix 6.3, mips
              sun solaris 2.5.1, sparc
     The KAI C++ is available at `http://www.kai.com'.      The CRAY
C++ is available on CRAY platforms.      Nevertheless, the current
version has no more been tested          on these compilers and systems.

If you are running a another compiler and operating system combination,
 please run the non-regression test suite:
              make check
and reports us the result. If all is ok, please, send us a mail,   and
we will add your configuration to the   list, and else we will try to
circumvent the problem.

1.9 Known portability limitations
=================================

On compacq alpha, the old cxx V6.1 (DIGITAL UNIX V4.0)   compiles well
but scratches on   non-regression tests, due to a bug in shared
libraries managment.    Please, update to cxx V6.3 or more, it will
work well.

   On some hpux and GNU C++ version combinations,   building shared
libraries could be broken.    Uses instead:
              ./configure --disable-shared
   It should work. Building static libraries leads to larger executable
 files, and then more disk space available. This limitation depends upon
 compilers and systems compatibilities, not upon rheolef source code
portability.

Please read `http://www.gnu.org/software/gcc/install/specific.html'.
A recent version of `binutils' and a hpux patch are recommended.

Osman F. Buyukisik <<osman.buyukisik@ae.ge.com>> reported that
              export LIBS=" -ldce -static "
              ./configure
   works also well on hpux-10.20.



1.10 Related tools
==================

Using rheolef suggests the use of the following optional tools:

               gnuplot
               plotmtv
               mayavi
               paraview
               vtk
               geomview
               qmg
               grummp


1.11 Advanced configuration
===========================

Note that each `--with' option has a corresponding     `--without'
option.


`--enable-optim'
     Turns compile-time optimization to maximum available.
     Default is on.

`--with-bigfloat=DIGITS10'
     Turn on Bruno Haible's `cln' arbitrary         precision float
     library with DIGITS10 precision,

     See `http://clisp.cons.org/~haible/packages-cln.html'.
     Default is off.          The DIGITS10 value is optional and
     default DIGITS10 value is 60.               This feature is still
     under development.

`--with-cln=DIR_CLN'
     Set the home directory for the `cln' library.          Default
     DIR_CLN is `/usr/local/math'.

`--with-doubledouble'
     Uses `doubledouble' class as the default rheolef `Float' type.
              This option is usefull for a quadruple-like precision on
                machines where this feature is not or incorrectly
     available.          Default is off.

`--enable-debian-packaging=DEBIAN_PACKAGING'
     Generate files the debian way         by respecting the `Debian
     Policy Manual`.

`--with-boost-incdir=INCDIR_BOOST'
     Turns on/off the `boost' boost/numeric/uBlas         dense and
     sparse matrix library.          This library is required by
     rheolef.

`--enable-debug'
     Produce a `c++ -g' like code.

`--enable-dmalloc'
     With debugging, also uses dynamic allocation runtime checking
            with `dmalloc' when available.

`--enable-distributed'
     Turns on/off the distributed memory and parallel computation
     features.          Default is off. This feature is currently in
     development.          When on, configure try to detect either the
     mpi, and cotch or the parmetis libraries.

`--enable-mpi'
     Turns on/off the distributed memory and parallel computation
     features.          Default is on when distributed is on. This
     feature is currently in development.          When on, configure
     try to detect either the scotch or the parmetis libraries.

`--with-scotch'
`--with-scotch=LIBDIR_SCOTCH'
     Turns on/off the `scotch' distributed mesh partitionner.
     Check in LIBDIR_SCOTCH for `libptscotchparmetis.so',
     `libptscotch.so' and `libptscotcherrexit.so' or
     corresponding `.a' libraries.          Default is to auto-detect
     when mpi is available.

`--with-parmetis'
`--with-parmetis=LIBDIR_PARMETIS'
     Turns on/off the `parmetis' distributed mesh partitionner.
     Check in LIBDIR_PARMETIS for `libparmetis.so',
     `libparmetis.a' and also `libmetis.a'         `libmetis.so'.
       Default is to autodetect when mpi is available and scotch
     unavailable.

`--with-blas-ldadd'
`--with-blas-ldadd=RHEO_LDADD_BLAS'
     Turns on/off the `blas' libraries.          Check in
     RHEO_LDADD_BLAS for `libblas.so',         or the corresponding
     `.a' libraries.          Default is to auto-detect.          This
     librariy is required for the pastix library.

`--with-pastix'
`--with-pastix=LIBDIR_PASTIX'
     Turns on/off the `scotch' distributed mesh partitionner.
     Check in LIBDIR_SCOTCH for `libptscotchparmetis.so',
     `libptscotch.so' and `libptscotcherrexit.so' or
     corresponding `.a' libraries.          Default is to auto-detect
     when mpi is available.

`--with-umfpack=LIBDIR_UMFPACK'
`--with-umfpack-incdir=INCDIR_UMFPACK'
     Turns on/off the `umfpack' version 4.3 multifrontal direct solver.
            Default INCDIR_UMFPACK is LIBDIR_UMFPACK.          Check in
     LIBDIR_UMFPACK for `libumfpack.so' or         `libumfpack.a' and
     for header         INCDIR_UMFPACK/umfpack.h or
     INCDIR_UMFPACK/umfpack/umfpack.h.               When this library
     is not available, the direct solver         bases upon a
     traditionnal skyline Choleski factorisation         combined with
     a reverse Cuthill-Mc Kee reordering.

`--with-taucs-ldadd=TAUCS_LDADD'
`--with-taucs-incdir=TAUCS_INCDIR'
     Turns on/off the `taucs' version 2.0 out-of-core sparse direct
     solver.               When this library is not available, the
     configure script         check for the spooles multifrontal (see
     below).

`--with-spooles-libdir=LIBDIR_SPOOLES'
`--with-spooles-incdir=INCDIR_SPOOLES'
     Turns on/off the `spooles' version 2.2 multifrontal direct solver.
            Default INCDIR_SPOOLES is LIBDIR_SPOOLES.          Check in
     LIBDIR_SPOOLES for `libspooles.so',         `libspooles.a' or
     `spooles.a' and for header         INCDIR_SPOOLES/FrontMtx.h.
             When this library is not available, the direct solver
       bases upon a traditionnal skyline Choleski factorisation
     combined with a reverse Cuthill-Mc Kee reordering.   Generic or
     hardware-dependant optimization

1.12 Future configure options
=============================

These options will be implemented in the future:

`--with-long-double'
     Defines `long double' as the default         rheolef `Float' type.
     Default is off and defines `double' as         `Float' type.
            Warning: most of architectures does not provides
     mathematical library in              `long double', e.g.
     `sqrt((long double)2)' returns only double precision
     result on Sun architectures, despites it uses a double memory
     space.          Thus use `--with-doubledouble' instead.

1.13 Rebuilding the documentation
=================================

You can rebuild the documentation by entering:
              make dvi

The user's manual goes into `doc/usrman/' and the  the reference manual
into `doc/refman/'.

The user's manual becomes available in `.dvi',  `.ps' and `.pdf'
formats.

Regenerating the full documention requires also optional tools.


              xdvi      doc/usrman/usrman.dvi
              ghostview doc/usrman/usrman.ps
              xpdf      doc/usrman/usrman.pdf

The reference manual is available in `.info', `.dvi',  `.ps', `.pdf',
`.html' and `.txt' formats:


              info -f   doc/refman/rheolef.info
              xdvi      doc/refman/rheolef.dvi
              ghostview doc/refman/rheolef.ps
              xpdf      doc/refman/rheolef.pdf
              lynx      doc/refman/rheolef_toc.html
              vi        doc/refman/rheolef.txt

1.14 Documentation using doxygen
================================

`doxygen' is a documentation system  and can be found at
`http://www.doxygen.org'.

`doxygen' has built-in support to generate inheritance diagrams for C++
classes.   `doxygen' can use the `dot' tool from `graphviz' to generate
more advanced diagrams  and graphs. `graphviz' is an open-sourced,
cross-platform graph drawing toolkit  from AT&T and Lucent Bell Labs
and can be found at  `http://www.research.att.com/sw/tools/graphviz/'.


              mozilla file:`pwd`/doc/doxygen/html/index.html

1.15 Compile-time optional tools
================================

Installation has been tested with the indicated version number.
Later version should also work well.


`doubledouble-2.2'
     The definitive site for this code is

     `http://www-epidem.plantsci.cam.ac.uk/~kbriggs/doubledouble.html'.

     The 2.2 version is included in this distribution for convenience.

`cln-1.0.2'
     Bruno Haible's arbitrary precision float library.

     See `http://clisp.cons.org/~haible/packages-cln.html'.

`dmalloc-4.8.2'
     For dynamic allocation checking in conjuction      with `configure
     --with-debug'.


1.16 The directory structure
============================

`config'
     portability related files and documentation extractors

`util'
     a collection of useful C++ classes                 and functions
     for smart pointers,                 handling files and
     directories, using strings, timing.

`skit'
     sparse matrix library, renumbering and factorization,
       linear solvers.

`fem'
     finite element library, mesh, spaces and forms.

`doc'
     reference manual, user's guide, web site.

`examples'
     demonstrations as in users'guide.

1.17 Compiling from development version
=======================================

The installation process is preceeded by an extra `bootstrap' stage,
and the `configure' stage takes an extra `--enable-ginac' flag.    An
example writes:
             ./bootstrap
             ./configure --enable-ginac
             make
             make install
You will need some extra-development tools that are used   by
maintainers.

* for configuration files:


             autoconf-2.59
             automake-1.7.9
             m4-1.4 (GNU m4)

* for automatically builted files:


             ginac-1.1.6
             flex-2.5.4
             bison-1.875a

* for maintaining documentation:


              makeinfo-4.6
              texi2html-1.65
              tex-3.14159
              texinfo-4.6
              latex 2e (2001/06/01)
              dvips-5.92b
              gnuplot-3.7
              transfig-3.2
              doxygen-1.2.13.1

* Version numbers are indicative: others versionnumbers sould also work.
   Nevertheless, these version numbers are known to work well.

* For participating to the rheolef concurrent development,   please
contact also <Pierre.Saramito@imag.fr> for concurrent   development.

