\section{Iterative Methods}
\label{sec:methods}

In this chapter we provide routines for preconditioners and iterative
methods. The interfaces for Krylov subspace methods are available in
the module \verb|psb_krylov_mod|.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  Krylov Methods driver routine
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subroutine{psb\_krylov \label{krylov}}{Krylov Methods Driver Routine}

This subroutine is a driver that provides a general interface for all
the Krylov-Subspace family methods implemented in PSBLAS version 2. 

The stopping criterion is the normwise backward error, in the infinity
norm, i.e. the iteration is stopped when 
\[ 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,irst,istop}

\begin{description}
\item[\bf On Entry]
\item[method] a string that defines the iterative method to be
  used. Supported values are:
  \begin{description}
  \item[CG]: the Conjugate Gradient method;
  \item[CGS]:the Conjugate Gradient Stabilized method;

  \item[BICG]: the Bi-Conjugate Gradient method;
  \item[BICGSTAB]: the Bi-Conjugate Gradient Stabilized method;
  \item[BICGSTABL]: the Bi-Conjugate Gradient Stabilized method with restarting;
  \item[RGMRES]: the Generalized Minimal Residual method with restarting.
  \end{description}
\item[a] the local portion of global sparse matrix
$A$. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\item[prec] The data structure containing the preconditioner.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \precdata.
\item[b] The RHS vector. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a rank one array.
\item[x] The initial guess. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one array.
\item[eps] The stopping tolerance. \\
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a real number. 
\item[desc\_a] contains data structures for communications.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[itmax]  The maximum number of iterations to perform.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Default: $itmax = 1000$.\\
Specified as: an integer variable $itmax \ge 1$.
\item[itrace] If $>0$  print out an informational message about
  convergence  every $itrace$ iterations.\\ 
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
\item[irst]  An integer specifying the restart parameter.\\
Scope: {\bf global} \\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Values: $irst>0$. This is employed for the BiCGSTABL or RGMRES
methods, otherwise it is ignored. 

\item[istop]  An integer specifying the stopping criterion.\\
Scope: {\bf global} \\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one array.
\item[iter]  The number of iterations performed.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Returned  as: an integer variable.
\item[err]  The convergence estimate on exit.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Returned  as: a real number.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected. 
\end{description}

%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% %      CG
%% %
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% \subroutine{psb\_cg \label{cg}}{CG Iterative Method}

%% This subroutine implements the CG method with restarting. 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).


%% \syntax{call psb\_cg}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the local portion of global sparse matrix
%% $A$. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[prec] The data structure containing the preconditioner.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \precdata.
%% \item[b] The RHS vector. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[x] The initial guess. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[eps] The stopping tolerance. \\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: a real number. 
%% \item[desc\_a] contains data structures for communications.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \descdata.
%% \item[itmax]  The maximum number of iterations to perform.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Default: $itmax = 1000$.\\
%% Specified as: an integer variable $itmax \ge 1$.
%% \item[itrace] If $>0$  print out an informational message about
%%   convergence  every $itrace$ iterations.\\ 
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[istop]  An integer specifying the stopping criterion.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\

%% \item[\bf On Return] 
%% \item[x] The computed solution. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[iter]  The number of iterations performed.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: an integer variable.
%% \item[err]  The error estimate on exit.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: a real number.
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required} \\
%% An integer value; 0 means no error has been detected. 
%% \end{description}
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% %      CGS
%% %
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% \subroutine{psb\_cgs \label{cgs}}{CGS Iterative Method}

%% This subroutine implements the CGS method with restarting. 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).


%% \syntax{call psb\_cgs}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the local portion of global sparse matrix
%% $A$. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[prec] The data structure containing the preconditioner.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \precdata.
%% \item[b] The RHS vector. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[x] The initial guess. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[eps] The stopping tolerance. \\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: a real number. 
%% \item[desc\_a] contains data structures for communications.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \descdata.
%% \item[itmax]  The maximum number of iterations to perform.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Default: $itmax = 1000$.\\
%% Specified as: an integer variable $itmax \ge 1$.
%% \item[itrace]  If $>0$  print out an informational message about
%%   convergence  every $itrace$ iterations.\\ 
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[istop]  An integer specifying the stopping criterion.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\

%% \item[\bf On Return] 
%% \item[x] The computed solution. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[iter]  The number of iterations performed.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: an integer variable.
%% \item[err]  The error estimate on exit.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: a real number.
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required} \\
%% An integer value; 0 means no error has been detected. 
%% \end{description}

%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% %      BiCG
%% %
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% \subroutine{psb\_bicg \label{bicg}}{BiCG Iterative Method}

%% This subroutine implements the BiCG method with restarting. 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).


%% \syntax{call psb\_bicg}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the local portion of global sparse matrix
%% $A$. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[prec] The data structure containing the preconditioner.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \precdata.
%% \item[b] The RHS vector. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[x] The initial guess. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[eps] The stopping tolerance. \\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: a real number. 
%% \item[desc\_a] contains data structures for communications.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \descdata.
%% \item[itmax]  The maximum number of iterations to perform.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Default: $itmax = 1000$.\\
%% Specified as: an integer variable $itmax \ge 1$.
%% \item[itrace] If $>0$  print out an informational message about
%%   convergence  every $itrace$ iterations.\\ 
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[istop]  An integer specifying the stopping criterion.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\

%% \item[\bf On Return] 
%% \item[x] The computed solution. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[iter]  The number of iterations performed.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: an integer variable.
%% \item[err]  The error estimate on exit.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: a real number.
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required} \\
%% An integer value; 0 means no error has been detected. 
%% \end{description}


%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% %      BiCGSTAB
%% %
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% \subroutine{psb\_bicgstab \label{bicgstab}}{BiCGSTAB Iterative Method}

%% This subroutine implements the BiCGSTAB method with restarting. 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).


%% \syntax{call psb\_bicgstab}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the local portion of global sparse matrix
%% $A$. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[prec] The data structure containing the preconditioner.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \precdata.
%% \item[b] The RHS vector. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[x] The initial guess. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[eps] The stopping tolerance. \\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: a real number. 
%% \item[desc\_a] contains data structures for communications.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \descdata.
%% \item[itmax]  The maximum number of iterations to perform.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Default: $itmax = 1000$.\\
%% Specified as: an integer variable $itmax \ge 1$.
%% \item[itrace]  If $>0$  print out an informational message about
%%   convergence  every $itrace$ iterations.\\ 
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[istop]  An integer specifying the stopping criterion.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\

%% \item[\bf On Return] 
%% \item[x] The computed solution. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[iter]  The number of iterations performed.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: an integer variable.
%% \item[err]  The error estimate on exit.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: a real number.
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required} \\
%% An integer value; 0 means no error has been detected. 
%% \end{description}


%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% %      BiCGSTAB(L)
%% %
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% \subroutine{psb\_bicgstabl \label{bicgstabl}}{BiCGSTAB-$l$ Iterative Method}

%% This subroutine implements the BiCGSTAB-$l$ method with restarting. 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).


%% \syntax{call psb\_bicgstab}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,irst,istop}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the local portion of global sparse matrix
%% $A$. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[prec] The data structure containing the preconditioner.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \precdata.
%% \item[b] The RHS vector. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[x] The initial guess. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[eps] The stopping tolerance. \\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: a real number. 
%% \item[desc\_a] contains data structures for communications.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \descdata.
%% \item[itmax]  The maximum number of iterations to perform.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Default: $itmax = 1000$.\\
%% Specified as: an integer variable $itmax \ge 1$.
%% \item[itrace]  If $>0$  print out an informational message about
%%   convergence  every $itrace$ iterations.\\ 
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[irst]  An integer specifying the restarting iteration.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[istop]  An integer specifying the stopping criterion.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\

%% \item[\bf On Return] 
%% \item[x] The computed solution. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[iter]  The number of iterations performed.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: an integer variable.
%% \item[err]  The error estimate on exit.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: a real number.
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required} \\
%% An integer value; 0 means no error has been detected. 
%% \end{description}


%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% %
%% %      GMRES
%% %
%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% \subroutine{psb\_gmres \label{gmres}}{GMRES Iterative Method}

%% This subroutine implements the GMRES method with restarting. 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).


%% \syntax{call psb\_gmres}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,irst,istop}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the local portion of global sparse matrix
%% $A$. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[prec] The data structure containing the preconditioner.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \precdata.
%% \item[b] The RHS vector. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[x] The initial guess. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[eps] The stopping tolerance. \\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: a real number. 
%% \item[desc\_a] contains data structures for communications.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a structured data of type \descdata.
%% \item[itmax]  The maximum number of iterations to perform.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Default: $itmax = 1000$.\\
%% Specified as: an integer variable $itmax \ge 1$.
%% \item[itrace]  If $>0$  print out an informational message about
%%   convergence  every $itrace$ iterations.\\ 
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[irst]  An integer specifying the restart iteration.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% \item[istop]  An integer specifying the stopping criterion.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\

%% \item[\bf On Return] 
%% \item[x] The computed solution. \\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a rank one array.
%% \item[iter]  The number of iterations performed.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: an integer variable.
%% \item[err]  The error estimate on exit.\\
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Returned  as: a real number.
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required} \\
%% An integer value; 0 means no error has been detected. 
%% \end{description}





%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: