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

(Source file: 'configure.ac')

       ./configure
       make
       make install

Successfull compilation and installation require the GNU 'make' command.

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 http://ljk.imag.fr/membres/Pierre.Saramito/rheolef/rheolef.pdf

The reference manual is generated in 'html' format:

       firefox http://ljk.imag.fr/membres/Pierre.Saramito/rheolef/rheolef-refman.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 2rheolef 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="$HOME/sys/bin:$PATH"
       export LD_LIBRARY_PATH="$HOME/sys/lib:$LD_LIBRARY_PATH"
       export MANPATH="$HOME/sys/man:$MANPATH"

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 = ($HOME/sys/bin $path)
       setenv LD_LIBRARY_PATH "$HOME/sys/lib:$LD_LIBRARY_PATH"
       setenv MANPATH "$HOME/sys/man:$MANPATH"

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 Requiered libraries
=======================

All the required libraries have precompiled packages under Debian
GNU/Linux and Ubuntu systems.  If you are running a system where these
libraries are not available, please consult the corresponding home pages
and install instructions.

a) Rheolef widely uses the 'boost' library, that provides usefull
extensions of the c++ standard template library.  'boost' at
<http://www.boost.org> .

b) The use of implicit numerical schemes leads to the resolution of
large sparse linear systems.  Rheolef installation optionally requieres
'mumps' as direct solver library.  'mumps' is available at
<http://graal.ens-lyon.fr/MUMPS> .

c) Rheolef implements the characteristic method and interpolation from
one mesh to another: these features leads to sophisticated algorithms
and octree-type data structures.  The 'cgal' library provide easy access
to efficient and reliable geometric algorithms in the form of a C++
library.  'cgal' is available at <http://www.cgal.org> .

1.4 Highly recommended libraries
================================

All the highly recommended libraries have precompiled packages under
Debian GNU/Linux and Ubuntu systems.  With all these libraries, Rheolef
with run optimally.  Otherwise, it will build and run also, but with
some loss of performances.

a) Rheolef bases on 'mpi', the message passing interface standard.  When
no 'mpi' libraries are available, the distributed features are turned
off.

b) Rheolef bases on 'scotch' for distributed mesh partitioning.
'scotch' is available at <http://www.labri.fr/perso/pelegrin/scotch> .
When the 'scotch' library is not available, the distributed features are
turned off.

c) Rheolef installation optionally uses 'trilinos/ifpack' as a library
of preconditioner used for iterative solvers.  'trilinos' is available
at <http://trilinos.sandia.gov> .  When 'trilinos' is not available, a
less efficient builtin IC0 preconditioner is used.

1.5 Run-time optional tools
===========================

Using Rheolef suggests the use of the following optional tools for pre-
and post-processing purpose:

       gmsh
       gnuplot
       mayavi
       paraview

None of these tools are required when building and installing Rheolef.

1.6 Build-time extra tools for rheolef developpers
==================================================

These tools are required if you build from the development version
(under CVS). Re-generating some source files, as initiated with the
"bootstrap" command, requiers autotools 'autoconf', 'automake' and
'libtool' and also 'flex' and 'bison'.  It requiers also 'ginac' for
polynomial basis management.  'ginac' is available at
<http://www.ginac.de> .  It requiers finaly latex figure management
tools to.  Here is the 'apt-get' commands to install these tools under
Debian GNU/Linux and Ubuntu:

       apt-get install cvs autoconf automake libtool
       apt-get install flex bison
       apt-get install pkg-config libginac-dev
       apt-get install ghostscript gnuplot xfig transfig imagemagick graphviz

1.7 Portability issues
======================

Rheolef is based on STL and its extensions, the BOOST library.
Therefore you need a compiler that supports the ANSI C++ standards.  STL
and Rheolef especially depend heavily on the template support of the
compiler.  Most recent c++ 2012 standard features are recommanded but
still optional: when available, it allows an elegant matrix
concatenation syntax via the 'std::initializer_list' class.

Current distributed version of Rheolef has been heavily tested with GNU
C++ and INTEL C++ on debian, ubuntu and suse GNU/Linux systems for
various 32 and 64 bits architectures, up to 100 distributed memories and
processes.

The GNU C++ compiler is a free software available at
<http://www.gnu.org>.  The Intel C++ compiler is a privative software.

Older 5.x 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:

       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++
       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
       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 the required libraries are located in a non-standard directory,
please use the configure options:

       ./configure --help

and also consider the CXX, CXXFLAGS and LIBS variables, as in the
following more complex configure command:

       CXX=icpc CXXFLAGS=-I/usr/local/include LIBS="-L/usr/local/lib -lz" ./configure

Finaly, if troubles still persist after the configure step, you can also
edit directly the config/config.mk and config/config.h files.  In these
cases please also post to the mailling list 'rheolef@grenet.fr' any
portability problem.

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.

'--enable-optim'
     Turns compile-time optimization to maximum available.  Include
     architecture-dependent compilation (e.g.  on intel, executable are
     less portable accross intel variants).  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'
'--with-boost-libdir=LIBDIR_BOOST'
     Specifies the 'boost' 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-old-code'
     Turns on/off the old code branch (before distributed computation
     features).  Default is off.

'--enable-mpi'
     Turns on/off the distributed 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-incdir=INCDIR_SCOTCH'
'--with-scotch-libdir=LIBDIR_SCOTCH'
'--with-scotch-libs=LIBS_SCOTCH'
     Turns on/off the 'scotch' distributed mesh partitioner.  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-incdir=INCDIR_PARMETIS'
'--with-parmetis-libdir=LIBDIR_PARMETIS'
     Turns on/off the 'parmetis' distributed mesh partitioner.  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-libdidr=RHEO_LIBDIR_BLAS'
'--with-blas-libs=RHEO_LIBS_BLAS'
     Turns on/off the 'blas' libraries.  Check in RHEO_LIBS_BLAS for
     'libblas.so', or the corresponding '.a' libraries.  Default is to
     auto-detect.  This librariy is required for the pastix library.

'--with-scalapack-libdidr=RHEO_LIBDIR_SCALAPACK'
'--with-scalapack-libs=RHEO_LIBS_SCALAPACK'
     Turns on/off the 'scalapack' libraries.  Check in
     RHEO_LIBS_SCALAPACK for 'libscalapack.so', or the corresponding
     '.a' libraries.  Default is to auto-detect.  This librariy is
     required for the pastix library.

'--with-mumps-incdir=INCDIR_MUMPS'
'--with-mumps-libdir=LIBDIR_MUMPS'
'--with-mumps-libs=LIBS_MUMPS'
     Turns on/off the 'mumps' distributed solver.  Check in LIBDIR_MUMPS
     for 'libmumps.so', or the corresponding '.a' libraries.  Default is
     to auto-detect when mpi is available.

'--with-trilinos'
'--with-trilinos=LIBDIR_TRILINOS'
     Turns on/off the 'trilinos' distributed preconditioner library.
     Check in LIBDIR_TRILINOS for 'libtrilinos_ifpack.so', or the
     corresponding '.a' libraries.  Default is to auto-detect when mpi
     is available.

'--with-pastix'
'--with-pastix=LIBDIR_PASTIX'
     Turns on/off the 'pastix' distributed solver.  Check in
     LIBDIR_PASTIX for 'libpastix.so', or the corresponding '.a'
     libraries.  Default is to auto-detect when mpi is available.

'--with-umfpack-incdir=INCDIR_UMFPACK'
'--with-umfpack-libdir=LIBDIR_UMFPACK'
'--with-umfpack-libs=LIBS_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.

'--with-cgal-incdir=INCDIR_CGAL'
'--with-cgal-libdir=LIBDIR_CGAL'
     Turns on/off the 'cgal' distributed solver.  Check in LIBDIR_CGAL
     for 'libcgal.so', or the corresponding '.a' libraries.  Default is
     to auto-detect when mpi is available.  Generic or
     hardware-dependant optimization

1.8 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.

   rpath issue for debian package: seems to be buggy with DESTDIR!=""

1.9 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, linear solvers.
'nfem'
     finite element library, mesh, spaces and forms.
'doc'
     reference manual, user's guide and examples.

