This directory contains  the PSBLAS library, version 2.4.0

WHAT'S NEW

In version 2.4.0: 
- Eliminated dependency on the BLACS, we now use only MPI
  (but the look and feel to the user remains unchanged). 
- Refactored the modules for the Krylov subspace methods.

In version 2.3.4: 
- Besides the usual bunch of bug fixes, refactored the I/O utilites
  and split most modules. 
- Tested with XLF V12. 

In version 2.3.2:
- --enable-serial configure option: the library includes a series of
  stubs for all MPI routines we currently use; no need for BLACS in
  this case. NOTE: the MPI stubs only cover what we use internally,
  they are not meant to be complete; however a user writing his/her own 
  MPI code is probably not interested in this. 

- Added NAGware support in configure.

In version 2.3.1:
- Improved performance of the index handling in descriptor build
  phase.  
- Name changes and reworked internals for linear map. 

In version 2.3:
- New HTML documentation.
- New object to map between two index spaces (psb_inter_desc).

 
Version 1.0 of the library was described in:
S. Filippone, M. Colajanni
PSBLAS: A library for parallel linear algebra computation on sparse matrices
ACM Trans. on Math. Software, 26(4), Dec. 2000, pp. 527-550.

PLATFORMS: 

The compilation process relies on the choice of an appropriate
Make.inc file; we have tested with AIX XLF, Intel ifort/Linux,  Nag
f95/Linux, GNU Fortran/Linux, Sun Forte 6.2. If you succeed in
compiling with  other compiler/operating systems please let us know. 


LINUX:

On Linux we work with the GCC compiler; note that we require version
4.3.0 or later

For the Intel compilers, we recommend version 9.1 or later.

IBM SP:
The library has been tested on an IBM SP6, with XLC and XLF 
version 12.1 and the IBM ESSL/PESSL versions of the BLAS and the
BLACS. 


UTILITIES
The test/util directory contains some utilities to convert to/from
Harwell-Boeing and MatrixMarket file formats. 


DOCUMENTATION

See docs/psblas-2.4.0.pdf; an HTML version of the same document is
available in docs/html. 
Please consult the sample programs, especially test/pargen/ppde.f90. 


OTHER SOFTWARE CREDITS 

We include our modified implementation of some of the Sparker (serial
sparse BLAS)  material,  e.g. Jagged diagonal, plus a number of
extensions of our own design. The original file spblas.f can be
downloaded from matisa.cc.rl.ac.uk; of course any bugs in our
implementation are our own to fix.  The main reference for the serial
sparse BLAS is: 
Duff, I., Marrone, M., Radicati, G., and Vittoli, C.
Level 3 basic linear algebra subprograms for sparse matrices: a user 
level interface
ACM Trans. Math. Softw., 23(3), 379-401, 1997.

INSTALLING

To compile and run our software you will need the following
prerequisites (see also SERIAL below):

1. A working version of MPI

2. A version of the BLAS; if you don't have a specific version for
   your platform you may try ATLAS available from
   http://math-atlas.sourceforge.net/ 

3. We have had good results with  the METIS library, from 
   http://www-users.cs.umn.edu/~karypis/metis/metis/main.html 
   This is optional; it is  used in the util and test/fileread
   directories but only if you define the HAVE_METIS directive.

The configure script will generate a Make.inc file suitable for
building the library.  
The script is capable of recognizing the needed libraries with their
default names; if they are in unusual places consider adding the paths
with --with-libs, or explicitly specifying the names in --with-blas, etc. 
Please note that a common way for the configure script to fail is to
specify inconsistent MPI vs. plain compilers, either directly or
indirectly via environment variables; e.g. specifying the Intel
compiler with FC=ifort while at the same time having an  MPIFC=mpif90
which points to GNU Fortran. 
The best way to avoid this situation is (in our opinion) to use the
environment modules package (see http://modules.sourceforge.net/), and
load the relevant variables with (e.g.)  
module load gnu43 mpich 
This will delegate to the modules setup to make sure that the version
of mpich in use is the one compiled with the gnu43 compilers. 
After the configure script has completed you can always tweak the
Make.inc  file yourself. 

After you have Make.inc fixed,  run 
 make 
to  compile the library; go to the test directory and its
subdirectories to get test programs done.   
If you specify --prefix=/path you can do make install and the
libraries will be installed under /path/lib, while the module files
will be installed under /path/include.

SERIAL
There is a configure option --enable-serial that will compile a
serial-only version of the library; in this case you don't need MPI
(but you still need the BLAS). 


KNOWN ISSUES.

An annoying problem exists with some versions of MPI: if the configure
script sets -DMPI_MOD the MPI call interfaces will be resolved by
using the MPI Fortran module. 
However usage of the  module may cause compilation to fail when
coupled with the debugging option -g, because the compiler complains
that it cannot find a matching interface for some of the
communication routines.
The solution: either take out the -g option, or, if you really need to
debug, edit Make.inc to force -DMPI_H in place of -DMPI_MOD. 


TODO:
Fix all reamining bugs. Bugs? We dont' have any ! ;-)


The PSBLAS team. 

RELATED SOFTWARE

If you are looking for more sophisticated preconditioners, you may be
interested in the package  MLD2P4 from http://www.mld2p4.it 



Contact: Salvatore Filippone     salvatore.filippone@uniroma2.it

Credits for version 2.2:
Michele Martone contributed the initial version of the configure
machinery.  

Credits for version 2.0:
Salvatore  Filippone
Alfredo    Buttari


Credits for version 1.0:

Salvatore  Filippone
Michele    Colajanni
Fabio      Cerioni
Stefano    Maiolatesi
Dario      Pascucci




