\section{Installation}
\label{sec:install}

Underneath the main {\tt BlockSolve95} directory are six other directories:
(1) {\tt src}, which contains the source code and makefiles for
\BS, (2) {\tt doc}, which contains the documentation for \BS,
(3) {\tt examples}, which contains example programs that demonstrate the
use of \BS, (4) {\tt include}, (5) {\tt lib}, and (6) {\tt bmake}.
\sindex{directory structure}
\sindex{installation}

\BS\ uses the same makefile system as PETSc \cite{petsc}.
The {\tt README} file in the main directory gives details on
how to build the libraries.
The makefiles will build the \BS\ library in a subdirectory of the
{\tt lib} directory based on the machine architecture and the
level of optimization.
The machine architecture should be specified by the environmental
variable {\tt \$PETSC\_ARCH}.\findex{\$PETSC_ARCH}
You will have to modify the
file {\tt bmake/\$PETSC\_ARCH/\$PETSC\_ARCH.site} as
directed in the {\tt README} file.
\sindex{PETSc}

Several compiler options affect \BS.
The {\tt DEBUG\_ALL}\findex{DEBUG_ALL} flags were described in \S\ref{sec:misc}.
The flag {\tt MLOG} is associated with the
\findex{MLOG}
logging facilities within \BS, and
more information can be found on them in the file 
{\tt include/BSlog.h}.\findex{include/BSlog.h}
A preprocessor variable called {\tt BSDOUBLE}\findex{BSDOUBLE}
is defined in {\tt include/BSsparse.h}.\findex{include/BSsparse.h}
If {\tt BSDOUBLE} is defined, \BS\ will compile a 
double-precision version; otherwise, a single-precision
version is compiled.
Unfortunately, the routine names for both versions are the same.
\sindex{compiler options}

There is special case on the Cray T3D because the C code
requires that {\tt FLOAT} be defined as {\tt double} but the
BLAS and LAPACK routines require the single-precision names
(although they are the double-precision versions).
Details can be found in the include file 
{\tt include/BSsparse.h}.
\sindex{single and double precision}

\subsection{Other Libraries}
To run \BS, you need LAPACK; the
BLAS 1, 2, and 3 libraries; and an MPI
implementation for the particular architecture
being used.
If MPI has not been installed on your system,
we recommend your using MPICH.
This package is available via anonymous ftp from
{\tt info.mcs.anl.gov} in the directory {\tt pub/mpi}.
More information on MPI can be found on the WWW at
{\tt http://www.mcs.anl.gov/mpi/index.html}.
\sindex{LAPACK}
\sindex{BLAS}
\sindex{MPICH}

\subsection{UNIX {\tt man} Pages}
UNIX {\tt man} pages have been generated for the
\BS\ routines and are located\linebreak in~the~directory
{\tt doc/man}.
To use these pages you must include
the path to the directory\linebreak 
{\tt BlockSolve95/doc/man} in
your {\tt MANPATH} environmental
variable.
This variable can be set with the command 
{\tt setenv}.
The tool {\tt xman} provides a nice
interface to these man pages.
The \BS\ routines can be accessed in Section 3
and the include files in Section h from the
pull-down menu given by the ``Sections'' button
on the {\tt xman} toolbar.
\sindex{UNIX {\tt man} pages}

\subsection{Availability of \BS}
The \BS\ package can obtained via anonymous ftp from
{\tt info.mcs.anl.gov}.
The package is in the directory {\tt pub/BlockSolve95}.
In addition, \BS\ is available from netlib.
The current version number and last date of modification
are in the file {\tt include/BSsparse.h}.
Please send any questions via e-mail to {\tt jones@cs.utk.edu}
or {\tt plassman@mcs.anl.gov}.
Include your name, affiliation, U.S.-mail address,
and e-mail address, along with a description of what 
you might be interested in doing with \BS.
\sindex{availability}

Information on the current status of \BS\ can be obtained on the WWW 
at {\tt http://www.mcs.anl.gov/blocksolve95/index.html}.
\sindex{WWW address}

\subsection{Differences between Previous {\em BlockSolve} Versions}
\BS\ incorporates many improvements over {\em BlockSolve} v1.1 and v2.0.
Among these improvements are the following.
\begin{itemize}
\item A compile-time option has been added that directs \BS\ to use
no blocking sends (see \S\ref{sec:misc} or the include file 
{\tt include/BSdepend.h} for details).\findex{include/BSdepend.h}
This feature is necessary because certain machines (e.g., the
IBM SP series architecture) have inadequate message buffering 
space allocated to use blocking sends.
\sindex{new features}

\item \BS\ now uses the MPI message-passing standard instead
of \tools\ for communication.

\item \BS\ can now compute incomplete LU factorizations for
matrices that have a symmetric nonzero pattern but nonsymmetric
entries.  Also, the iterative solver GMRES has been added,
which can be used to solve these nonsymmetric systems.
See \S\ref{sec:main} for details.

\item A subroutine, {\tt BSeasy\_A()},\findex{BSeasy_A()}
has been added that allows the user
to convert a sparse matrix stored in a familiar storage format to
the \BS\ data structure used for parallel computation (see 
\S\ref{sec:data} for details).
In addition, the routine {\tt BSfree\_easymat()}\findex{BSfree_easymat()}
has been added to free the data structures that \BS\ allocates when
{\tt BSeasy\_A()} is called.

\item The matrix reordering routines called in {\tt BSmain\_perm()}
\findex{BSmain_perm()} have been significantly modified
to greatly reduce the runtime of \BS\ for problems with only
one degree of freedom per grid point.
\BS\ is still designed for more complex problems, but the reordering
time for these simpler problems is now more satisfactory.

\item The code is now ANSI-C.  This should result in
fewer user errors because of the type checking that can
now be done on argument lists.
Note that the user's code does not have to be ANSI-C
to use the libraries.
\sindex{ANSI-C}

\item \BS\ has special macros for handling the level-2
BLAS GEMV and TRMV for small i-node sizes.  The performance
of the vendor-supplied BLAS have proven to be inadequate
in this parameter range, so inline versions of specific
BLAS are now included in the include file {\tt include/BSmy\_blas.h}.
\findex{include/BSmy_blas.h}
\sindex{BLAS}
\sindex{inline macros}

\item The set of example programs is greatly expanded
and can be used to test most aspects of \BS.
See \S\ref{sec:examples} for a description of the 
program examples.
\sindex{examples}
\end{itemize}

\newpage
