===========================================
MUMPS 5.0.1 INSTALLATION
===========================================

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

If you only want to use the sequential version, you need:
-> an optimized sequential or multithreaded BLAS library

If you want to use MUMPS on a multicore machine, you need:
-> a multithreaded BLAS library

If you want to use the parallel (distributed memory MPI based) version, 
you need:
-> MPI
-> BLAS library 
-> BLACS library
-> ScaLAPACK library (sometimes depending on LAPACK)

For performance (time and memory issues) we very strongly recommend to install:
-> SCOTCH and/or METIS for the sequential and parallel versions
-> PT-SCOTCH and/or ParMetis to parallelize the analysis phase (parallel version
only: ParMetis and PT-SCOTCH must be disabled for the sequential version as
this would otherwise lead to undefined MPI symbols at the link phase)


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

The following steps can be applied.

% tar zxvf MUMPS_5.0.1.tar.gz
% cd MUMPS_5.0.1

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

 Makefile.debian.SEQ       : default for debian systems with standard packages, sequential version
 Makefile.debian.PAR       : default for debian systems with standard packages, parallel version
 Makefile.FREEBSD10.SEQ    : default Makefile.inc for a FreeBSD system, sequential version.
 Makefile.FREEBSD10.PAR    : default Makefile.inc for a FreeBSD system, parallel version.
 Makefile.G95.SEQ          : default Makefile.inc for the G95 compiler, sequential version.
 Makefile.G95.PAR          : default Makefile.inc for the G95 compiler, parallel version.
 Makefile.INTEL.SEQ        : default for PC with the Intel suite (compilers, MPI and MKL), sequential.
 Makefile.INTEL.PAR        : default for PC with the Intel suite (compilers and MKL), parallel.
 Makefile.NEC.SEQ          : default Makefile.inc for a NEC, sequential version.
 Makefile.NEC.PAR          : default Makefile.inc for a NEC, parallel version.
 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.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 debian system and standard packages copy
Make.inc/Makefile.debian.PAR into Makefile.inc

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

In most cases, Makefile.inc should be adapted to fit with your
architecture, libraries and compilers (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.


Using MUMPS from an external project
------------------------------------

If you want to use MUMPS from outside the MUMPS installation directory,
please make sure the ./lib/ and ./include/ directories can be accessed,
and start from the Makefile.inc used at installation and the Makefile
available in ./examples as models.


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 the FAQ page at http://mumps-solver.org). 

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


32-bit versus 64-bit Fortran integers
-------------------------------------

MUMPS mainly relies on 32-bit integers (64-bit integers are sometimes
used internally to address some large arrays). It should thus be linked
with libraries (BLAS, MPI, ...) that have been compiled to work with
32-bit integers.

If you need to use MUMPS with 64-bit integers, it is possible to force
64-bit integers in all MUMPS Fortran sources with a compiler-specific
flag. This flag (e.g., -i8 or -fdefault-integer-8, depending on your
compiler) should be added in the OPTF variable from the Makefile.inc
corresponding to your local configuration. You should also force 64-bit
default "int" in C code, by adding -DINTSIZE64 to the OPTC variable
from Makefile.inc.

For the MPI-free version, all libraries used by MUMPS (METIS, SCOTCH,
BLAS) should also rely on 64-bit integers. For the MPI version,
it is not clear which MPI implementations support default 64-bit
integers (for MPI_INTEGER and for all counts).

At the moment of this release, this feature has only been tested for
the MPI-free version.


Interface with the Metis and ParMetis orderings
-----------------------------------------------

Since the release of MUMPS 4.10.0, the Metis API
has changed. MUMPS 5.0.1 assumes that Metis 5.1.0 or 
ParMetis 4.0.3 or later are installed, 
and that the newer versions of Metis/ParMetis
are backward compatible with Metis 5.1.0/ParMetis 4.0.3.

It is however possible to continue using Metis
versions 4.0.3 or lower by forcing the compilation flag -Dmetis4,
and to continue using ParMetis versions 3.2.0 or lower
by forcing the compilation flag -Dparmetis3.

Note that Metis 5.0.3 and ParMetis 4.0.1/4.0.2 have
never been supported in MUMPS.


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

Versions of MUMPS have been tested on a large range of platforms.
MUMPS is potentially portable to any platform having a C and
Fortran 90 compiler as well as MPI, BLACS, and ScaLAPACK installed.

* WINDOWS
  -------

Although the MUMPS development team is not using Windows, you
may be interested by discussions on this topic in the archives
of MUMPS users, by the WINMUMPS project, or by visual studio project
files provided by Free Fields Technologies (see main MUMPS website).


* FREEBSD AND SOLARIS
  -------------------

Under FreeBSD and Solaris, please check that the spaces are
kept after the definition of commands. For example, use
AR = ar -vr "" 
to force keeping the space after ar -vr
See the example Makefile.FREEBSD10 in the Make.inc/ directory.

Note that the absence of space in the main Makefile
is motivated by portability on Windows environments.

* MAC OSX
  -------

Dominique Orban has developed an Homebrew formula for MUMPS.
Please check the links page at http://mumps-solver.org and
https://github.com/Homebrew/homebrew-science


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

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

* MPICH
  -----
The double complex version does not work correctly with MPICH2 v 1.0.3,
due to truncated messages when using double complex types.
See the FAQ for compatibility issues between mpich and gfortran.

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

