===================
README Instructions
===================

This README file details how to run a ScaLAPACK Example Program on
a network of workstations using MPI.  For demonstration
purposes, we have chosen
   http://www.netlib.org/scalapack/examples/example1.f

The instructions assume that the underlying system is a Sun Solaris
system; the problem is run on one physical processor, using six
processes that do message passing.  The example uses MPI as the
message-passing layer. The version of MPI used in this example is
MPICH (version 1.0.13), and we assume the user has this version
installed. MPICH is a freely available, portable implementation of MPI.
If MPICH is not installed, refer to http://www.netlib.org/mpi/.

If this is run on a different architecture, the user will have to make
a number of changes. In particular, the prebuilt libraries will have
to be changed. If prebuilt libraries do not exist for the specific
architecture, the user will need to download the source
   http://www.netlib.org/scalapack/scalapack.tar.gz
and build them.

To use ScaLAPACK for the first time (on a network of workstations using MPI),
one should

1.  Make a directory for this testing.

      mkdir SCALAPACK
      cd SCALAPACK

2.  Download the ScaLAPACK example program (about 7 KB) into directory
    SCALAPACK.
      http://www.netlib.org/scalapack/examples/example1.f

3.  Download the prebuilt ScaLAPACK library (about 3MB) for the specific
    architecture into directory SCALAPACK (e.g., SUN4SOL2) and uncompress.

      http://www.netlib.org/scalapack/archives/scalapack_SUN4SOL2.tgz

      gunzip scalapack_SUN4SOL2.tgz
      tar xvf scalapack_SUN4SOL2.tar
      rm scalapack_SUN4SOL2.tar

      (Note that this tar file contains the library archive and the
       SLmake.inc used to build the library.  Details of compiler
       flags, etc. can be found in this make include file.)

4.  Download the prebuilt BLACS library (about 60 KB) for the architecture
    (e.g., SUN4SOL2) and message-passing layer (e.g., MPICH), and
    uncompress into directory SCALAPACK.

      http://www.netlib.org/blacs/archives/blacs_MPI-SUN4SOL2-0.tgz

      gunzip blacs_MPI-SUN4SOL2-0.tgz
      tar xvf blacs_MPI-SUN4SOL2-0.tar
      rm blacs_MPI-SUN4SOL2-0.tar

      (Note that this tar file contains the library archive(s) and the
       Bmake.inc used to build the library.  Details of compiler
       flags, etc. can be found in this make include file.)

5.  Find the optimized BLAS library on the specific architecture.

      If not available, download reference implementation (about 1 MB)
      into directory SCALAPACK/BLAS, compile, and build the library.

        mkdir BLAS
        cd BLAS

        Download http://www.netlib.org/blas/blas.tgz

        gunzip -c blas.tgz | tar xvf -
        f77 -O -f -c *.f
        ar cr ../blas_SUN4SOL2.a *.o
        cd ..

     (Note that this reference implementation of the BLAS will not
      deliver high performance.)

6.  Compile and link to prebuilt libraries.


    sun4sol2> f77 -f -o example1 example1.f scalapack_SUN4SOL2.a \
              blacsF77init_MPI-SUN4SOL2-0.a blacs_MPI-SUN4SOL2-0.a \
              blacsF77init_MPI-SUN4SOL2-0.a blas_SUN4SOL2.a \
              $MPI_ROOT/lib/solaris/ch_p4/libmpi.a -lnsl -lsocket
    example1.f:
     MAIN example1:
           matinit:

    (Note that the -lnsl -lsocket libraries are machine specific
     to Solaris.  Refer to the SLmake.inc for details.
    MPICH can be found in the directory $MPI_ROOT.
    On our system we did setenv MPI_ROOT /src/icl/MPI/mpich)

7.  Run the ScaLAPACK example program.

    To run an MPI program with MPICH, one will need to add $MPI_ROOT/bin
    to the path.  On our system we did

    sun4sol2> set path = ($path $MPI_ROOT/bin) 


    To run the example:

    sun4sol2> mpirun -np 6 example1

    
    The example runs on six processes and prints out a statement that
    ``the solution is correct'' or ``the solution is incorrect''.