From 4dda0494a7bcfd48445b99f24b393c89d7bd191f Mon Sep 17 00:00:00 2001 From: Salvatore Filippone Date: Thu, 24 Jul 2008 06:00:20 +0000 Subject: [PATCH] mld2p4: Further doc fixes. --- docs/pdf/bibliography.tex | 2 +- docs/pdf/building.tex | 33 ++++++++++++------------- docs/pdf/gettingstarted.tex | 8 +++--- docs/pdf/userinterface.tex | 49 +++++++++++++++++++++---------------- 4 files changed, 49 insertions(+), 43 deletions(-) diff --git a/docs/pdf/bibliography.tex b/docs/pdf/bibliography.tex index 31f6f4bc..b68ae5e9 100644 --- a/docs/pdf/bibliography.tex +++ b/docs/pdf/bibliography.tex @@ -117,7 +117,7 @@ BIT Numerical Mathematics, 43, 2003, 945--959. % \bibitem{PSBLASGUIDE} S.~Filippone, A.~Buttari, -{\em PSBLAS-2.3 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library}, +{\em PSBLAS-2.3 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library}, 2008, available from \texttt{http://www.ce.uniroma2.it/psblas/}. % \bibitem{psblas_00} diff --git a/docs/pdf/building.tex b/docs/pdf/building.tex index cb4f728e..7c1d699e 100644 --- a/docs/pdf/building.tex +++ b/docs/pdf/building.tex @@ -22,29 +22,29 @@ real and complex data, in both single and double precision. The following base libraries are needed: \begin{description} -\item[BLAS] The Basic Linear Algebra subprograms \cite{blas3,blas3,blas1}. - Many vendors provide optimized versions; if no vendor version is - available for a given platform, the ATLAS software +\item[BLAS] \cite{blas3,blas2,blas1} Many vendors provide optimized versions + of the Basic Linear Algebra Subprograms; if no vendor version is + available for a given platform, the ATLAS software (\verb!http://math-atlas.sourceforge.net/!) may be employed. The reference BLAS from Netlib (\verb|http://www.netlib.org/blas|) are meant to define the standard behaviour of the BLAS interface, so they are not optimized for any particular plaftorm, and should only be used as a last - resort. Note that BLAS computation form a relatively small part of + resort. Note that BLAS computations 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 \cite{MPI2,MPI1} is available on most high performance - computing system; only version 1.1 is required. -\item[BLACS] The Basic Linear Algebra Communication Subroutines - \cite{BLACS} are available in source form from \verb|http://www.netlib.org/blacs|; +\item[MPI] \cite{MPI2,MPI1} A version of MPI is available on most + high-performance computing systems; only version 1.1 is required. +\item[BLACS] \cite{BLACS} The Basic Linear Algebra Communication Subprograms + are available in source form from \verb|http://www.netlib.org/blacs|; some vendors include them in their parallel computing support libraries. - \item[PSBLAS] Parallel Sparse BLAS \cite{PSBLASGUIDE,psblas_00} is - available from \\ \verb|http://www.ce.uniroma2.it/psblas|; indeed, all the - prerequisites listed so far are also prerequisites of PSBLAS. - Version 2.3 (or later) is required. To build the MLD2P4 library - it is necessary to get access to + \item[PSBLAS] \cite{PSBLASGUIDE,psblas_00} Parallel Sparse BLAS is + available from \\ \verb|http://www.ce.uniroma2.it/psblas|; version 2.3 + (or later) is required. Indeed, all the prerequisites + listed so far are also prerequisites of PSBLAS. + To build the MLD2P4 library it is necessary to get access to the source PSBLAS directory employed to build the version under use; after the MLD2P4 build process completes, only the compiled form of the PSBLAS library is necessary to build user applications. @@ -67,7 +67,7 @@ for multilevel preconditioners may change to reflect their presence. \verb|http://www.cise.ufl.edu/research/sparse/umfpack/|; provides serial factorization and triangular system solution for double precision real and complex data. We have tested - versions 4.4 and 5.1; + versions 4.4 and 5.1. \item[SuperLU] \cite{SUPERLU} A sparse direct factorization package available from \\ \verb|http://crd.lbl.gov/~xiaoye/SuperLU/|; provides serial @@ -96,7 +96,6 @@ 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 --help `configure' configures MLD2P4 1.0 to adapt to many kinds of systems. Usage: ./configure [OPTION]... [VAR=VALUE]... @@ -232,12 +231,12 @@ both of them are further divided into \verb|fileread| and 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 +\item[\tt tests] 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 or the -Harwell-Boeing storage format; the \verb|pargen| instead generate +Harwell-Boeing storage format; the \verb|pdegen| instead generate matrices in full parallel mode from the discretization of a sample PDE. diff --git a/docs/pdf/gettingstarted.tex b/docs/pdf/gettingstarted.tex index bcef17d5..df94329c 100644 --- a/docs/pdf/gettingstarted.tex +++ b/docs/pdf/gettingstarted.tex @@ -74,7 +74,7 @@ compilers. \begin{table}[th] \begin{center} %{\small -\begin{tabular}{|l|l|p{6.4cm}|} +\begin{tabular}{|l|l|p{7.8cm}|} \hline \textsc{type} & \textsc{string} & \textsc{default preconditioner} \\ \hline No preconditioner &\verb|'NOPREC'|& Considered only to use the PSBLAS @@ -89,15 +89,15 @@ Multilevel &\verb|'ML'| & Multi-level hybrid preconditioner (additive Number of levels: 2. Post-smoother: RAS with overlap 1 and ILU(0) on the local blocks. - Aggregation: smoothed aggregation with + Aggregation: decoupled smoothed aggregation with threshold $\theta = 0$. Coarsest matrix: distributed among the processors. Coarsest-level solver: 4 sweeps of the block-Jacobi solver, with LU (or ILU) factorization of the blocks (UMFPACK for the double precision versions and - SuperLU for the single precision ones, if they have been - installed; ILU(0), otherwise). \\ + SuperLU for the single precision ones, if the packages + have been installed; ILU(0), otherwise). \\ \hline \end{tabular} %} diff --git a/docs/pdf/userinterface.tex b/docs/pdf/userinterface.tex index fd457826..e3d5cf34 100644 --- a/docs/pdf/userinterface.tex +++ b/docs/pdf/userinterface.tex @@ -185,7 +185,7 @@ refer to Section~\ref{sec:background}. \verb|mld_sub_prol_| & \verb|character(len=*)| & \texttt{'SUM'} \hspace{2.5cm} \texttt{'NONE'} & \texttt{'NONE'} - & Type of prolongator operator: + & Type of prolongation operator: \texttt{'SUM'} for adding the contributions from the overlap, \texttt{'NONE'} for neglecting them. \\ \hline \verb|mld_sub_solve_| & \verb|character(len=*)| @@ -233,7 +233,7 @@ refer to Section~\ref{sec:background}. \verb|mld_aggr_thresh_| & \verb|real(|\emph{kind\_parameter}\verb|)| & Any~real~num. $\in [0, 1]$ & 0 - & The threshold $\theta$ in the aggregation algorithm. \\ \hline + & Threshold $\theta$ in the aggregation algorithm. \\ \hline \verb|mld_aggr_eig_| & \verb|character(len=*)| & \texttt{'A\_NORMI'} & \texttt{'A\_NORMI'} @@ -244,11 +244,12 @@ refer to Section~\ref{sec:background}. \verb|mld_aggr_damp_| & \verb|real(|\emph{kind\_parameter}\verb|)| & Any~real~num. & $4/(3||D^{-1}A||_\infty)$ - & The damping parameter $\omega$ in the smoothed aggregation algorithm. - If the user specifies a negative value, then $\omega$ is set to its default - value; otherwise, $\omega$ is set to the value provided by the - user. In the latter case no estimate of the eigenvalue $D^{-1}A$ with - largest modulus is computed.\\ + & Damping parameter $\omega$ in the smoothed aggregation algorithm. + If the user specifies a negative value, then $\omega$ + is set to its default value; + otherwise, $\omega$ is set to the value provided by the + user. In the latter case no estimate of the eigenvalue of + $D^{-1}A$ with largest modulus is computed.\\ \hline \end{tabular} \end{center} @@ -263,30 +264,36 @@ refer to Section~\ref{sec:background}. \verb|what| & \textsc{data type} & \verb|val| & \textsc{default} & \textsc{comments} \\ \hline %\multicolumn{5}{|c|}{\emph{coarse-space correction at the coarsest level}}\\ \hline -\verb|mld_coarse_solve_| & \verb|character(len=*)| - & \texttt{'BJAC'} \hspace{2.5cm} \texttt{'UMF'} \hspace{2.5cm} \texttt{'SLU'} - \hspace{2.5cm} \texttt{'SLUDIST'} - & \texttt{'BJAC'} - & Solver used at the coarsest level: block Jacobi, sequential LU from UMFPACK, - sequential LU from SuperLU, distributed LU from SuperLU\_Dist. - With \texttt{'SLUDIST'} the coarsest matrix - must be distributed; with \texttt{'UMF'} or - \texttt{'SLU'} it must be replicated. \\ \hline \verb|mld_coarse_mat_| & \verb|character(len=*)| & \texttt{'DISTR'} \hspace{2.5cm} \texttt{'REPL'} & \texttt{'DISTR'} - & Coarsest matrix: distributed among the processors or replicated on each of them. \\ \hline + & Coarsest matrix: distributed among the processors or + replicated on each of them. \\ \hline +\verb|mld_coarse_solve_| & \verb|character(len=*)| + & \texttt{'BJAC'} \hspace{2.5cm} \texttt{'UMF'} \hspace{2.5cm} + \texttt{'SLU'} \hspace{2.5cm} \texttt{'SLUDIST'} + & \texttt{'BJAC'} + & Solver used at the coarsest level: block Jacobi, sequential + LU from UMFPACK, sequential LU from SuperLU, + distributed LU from SuperLU\_Dist. + \texttt{'BJAC'} and \texttt{'SLUDIST'} require the coarsest + matrix to be distributed, while \texttt{'UMF'} and + \texttt{'SLU'} require it to be replicated. \\ \hline \verb|mld_coarse_subsolve_| & \verb|character(len=*)| - & \texttt{'ILU'} \hspace{2.5cm} \texttt{'MILU'} \hspace{2.5cm} \texttt{'ILUT'} + & \texttt{'ILU'} \hspace{2.5cm} \texttt{'MILU'} + \hspace{2.5cm} \texttt{'ILUT'} \hspace{2.5cm} \texttt{'UMF'} \hspace{2.5cm} \texttt{'SLU'} & \texttt{'UMF'} - & Solver for the diagonal blocks of the coarse matrix, in case the block Jacobi solver - is chosen as coarsest-level solver: ILU($p$), MILU($p$), ILU($p,t$), LU from UMFPACK, + & Solver for the diagonal blocks of the coarse matrix, + in case the block Jacobi solver + is chosen as coarsest-level solver: ILU($p$), MILU($p$), + ILU($p,t$), LU from UMFPACK, LU from SuperLU, plus triangular solve. \\ \hline \verb|mld_coarse_sweeps_|& \verb|integer| & Any~int.~num.~$> 0$ & 4 - & Number of Block-Jacobi sweeps when 'BJAC' is used as coarsest-level solver. \\ \hline + & Number of Block-Jacobi sweeps when 'BJAC' is used as + coarsest-level solver. \\ \hline \verb|mld_coarse_fillin_| & \verb|integer| & Any~int.~num.~$\ge 0$ & 0