===========================================
MUMPS version 4.8.3
===========================================

MUMPS 4.8.3 solves a sparse system of linear equations A x = b
using Gaussian elimination. Please read this README file and
the documentation (in ./doc/) for a complete list of
functionalities. Documentation and publications related to
MUMPS can also be found at http://mumps.enseeiht.fr/
or at http://graal.ens-lyon.fr/MUMPS

For installation problems, bug reports, and to report your
experience/feedback with the package, please contact
mumps@cerfacs.fr.

This version of MUMPS is provided to you free of charge. It is public
domain, based on public domain software developed during the Esprit IV
european project PARASOL (1996-1999) by CERFACS, ENSEEIHT-IRIT and RAL.
Since this first public domain version in 1999, the developments are supported
by the following institutions CERFACS, INRIA and IRIT.

Current development team includes Patrick Amestoy, Alfredo Buttari,
Philippe Combes, Abdou Guermouche, Jean-Yves L'Excellent, Stéphane Pralet
and Bora Ucar.

We are also grateful to C. Bousquet, C. Daniel, V. Espirat, A. Fèvre,
C. Puglisi, G. Richard, M. Tuma, X. Vasseur and C. Voemel 
who have been contributing to this work. 


Contents of the distribution :
----------------------------

COPYRIGHT  Makefile  README   doc/      lib/     src/
Make.inc/  PORD/     VERSION  include/  libseq/  examples/

Make.inc contains some template Makefiles

doc      contains the users' guide in postscript and pdf formats.

src      contains the source files (for all arithmetics 's','d','c' or 'z')
         necessary to generate the MUMPS library.

lib      is the place where the MUMPS libraries libxmumps.a
         (x='s','d','c' or 'z') are generated.

libseq   contains a sequential MPI library used by the purely sequential
         version of MUMPS.

include  contains xmumps_struc.h, xmumps_root.h and xmumps_c.h (where x is one
         of 'd','c','s','z' depending on the arithmetic desired),
         mumps_c_types.h and mumps_compat.h. The first two files must be
         available at compile time in order to use MUMPS from external FORTRAN
         programs. The three others for C programs.

examples contains illustrative test programs showing how MUMPS can be used.

PORD     contains the PORD package (not part of MUMPS) from University
         of Paderborn. See PORD/README for more info.


Installation
------------

The following steps can be applied.

% tar zxvf MUMPS_4.8.3.tar.gz
% cd MUMPS_4.8.3

You then need to build a file called Makefile.inc corresponding
to your achitecture. Various examples are available in the
directory Make.inc :

 Makefile.SGI.SEQ : default Makefile.inc for an Origin, sequential version.
 Makefile.SGI.PAR : default Makefile.inc for an Origin, parallel version.
 Makefile.SUN.SEQ : default Makefile.inc for a SUN, sequential version.
 Makefile.SUN.PAR : default Makefile.inc for a SUN, parallel version.
 Makefile.SP.SEQ : default for SP (32 bits), sequential version.
 Makefile.SP.PAR : default for SP (32 bits), parallel version.
 Makefile.SP64.SEQ : default for SP (64 bits), sequential version.
 Makefile.SP64.PAR : default for SP (64 bits), parallel version.
 Makefile.PC.SEQ : default for PC (linux, pgf90, lam), seq. version.
 Makefile.PC.PAR : default for PC (linux, pgf90, lam), parallel version.
 Makefile.INTEL.SEQ : default for PC (linux, intel compiler, lam), sequential.
 Makefile.INTEL.PAR : default for PC (linux, intel compiler, lam), parallel.
 Makefile.ALPHA_linux.SEQ : default for ALPHA linux (compiler:fort), sequential.
 Makefile.ALPHA_linux.PAR : default for ALPHA linux (compiler:fort), parallel.
 Makefile.ALPHA_true64.SEQ : default for ALPHA true 64 (compiler:f90), sequential.
 Makefile.ALPHA_true64.PAR : default for ALPHA true 64 (compiler:f90), parallel.

For a parallel version of MUMPS on an IBM SP machine, copy
Make.inc/Makefile.SP.PAR into Makefile.inc

% cp Make.inc/Makefile.SP.PAR ./Makefile.inc

In some cases, Makefile.inc should be adapted to fit with your
architecture, libraries and compiler (see comments in the
Makefile.inc.generic or Makefile.inc.generic.SEQ for details).  The
variables LIBBLAS (BLAS library), SCALAP (ScaLAPACK library), INCPAR
(include files for MPI), LIBPAR (library files for MPI) are concerned.

By default, only the double precision version of MUMPS will be
installed. make <ARITH> will build the version for a specific
arithmetic, where <ARITH> can be one of 'd','c','s','z'.
"make all" will compile versions of MUMPS for all 4 arithmetics.

After issuing the command
% make
, ./lib will contain the mumps libraries libxmumps.a (with x = 'd', 'c',
's' or 'z') and libmumps_common.a. Both must be included at link time in
an external program.

A simple Fortran test driver in ./examples (see ./examples/README) will
also be compiled as well as an example of using MUMPS from a C main
program.


Preprocessing options
---------------------

-DMAIN_COMP:
Note that some Fortran runtime libraries define the "main" symbol.
This can cause problems when using MUMPS from C if Fortran is used
for the link phase. One approach is to use a specific flag (such
as -nofor_main for Intel ifort compiler). Another approach is to
use the C linker (gcc, etc...) and add manually the Fortran runtime
libraries (that should not define the symbol "main"). Finally, if
the previous approaches do not work, compile the C example with
"-DMAIN_COMP". This might not work well with some MPI implementations
(see options in Makefiles and FAQ
at http://graal.ens-lyon.fr/MUMPS and
http://mumps.enseeiht.fr/).

-DAdd_ , -DAdd__ and -DUPPER:
These options are used for defining the calling
convention from C to Fortran or Fortran to C. 

-DALLOW_NON_INIT:
This option can be used to speed up the code for
symmetric matrices by allowing non initialization of
data area that will modified but are not significant
for the computation.

Some other preprocessing options correspond to default
architectures and are defined in specific Makefiles.


Sequential version
------------------

You can use the parallel MPI version of MUMPS on a single
processor. If you only plan to use MUMPS on a uniprocessor
machine, and do not want to install parallel libraries
such as MPI, ScaLAPACK, etc... then it might be more convenient
to use one of the Makefile.<ARCH>.SEQ to build a sequential
version of MUMPS instead of a parallel one.

For that, a dummy MPI library (available in ./libseq) defining
all symbols related to parallel libraries is used at the link
phase.

Note that you should use 'make clean' before building the
MUMPS sequential library if you had previously built a parallel
version. And vice versa.


Compiling and linking your program with MUMPS
---------------------------------------------

Basically, ./lib/libxmumps.a and ./lib/libmumps_common.a constitute the
MUMPS library and ./include/*.h are the include files. Also, some BLAS,
ScaLAPACK, BLACS, and MPI are needed. (Except for the sequential version
where ./libseq/libmpiseq.a is used.) Please refer to the Makefile
available in the directory ./examples for an example of how to link your
program with MUMPS. We advise to use the same compiler alignment options
for compiling your program as were used for compiling MUMPS. Otherwise
some derived datatypes may not match.


Platform dependencies
---------------------

Versions of MUMPS have been tested on CRAY, IBM, SGI, COMPAQ, and Linux
systems. We could potentially generate versions for any other platform
with Fortran 90, MPI, BLACS, and ScaLAPACK installed, but the code has
only been tested on the above-mentionned platforms.


* IBM SP
  ------
On SP machines, use of pessl(p2), blacs(p2), mpi and essl is made.

Note that MUMPS requires PESSL release 2 or greater. The version
of MUMPS based on PESSL release 1.1 (that used descriptors of
size 8) is no longer available. If PESSL release 2 is not
available on your system, the public domain version of
ScaLAPACK should be used instead.

* COMPAQ
  ------
The option -nopipeline is required, otherwise, the version of the
compiler we have used performs software pipeline over iterations of
loops with potential dependencies. Also the option -O3 should not be
used on xmumps_static_mapping.F as it seems to create erroneous code.

* LAM
  ---
lam version 6.5.6 or later is required for the double complex
version of MUMPS to work correctly.

* MPICH
  -----
MUMPS has been tested and works correctly with various versions of MPICH.
The double complex version does not work correctly with MPICH2 v 1.0.3,
due to truncated messages when using double complex types.

* CRAY
  ----
On the CRAY, we recommend to link with the standard BLACS
library from netlib, based on MPI. We observed problems
(deadlock) when using the CRAY BLACS in host-node mode or
when MUMPS is used on a subcommunicator of MPI_COMM_WORLD
of more than 1 processor.
