mld2p4:

docs/pdf/building.tex
 docs/pdf/distribution.tex
 docs/pdf/errors.tex
 docs/userguide.pdf

Updated building, license and error sections.

docs/pdf/building.tex

@@ -11,8 +11,11 @@ MLD2P4 is implemented almost entirely in Fortran~95, with some
 interfaces to external libraries in C; we require the Fortran compiler
 to support the Fortran~95 standard plus the extension TR15581, which
 enhances the usability of \verb|ALLOCATABLE| variables. Most modern
-Fortran compilers, including the GNU Fortran compiler, support this
-language level. The software defines data types and interfaces for
+Fortran compilers support this language level. In particular, this is
+supported by the GNU Fortran compiler as of version 4.2.0; however we
+recommend to use the latest available release (4.3.1 at the time of
+this writing§).
+The software defines data types and interfaces for
 real and complex data, in both single and double precision. 
 
 \subsection{Prerequisites}
@@ -22,12 +25,13 @@ The following base libraries are needed:
   optimized versions; if no vendor version is available for a given 
   platform, the  ATLAS software  \verb!http://www.netlib.org/atlas!
   may be employed.  The reference BLAS from Netlib
-  \verb|htt://www.netlib.org/blas| are meant to define the standard
+  \verb|http://www.netlib.org/blas| are meant to define the standard
   behaviour of the BLAS interface, so they not optimized for any
-  particular plaftorm, and they should only be used as a last
-  resort; note that BLAS computation form a relatively small part of
-  the MLD2P4/PSBLAS computations, except when using preconditioners
-  based on the UMFPACK or SuperLU third party libraries. 
+  particular plaftorm, and  should only be used as a last
+  resort.  Note that BLAS computation form a relatively small part of
+  the MLD2P4/PSBLAS computations; they are however critical when using
+  preconditioners based on the UMFPACK or SuperLU third party
+  libraries.  
 \item[MPI] A version of MPI is available on most high performance
   computing system; we only require version 1.1.
 \item[BLACS] The Basic Linear Algebra Communication Subroutines are
@@ -52,12 +56,182 @@ compiler.
 
 \subsection{Optional third party libraries}
 
-    - software `third party" (UMFPACK, SuperLU, SuperLUdist - specificare versioni e opzioni di 
-    configure, dire che UMFPACK e SuperLU sono richiesti, rispettivamente, dalle versioni in 
-    singola ed in doppia precisione.)\\
+We provide interfaces to the following third-party software libraries;
+note that these are optional, but if you enable them some defaults
+for multilevel preconditioners may change to reflect their presence. 
+
+\begin{description}
+\item[UMFPACK] A sparse direct factorization package available from\\ 
+  \verb|http://www.cise.ufl.edu/research/sparse/umfpack/|; 
+  provides serial factorization and solution for double
+  precision real and complex double precision data. We have tested
+  versions 4.4 and 5.1; 
+\item[SuperLU] A sparse direct factorization package available from \\
+  \verb|http://crd.lbl.gov/~xiaoye/SuperLU/|; provides serial
+  factorization and solution for single and double precision real and
+  complex data. We have tested versions 3.0 and 3.1.
+\item[SuperLU\_Dist] A sparse direct factorization package available
+  from the same site as SuperLU; provides parallel factorization and
+  solution for real and complex double precision data. We have tested
+  version 2.1.
+\end{description}
+
 \subsection{Configuration options}
-    - sistemi operativi e compilatori su cui MLD2P4 e' stato
-    implementato con successo \\
-    - sono previste opzioni di configurazione per il debugging o per il profiling? \\
-    - albero delle directory generato al momento dell'installazione, con brevissima
-    descrizione del contenuto delle directory - aggiungere la directory \texttt{examples}\\
+
+To build  MLD2P4 the first step is to use the \verb|configure| script
+in the main directory to generate the necessary makefile(s). 
+
+As a minimal example consider the following:
+\begin{verbatim}
+./configure --with-psblas=/home/user/PSBLAS/psblas-2.3
+\end{verbatim}
+This assumes that the various MPI compilers and support libraries are
+available in the standard directories on the system. Note that the
+PSBLAS build directory must be specified with an {\em absolute} path.
+The full set of options may be looked at by issuing the command
+\verb|./configure --help|, which produces:
+\begin{verbatim}
+`configure' configures MLD2P4 1.0 to adapt to many kinds of systems.
+
+Usage: ./configure [OPTION]... [VAR=VALUE]...
+
+To assign environment variables (e.g., CC, CFLAGS...), specify them as
+VAR=VALUE.  See below for descriptions of some of the useful variables.
+
+Defaults for the options are specified in brackets.
+
+Configuration:
+  -h, --help              display this help and exit
+      --help=short        display options specific to this package
+      --help=recursive    display the short help of all the included packages
+  -V, --version           display version information and exit
+  -q, --quiet, --silent   do not print `checking...' messages
+      --cache-file=FILE   cache test results in FILE [disabled]
+  -C, --config-cache      alias for `--cache-file=config.cache'
+  -n, --no-create         do not create output files
+      --srcdir=DIR        find the sources in DIR [configure dir or `..']
+
+Installation directories:
+  --prefix=PREFIX         install architecture-independent files in PREFIX
+			  [/usr/local]
+  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
+			  [PREFIX]
+
+By default, `make install' will install all the files in
+`/usr/local/bin', `/usr/local/lib' etc.  You can specify
+an installation prefix other than `/usr/local' using `--prefix',
+for instance `--prefix=$HOME'.
+
+For better control, use the options below.
+
+Fine tuning of the installation directories:
+  --bindir=DIR           user executables [EPREFIX/bin]
+  --sbindir=DIR          system admin executables [EPREFIX/sbin]
+  --libexecdir=DIR       program executables [EPREFIX/libexec]
+  --sysconfdir=DIR       read-only single-machine data [PREFIX/etc]
+  --sharedstatedir=DIR   modifiable architecture-independent data [PREFIX/com]
+  --localstatedir=DIR    modifiable single-machine data [PREFIX/var]
+  --libdir=DIR           object code libraries [EPREFIX/lib]
+  --includedir=DIR       C header files [PREFIX/include]
+  --oldincludedir=DIR    C header files for non-gcc [/usr/include]
+  --datarootdir=DIR      read-only arch.-independent data root [PREFIX/share]
+  --datadir=DIR          read-only architecture-independent data [DATAROOTDIR]
+  --infodir=DIR          info documentation [DATAROOTDIR/info]
+  --localedir=DIR        locale-dependent data [DATAROOTDIR/locale]
+  --mandir=DIR           man documentation [DATAROOTDIR/man]
+  --docdir=DIR           documentation root [DATAROOTDIR/doc/mld2p4]
+  --htmldir=DIR          html documentation [DOCDIR]
+  --dvidir=DIR           dvi documentation [DOCDIR]
+  --pdfdir=DIR           pdf documentation [DOCDIR]
+  --psdir=DIR            ps documentation [DOCDIR]
+
+Optional Packages:
+  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
+  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
+  --with-psblas           The source directory for PSBLAS, for example,
+                          --with-psblas=/opt/packages/psblas-2.2
+  --with-libs             List additional libraries here. For example,
+                          --with-libs=-lsuperlu or
+                          --with-libs=/path/libsuperlu.a
+  --with-clibs            additional CLIBS flags to be added: will prepend
+                          to CLIBS
+  --with-flibs            additional FLIBS flags to be added: will prepend
+                          to FLIBS
+  --with-library-path     additional LIBRARYPATH flags to be added: will
+                          prepend to LIBRARYPATH
+  --with-include-path     additional INCLUDEPATH flags to be added: will
+                          prepend to INCLUDEPATH
+  --with-module-path      additional MODULE_PATH flags to be added: will
+                          prepend to MODULE_PATH
+  --with-umfpack=LIBNAME  Specify the library name for UMFPACK library.
+                          Default: "-lumfpack -lamd"
+  --with-umfpackdir=DIR   Specify the directory for UMFPACK library and
+                          includes.
+  --with-superlu=LIBNAME  Specify the library name for SUPERLU library.
+                          Default: "-lslu"
+  --with-superludir=DIR   Specify the directory for SUPERLU library and
+                          includes.
+  --with-superludist=LIBNAME
+                          Specify the libname for SUPERLUDIST library.
+                          Requires you also specify SuperLU. Default: "-lslud"
+  --with-superludistdir=DIR
+                          Specify the directory for SUPERLUDIST library and
+                          includes.
+
+Some influential environment variables:
+  FC          Fortran compiler command
+  FCFLAGS     Fortran compiler flags
+  LDFLAGS     linker flags, e.g. -L<lib dir> if you have libraries in a
+              nonstandard directory <lib dir>
+  LIBS        libraries to pass to the linker, e.g. -l<library>
+  CC          C compiler command
+  CFLAGS      C compiler flags
+  CPPFLAGS    C/C++/Objective C preprocessor flags, e.g. -I<include dir> if
+              you have headers in a nonstandard directory <include dir>
+  CPP         C preprocessor
+  MPICC       MPI C compiler command
+
+Use these variables to override the choices made by `configure' or to help
+it to find libraries and programs with nonstandard names/locations.
+
+Report bugs to <salvatore.filippone@uniroma2.it>.
+\end{verbatim}
+Thus, a sample build with libraries in installation
+directories specifics to the GNU 4.3 compiler suite might be as
+follows, specifying only the UMFPACK external package: 
+\begin{verbatim}
+ ./configure --with-psblas=/home/user/psblas-2.3/ \
+ --with-libs="-L/usr/local/BLAS/gnu43 -L/usr/local/BLACS/gnu43" \
+ --with-blacs=-lmpiblacs  --with-umfpackdir=/usr/local/UMFPACK/gnu43 
+\end{verbatim}
+Once the configure script has completed execution, it will have
+generated the file \verb|Make.inc| which will then be used by all
+Makefiles in the directory tree. 
+
+To build the library the user will now enter 
+\begin{verbatim}
+make
+\end{verbatim}
+followed (optionally) by 
+\begin{verbatim}
+make install
+\end{verbatim}
+
+\subsection{Example and test programs}
+The package contains the \verb|examples| and \verb|tests| directories;
+both of them are further divided into \verb|fileread| and
+\verb|pargen| subdirectories. Their purpose is as follows:
+\begin{description}
+\item[\tt examples] contains a set of simple example programs with a
+  predefined choice of preconditioners, selectable via integer
+  values. These are intended to get an acquaintance with the
+  multilevel preconditioners.
+\item[\tt test] contains a set of more sophisticated examples that
+  will allow the user, via the input files in the \verb|runs|
+  subdirectories, to experiment with the full range of preconditioners
+  implemented in the library.
+\end{description}
+The \verb|fileread| directories contain sample programs that read
+sparse matrices from files, according to the Matrix Market storage
+format; the \verb|pargen| instead generate matrices in full parallel
+mode from the discretization of a sample PDE. 

docs/pdf/distribution.tex

@@ -13,4 +13,5 @@ bug reports.
 The software is available under a modified BSD license, as specified
 in appendix~\ref{sec:license}; please note that some of the optional
 third party libraries may be licensed under a different and more
-stringent license. 
+stringent license, most notably the GPL, and this should be taken into
+account when treating derived works. 

docs/pdf/errors.tex

@@ -2,8 +2,17 @@
 \markboth{\textsc{MLD2P4 User's and Reference Guide}}
          {\textsc{\ref{sec:errors} Error handling}}
 
-Error handling
-    - Breve descrizione con rinvio alla guida di PSBLAS
+The error handling in MLD2P4 is based on the PSBLAS version 2 error
+handling. Error conditions are signaled via an integer argument
+\verb|info|; whenever an error condition is detected, an error trace
+stack is built by the library up to the top-level, user-callable
+routine. This routine will then decide, according to the user
+preferences, whether the error should be handled by terminating the
+program or by returning the error condition to the user code, which
+will then take action, and whether
+an error message should  be printed. These options may be set by using
+the PSBLAS error handling routines; for further details see the PSBLAS
+user's guide. 
 
 %%% Local Variables: 
 %%% mode: latex