docs/pdf/datastruct.tex

@@ -9,7 +9,7 @@ communication descriptors and preconditioners.%%  These data structures
 %% be used to next chapters containing these callings.  
 
 All the data types and subroutine interfaces are defined in the module
-\verb|psb_sparse_mod|; this will have to be included by every user
+\verb|psb_base_mod|; this will have to be included by every user
 subroutine that makes use of the library. 
 
 

docs/pdf/precs.tex

@@ -3,28 +3,30 @@
 
 % \section{Preconditioners}
 \label{sec:psprecs}
-PSBLAS contains the implementation of many preconditioning
-techniques some of which are very flexible thanks to the presence of
-many parameters that is possible to adjust to fit the user's needs:
+The base PSBLAS library  contains the implementation of two simple
+preconditioning techniques:
 \begin{itemize}
 \item Diagonal Scaling
 \item Block Jacobi with ILU(0) factorization
 %% \item Additive Schwarz with the Restricted Additive Schwarz and
 %%   Additive Schwarz with Harmonic extensions;
 \end{itemize}
-The PSBLAS library is incorporating a package of two-level Additive
-  Schwarz preconditioners called MD2P4; this is actually a family of 
-  preconditioners since there is the possibility to choose between
-  many variants, and is currently in an experimental state. Its
-  documentation is planned to appear after stabilization of the
-  package, which will characterize release  2.1 of our library.
+The supporting data type and subroutine interfaces are defined in the
+module  \verb|psb_prec_mod|.
+
+%% We also provide a companion  package of multi-level Additive
+%%   Schwarz preconditioners called MD2P4; this is actually a family of 
+%%   preconditioners since there is the possibility to choose between
+%%   many variants, and is currently in an experimental stateIts
+%%   documentation is planned to appear after stabilization of the
+%%   package, which will characterize release  2.1 of our library.
 
 
 
 
 \subroutine{psb\_precset}{Sets the preconditioner type}
 
-\syntax{call psb\_precset}{prec, ptype, info, iv, rs}
+\syntax{call psb\_precset}{prec, ptype, info}
 
 \begin{description}
 \item[\bf On Entry]
@@ -36,14 +38,14 @@ Specified as: a pronditioner data structure \precdata.
 Scope: {\bf global} \\
 Type: {\bf required}\\
 Specified as: a character string, see usage notes.
-\item[iv] integer parameters for the precondtioner. 
-Scope: {\bf global} \\
-Type: {\bf required}\\
-Specified as: an integer array, see usage notes. 
-\item[rs] 
-Scope: {\bf global} \\
-Type: {\bf optional}\\
-Specified as: a long precision real number.
+%% \item[iv] integer parameters for the precondtioner. 
+%% Scope: {\bf global} \\
+%% Type: {\bf required}\\
+%% Specified as: an integer array, see usage notes. 
+%% \item[rs] 
+%% Scope: {\bf global} \\
+%% Type: {\bf optional}\\
+%% Specified as: a long precision real number.
 \item[\bf On Exit]
 
 \item[info] 
@@ -52,10 +54,10 @@ Type: {\bf required}\\
 Error code: if no error, 0 is returned.
 \end{description}
 \section*{Usage Notes}
-The PSBLAS 2.0 contains a number of preconditioners, ranging from a
-simple diagonal scaling to 2-level domain decomposition. These
-preconditioners may use the SuperLU or the UMFPACK software, if
-installed; see~\cite{SUPERLU,UMFPACK}. 
+%% The PSBLAS 2.0 contains a number of preconditioners, ranging from a
+%% simple diagonal scaling to 2-level domain decomposition. These
+%% preconditioners may use the SuperLU or the UMFPACK software, if
+%% installed; see~\cite{SUPERLU,UMFPACK}. 
 Legal inputs to this subroutine are interpreted depending on the
 $ptype$ string as follows\footnote{The string is case-insensitive}:
 \begin{description}
@@ -64,7 +66,7 @@ $ptype$ string as follows\footnote{The string is case-insensitive}:
 \item[DIAG] Diagonal scaling; each entry of the input vector is
   multiplied by the reciprocal of the sum of the absolute values of
   the coefficients in the corresponding row of matrix  $A$;
-\item[ILU] Precondition by the incomplete LU factorization of the
+\item[ILU, BJA] Precondition by the incomplete LU factorization of the
   block-diagonal of matrix $A$, where block boundaries are determined
   by the data allocation boundaries for each process; requires no
   communication. Only $ILU(0)$ is currently implemented. 

docs/pdf/title.tex

@@ -5,7 +5,7 @@
 
 \ifx\pdfoutput\undefined % We're not running pdftex
 \else
-\pdfbookmark{PSBLAS-v2.0.2 User's Guide}{title}
+\pdfbookmark{PSBLAS-v2.1 User's Guide}{title}
 \fi
 \newlength{\centeroffset}
 \setlength{\centeroffset}{-0.5\oddsidemargin}

docs/pdf/toolsrout.tex

@@ -7,50 +7,44 @@
 %
 \subroutine{psb\_cdall}{Allocates a communication descriptor}
 
-\syntax{call psb\_cdall}{m, n, parts, icontxt, desc\_a, info}
-\syntax*{call psb\_cdall}{m, v, icontxt, desc\_a, info, flag}
+\syntax{call psb\_cdall}{icontxt, desc\_a, info,mg=mg,parts=parts}
+\syntax{call psb\_cdall}{icontxt, desc\_a, info,vg=vg,flag=flag}
+\syntax{call psb\_cdall}{icontxt, desc\_a, info,vl=vl}
 
 This subroutine initializes the communication descriptor associated
-with an index space. It takes two forms depending on whether the user
-specifies the domain partitioning through a subroutine or through a vector
+with an index space. Exactly one of the  optional arguments
+\verb|parts|, \verb|vg|, \verb|vl| must be specified, thereby choosing
+the specific initialization strategy:
 \begin{description}
-\item[\bf  First Form: On Entry ]
-\item[m] the number of rows of the problem.\\
+\item[\bf  On Entry ]
+\item[icontxt] the communication context.\\
 Scope:{\bf global}.\\
 Type:{\bf required}.\\
 Specified as: an integer value.
-\item[n] the number of columns of the problem.\\
+\item[vg] Data allocation: each index $i\in \{1\dots mg\}$ is allocated
+  to process $vg(i)$.
 Scope:{\bf global}.\\
-Type:{\bf required}.\\
-Specified as: an integer value. Currently constrained to be  $m=n$.
+Type:{\bf optional}.\\
+Specified as: an integer array. 
+\item[flag] Specifies whether entries in $vg$ are zero- or one-based.
+Scope:{\bf global}.\\
+Type:{\bf optional}.\\
+Specified as: an integer value $0,1$, default $0$.
+
+\item[mg] the (global) number of rows of the problem.\\
+Scope:{\bf global}.\\
+Type:{\bf optional}.\\
+Specified as: an integer value. It is required if \verb|parts| is
+specified. 
 \item[parts] the subroutine that defines the partitioning scheme.\\
 Scope:{\bf global}.\\
 Type:{\bf required}.\\
 Specified as: a subroutine. 
-\item[icontxt] the communication context.\\
-Scope:{\bf global}.\\
-Type:{\bf required}.\\
-Specified as: an integer value.
-\end{description}
-\begin{description}
-\item[\bf  Second Form: On Entry ]
-\item[m] the size of the index space.\\
-Scope:{\bf global}.\\
-Type:{\bf required}.\\
-Specified as: an integer value $m>0$.
-\item[v] Data allocation: each index $i\in \{1\dots m\}$ is allocated
-  to process $v(i)$.
-Scope:{\bf global}.\\
-Type:{\bf required}.\\
-Specified as: an integer array of size $m$. 
-\item[icontxt] the communication context.\\
-Scope:{\bf global}.\\
-Type:{\bf required}.\\
-Specified as: an integer value.
-\item[flag] Specifies whether entries in $v$ are zero- or one-based.
-Scope:{\bf global}.\\
+\item[vl] Data allocation: the set of global indices belonging to the
+  calling process. 
+Scope:{\bf local}.\\
 Type:{\bf optional}.\\
-Specified as: an integer value $0,1$, default $0$.
+Specified as: an integer array. 
 \end{description}
 
 \begin{description}
@@ -67,6 +61,28 @@ Specified as: an integer variable.\\
 
 \section*{Notes}
 \begin{enumerate}
+\item Exactly one of the optional arguments  \verb|parts|, \verb|vg|,
+  \verb|vl| must be specified, thereby choosing the initialization
+  strategy as follows:
+\begin{description}
+\item[parts] In this case we have a subroutine that takes as input a
+  index and the total number of indices in the space, and produces in
+  output a  vector containing the set of processes (usually with just
+  one entry) to which the index should be assigned. If this argument
+  is specified, then it is mandatory to also specify the argument
+  \verb|mg|. 
+\item[vg] In this case the association between an index and a process
+  is specified via an integer vector; the size of the index space is
+  equal to the size of \verb|vg|, and each index $i$ is assigned to
+  the process $vg(i)$. The vector \verb|vg| must be identical on all
+  calling processes; its entries may have the ranges $(0\dots np-1)$
+  or $(1\dots np)$ according to the value of \verb|flag|.
+\item[vl] In this case we are specifying the list of indices assigned
+  to the current process; thus, the global problem size $mg$ is given by
+  the sum of the sizes of the individual vectors \verb|vl| specified
+  on the calling processes. The subroutine will check that each entry
+  in the global index space $(1\dots mg)$ is specified exactly once.
+\end{description}
 \item On exit from this routine the descriptor is in the build state
 \end{enumerate}
 

docs/pdf/userguide.tex

@@ -88,11 +88,11 @@
 \include{psbrout}
 \include{commrout}
 \include{toolsrout}
-\include{methods}
-\include{precs}
 \include{penv}
 \include{error}
-
+\include{util}
+\include{precs}
+\include{methods}
 
 \clearpage
 
@@ -156,7 +156,7 @@ Cambridge University Press.
 \bibitem{APNUM06}
 P.~D'Ambra, D.~di Serafino and S.~Filippone,
 On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners,
-Applied Numerical Mathematics, to appear, 2006.
+Applied Numerical Mathematics, to appear, 2007.
 %
 \bibitem{UMFPACK}
 T.A.~Davis, 

docs/pdf/util.tex

@@ -0,0 +1,9 @@
+\section{Utilities}
+\label{sec:util}
+
+
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "userguide"
+%%% End: