===========================================
MUMPS version 4.10.0
===========================================

(Quick note on upgrading from a previous version: please
 check if Makefiles have changed (see old and new Makefiles
 in Make.inc/ and be aware that all codes that use MUMPS
 include files must be recompiled).


MUMPS 4.10.0 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 subscribe the
MUMPS Users's mailing list.


  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). Since this first public domain
  version in 1999, research and developments have been supported by the
  following institutions: CERFACS, CNRS, ENS Lyon, INPT(ENSEEIHT)-IRIT,
  INRIA, and University of Bordeaux.

  The MUMPS team at the moment of releasing this version includes
  Patrick Amestoy, Maurice Bremond, Alfredo Buttari, Abdou Guermouche,
  Guillaume Joslin, Jean-Yves L'Excellent, Francois-Henry Rouet, Bora
  Ucar and Clement Weisbecker.

  We are also grateful to Emmanuel Agullo, Caroline Bousquet, Indranil
  Chowdhury, Philippe Combes, Christophe Daniel, Iain Duff, Vincent Espirat,
  Aurelia Fevre, Jacko Koster, Stephane Pralet, Chiara Puglisi, Gregoire
  Richard, Tzvetomila Slavova, Miroslav Tuma and Christophe Voemel who
  have been contributing to this project.

  Up-to-date copies of the MUMPS package can be obtained
  from the Web pages:
  http://mumps.enseeiht.fr/  or  http://graal.ens-lyon.fr/MUMPS


   THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY
   EXPRESSED OR IMPLIED. ANY USE IS AT YOUR OWN RISK.


  User documentation of any code that uses this software can
  include this complete notice. You can acknowledge (using
  references [1] and [2]) the contribution of this package
  in any scientific publication dependent upon the use of the
  package. You shall use reasonable endeavours to notify
  the authors of the package of this publication.

   [1] P. R. Amestoy, I. S. Duff, J. Koster and  J.-Y. L'Excellent,
   A fully asynchronous multifrontal solver using distributed dynamic
   scheduling, SIAM Journal of Matrix Analysis and Applications,
   Vol 23, No 1, pp 15-41 (2001).

   [2] P. R. Amestoy and A. Guermouche and J.-Y. L'Excellent and
   S. Pralet, Hybrid scheduling for the parallel solution of linear
   systems. Parallel Computing Vol 32 (2), pp 136-156 (2006).



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

ChangeLog  LICENSE    README     VERSION    Makefile    Make.inc/
doc/       src/       lib/       include/   libseq/     examples/
PORD/      MATLAB/    SCILAB/

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.

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.

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

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.

MATLAB   contains a MATLAB interface to the sequential version of MUMPS

SCILAB   contains a SCILAB interface to the sequential version of MUMPS


Pre-requisites
--------------

If you only want to use the sequential version, you need to install:
-> BLAS library

If you want to use the parallel version, you need to install:
-> MPI
-> BLAS library
-> BLACS library
-> ScaLAPACK library

For performance (time and memory issues) we also strongly recommend to install:
-> SCOTCH and/or METIS for the sequential version
-> PT-SCOTCH and/or ParMetis for the parallel version


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

The following steps can be applied.

% tar zxvf MUMPS_4.10.0.tar.gz
% cd MUMPS_4.10.0

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.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.
 Makefile.WIN.MS-Intel.SEQ : default for Windows with Intel compiler, sequential, with GNU make.
 Makefile.WIN.MS-G95.SEQ : default for Windows with g95 compiler, sequential, with GNU make.


For a parallel version of MUMPS on a 64-bit IBM SP machine, copy
Make.inc/Makefile.SP64.PAR into Makefile.inc

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

In most 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 constants (Makefile.inc)
--------------------------------------

-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, BLACS, 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. PESSL usually does not
include single precision versions of the ScaLAPACK routines
required by MUMPS. If the single precision or single
complex versions of MUMPS are needed, then ScaLAPACK should
then be used in place of PESSL.

* INTEL Compilers
  ---------------
Some users have reported problems (wrong results) with
Intel compilers version 10.x when using default compiler
optimization (-O).

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