Updated PENV with min/max.

Updated docs on utilities.

docs/pdf/methods.tex

@@ -17,10 +17,12 @@ the Krylov-Subspace family methods implemented in PSBLAS-2.0.
 
 The stopping criterion is the normwise backward error, in the infinity
 norm, i.e. the iteration is stopped when 
-\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \]
-or
-\[ \frac{\|r_i\|}{\|b\|_2} < eps \]
-according to the value passed through the  istop argument (see later).
+\[ err = \frac{\|r_i\|}{(\|A\|\|x_i\|+\|b\|)} < eps \]
+or the 2-norm residual reduction
+\[ err = \frac{\|r_i\|}{\|b\|_2} < eps \]
+according to the value passed through the  istop argument (see
+later). In the above formulae, $x_i$ is the tentative solution and
+$r_i=b-Ax_i$ the corresponding residual at the $i$-th iteration. 
 
 
 \syntax{call psb\_krylov}{method,a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}
@@ -74,8 +76,9 @@ Scope: {\bf global} \\
 Type: {\bf optional}\\
 \item[istop]  An integer specifying the stopping criterion.\\
 Scope: {\bf global} \\
-Type: {\bf optional}\\
-
+Type: {\bf optional}.\\
+Values: 1: use the normwise backward error, 2: use the scaled 2-norm
+of the residual. Default: 1. 
 \item[\bf On Return] 
 \item[x] The computed solution. \\
 Scope: {\bf local} \\

docs/pdf/penv.tex

@@ -292,6 +292,96 @@ Type, rank and size must agree on all processes.
 
 
 
+\subroutine{psb\_max}{Global maximum}
+
+\syntax{call psb\_max}{icontxt, dat, root}
+
+This subroutine implements a maximum valuereduction
+operation based on the underlying communication library. 
+\begin{description}
+\item[\bf  On Entry ]
+\item[icontxt] the communication context identifying the virtual
+  parallel machine.\\
+Scope:{\bf global}.\\
+Type:{\bf required}.\\
+Specified as: an integer variable.
+\item[dat] The local contribution to the global maximum.\\
+Scope:{\bf local}.\\
+Type:{\bf required}.\\
+Specified as: an integer or  real variable, which may be a
+scalar, or a rank 1 or 2 array. \
+Type, rank and size must agree on all processes.
+\item[root] Process to hold the final maximum, or $-1$ to make it available
+  on all processes.\\
+Scope:{\bf global}.\\
+Type:{\bf optional}.\\
+Specified as: an integer value $-1<= root <= np-1$, default -1. \\
+\end{description}
+
+
+\begin{description}
+\item[\bf On Return]
+\item[dat] On destination process(es), the result of the maximum operation.\\
+Scope:{\bf global}.\\
+Type:{\bf required}.\\
+Specified as: an integer or  real variable, which may be a
+scalar, or a rank 1 or 2 array. \
+Type, rank and size must agree on all processes.
+\end{description}
+
+
+\section*{Notes}
+\begin{enumerate}
+\item The \verb|dat| argument is both input and output, and its
+  value may be changed even on processes different from the final
+  result destination.
+\end{enumerate}
+
+\subroutine{psb\_min}{Global minimum}
+
+\syntax{call psb\_min}{icontxt, dat, root}
+
+This subroutine implements a minimum value reduction
+operation based on the underlying communication library. 
+\begin{description}
+\item[\bf  On Entry ]
+\item[icontxt] the communication context identifying the virtual
+  parallel machine.\\
+Scope:{\bf global}.\\
+Type:{\bf required}.\\
+Specified as: an integer variable.
+\item[dat] The local contribution to the global minimum.\\
+Scope:{\bf local}.\\
+Type:{\bf required}.\\
+Specified as: an integer  or real variable, which may be a
+scalar, or a rank 1 or 2 array. \
+Type, rank and size must agree on all processes.
+\item[root] Process to hold the final value, or $-1$ to make it available
+  on all processes.\\
+Scope:{\bf global}.\\
+Type:{\bf optional}.\\
+Specified as: an integer value $-1<= root <= np-1$, default -1. \\
+\end{description}
+
+
+\begin{description}
+\item[\bf On Return]
+\item[dat] On destination process(es), the result of the minimum operation.\\
+Scope:{\bf global}.\\
+Type:{\bf required}.\\
+Specified as: an integer  or  real variable, which may be a
+scalar, or a rank 1 or 2 array. \\
+Type, rank and size must agree on all processes.
+\end{description}
+
+
+\section*{Notes}
+\begin{enumerate}
+\item The \verb|dat| argument is both input and output, and its
+  value may be changed even on processes different from the final
+  result destination.
+\end{enumerate}
+
 \subroutine{psb\_amx}{Global maximum absolute value}
 
 \syntax{call psb\_amx}{icontxt, dat, root}
@@ -311,7 +401,7 @@ Type:{\bf required}.\\
 Specified as: an integer, real or complex variable, which may be a
 scalar, or a rank 1 or 2 array. \
 Type, rank and size must agree on all processes.
-\item[root] Process to hold the final sum, or $-1$ to make it available
+\item[root] Process to hold the final value, or $-1$ to make it available
   on all processes.\\
 Scope:{\bf global}.\\
 Type:{\bf optional}.\\
@@ -356,7 +446,7 @@ Type:{\bf required}.\\
 Specified as: an integer, real or complex variable, which may be a
 scalar, or a rank 1 or 2 array. \
 Type, rank and size must agree on all processes.
-\item[root] Process to hold the final sum, or $-1$ to make it available
+\item[root] Process to hold the final value, or $-1$ to make it available
   on all processes.\\
 Scope:{\bf global}.\\
 Type:{\bf optional}.\\

docs/pdf/userguide.tex

@@ -35,7 +35,9 @@
 
 \newcounter{subroutine}[subsection]
 \newcounter{example}[subroutine]
-\newcommand{\subroutine}[2]{\clearpage%
+\makeatletter
+\def\subroutine{\@ifstar{\@subroutine}{\clearpage\@subroutine}}%
+\def\@subroutine#1#2{%
 \stepcounter{subroutine}%
       \section*{\flushleft #1---#2 \endflushleft}%
       \addcontentsline{toc}{subsection}{#1}%
@@ -47,7 +49,6 @@
       \markright{#1}}%
 \newcommand{\examplename}{Example}
 \newcommand{\syntaxname}{Syntax}
-\makeatletter
 \def\syntax{\@ifstar{\@ssyntax}{\@syntax}}%
 \def\@syntax{\section*{\syntaxname}%
      \@ssyntax}%

docs/pdf/util.tex

@@ -2,6 +2,148 @@
 \label{sec:util}
 
 
+\subroutine{PSB\_HBIO\_MOD}{Input/Output in Harwell-Boeing format}
+
+\subroutine*{hb\_read}{Read a sparse matrix from a file}
+\syntax{call hb\_read}{a, iret, iunit, filename, b, mtitle}
+ 
+\begin{description}
+\item[\bf  On Entry ]
+\item[filename] The name of the file to be read.\\
+Type:{\bf optional}.\\
+Specified as: a character variable containing a valid file name, or
+\verb|-|, in which case the default input unit  5 (i.e. standard input
+in Unix jargon) is used. Default: \verb|-|. 
+\item[iunit] The Fortran file unit number.\\
+Type:{\bf optional}.\\
+Specified as: an integer value. Only meaningful if filename is not \verb|-|.
+\end{description}
+
+\begin{description}
+\item[\bf On Return]
+\item[a] the sparse matrix read from file.\\
+Type:{\bf required}.\\
+Specified as: a structured data of type \spdata.
+\item[b] Rigth hand side.\\
+Type: {\bf Optional} \\
+An  array of type real or complex, rank 1 and having the ALLOCATABLE
+attribute; will be allocated and filled in if the input file contains
+a right hand side. 
+\item[mtitle] Matrix title.\\
+Type: {\bf Optional} \\
+A charachter variable of length 72 holding a copy of the
+matrix title as specified by the Harwell-Boeing format and contained
+in the input file.
+\item[iret] Error code.\\
+Type: {\bf required} \\
+An integer value; 0 means no error has been detected. 
+\end{description}
+
+
+
+\subroutine*{hb\_write}{Write a sparse matrix to a  file}
+\syntax{call hb\_write}{a, iret, iunit, filename, key, rhs, mtitle}
+
+
+
+\begin{description}
+\item[\bf  On Entry ]
+\item[a] the sparse matrix to be written.\\
+Type:{\bf required}.\\
+Specified as: a structured data of type \spdata.
+\item[b] Rigth hand side.\\
+Type: {\bf Optional} \\
+An  array of type real or complex, rank 1 and having the ALLOCATABLE
+attribute; will be allocated and filled in if the input file contains
+a right hand side. 
+\item[filename] The name of the file to be written to.\\
+Type:{\bf optional}.\\
+Specified as: a character variable containing a valid file name, or
+\verb|-|, in which case the default output unit  6 (i.e. standard output
+in Unix jargon) is used. Default: \verb|-|. 
+\item[iunit] The Fortran file unit number.\\
+Type:{\bf optional}.\\
+Specified as: an integer value. Only meaningful if filename is not \verb|-|.
+\item[key] Matrix key.\\
+Type: {\bf Optional} \\
+A charachter variable of length 8 holding the
+matrix key as specified by the Harwell-Boeing format and to be
+written to file.
+\item[mtitle] Matrix title.\\
+Type: {\bf Optional} \\
+A charachter variable of length 72 holding the
+matrix title as specified by the Harwell-Boeing format and to be
+written to file.
+\end{description}
+
+\begin{description}
+\item[\bf On Return]
+\item[iret] Error code.\\
+Type: {\bf required} \\
+An integer value; 0 means no error has been detected. 
+\end{description}
+
+
+
+
+\subroutine{PSB\_MMIO\_MOD}{Input/Output in MatrixMarket format}
+
+\subroutine*{mm\_mat\_read}{Read a sparse matrix from a file}
+\syntax{call mm\_mat\_read}{a, iret, iunit, filename}
+
+\begin{description}
+\item[\bf  On Entry ]
+\item[filename] The name of the file to be read.\\
+Type:{\bf optional}.\\
+Specified as: a character variable containing a valid file name, or
+\verb|-|, in which case the default input unit  5 (i.e. standard input
+in Unix jargon) is used. Default: \verb|-|. 
+\item[iunit] The Fortran file unit number.\\
+Type:{\bf optional}.\\
+Specified as: an integer value. Only meaningful if filename is not \verb|-|.
+\end{description}
+
+\begin{description}
+\item[\bf On Return]
+\item[a] the sparse matrix read from file.\\
+Type:{\bf required}.\\
+Specified as: a structured data of type \spdata.
+\item[iret] Error code.\\
+Type: {\bf required} \\
+An integer value; 0 means no error has been detected. 
+\end{description}
+
+
+
+\subroutine*{mm\_mat\_write}{Write a sparse matrix to a  file}
+\syntax{call mm\_mat\_write}{a, mtitle, iret, iunit, filename}
+\begin{description}
+\item[\bf  On Entry ]
+\item[a] the sparse matrix to be written.\\
+Type:{\bf required}.\\
+Specified as: a structured data of type \spdata.
+\item[mtitle] Matrix title.\\
+Type: {\bf required} \\
+A charachter variable holding a descriptive title for the matrix to be
+ written to file.
+\item[filename] The name of the file to be written to.\\
+Type:{\bf optional}.\\
+Specified as: a character variable containing a valid file name, or
+\verb|-|, in which case the default output unit  6 (i.e. standard output
+in Unix jargon) is used. Default: \verb|-|. 
+\item[iunit] The Fortran file unit number.\\
+Type:{\bf optional}.\\
+Specified as: an integer value. Only meaningful if filename is not \verb|-|.
+\end{description}
+
+\begin{description}
+\item[\bf On Return]
+\item[iret] Error code.\\
+Type: {\bf required} \\
+An integer value; 0 means no error has been detected. 
+\end{description}
+
+
 
 %%% Local Variables: 
 %%% mode: latex