mirror of
https://github.com/sfilippone/psblas3.git
synced 2026-10-06 22:55:08 +00:00
*** empty log message ***
This commit is contained in:
Alfredo Buttari
+1
-1
@@ -85,7 +85,7 @@
|
||||
|
||||
TOPFILE = userguide.tex
|
||||
SECFILE = title.tex intro.tex commrout.tex datastruct.tex psbrout.tex toolsrout.tex\
|
||||
methods.tex precs.tex
|
||||
methods.tex precs.tex error.tex
|
||||
FIGDIR = figures
|
||||
|
||||
XPDFFLAGS =
|
||||
|
||||
@@ -0,0 +1,201 @@
|
||||
\section{Error handling}
|
||||
|
||||
The PSBLAS library error handling policy has been completely rewritten
|
||||
in version 2.0. The idea behind the design of this new error handling
|
||||
strategy is to keep error messages on a stack allowing the user to
|
||||
trace back up to the point where the first error message has been
|
||||
generated. Every routine in the PSBLAS-2.0 library has, as last
|
||||
non-optional argument, an integer \verb|info| variable; whenever,
|
||||
inside the routine, en error is detected, this variable is set to a
|
||||
value corresponding to a specific error code. Then this error code is
|
||||
also pushed on the error stack and then either control is returned to
|
||||
the caller routine or the execution is aborted, depending on the users
|
||||
choice. At the time when the execution is aborted, an error message is
|
||||
printed on standard output with a level of verbosity than can be
|
||||
chosen by the user. If the execution is not aborted, then, the caller
|
||||
routine checks the value returned in the \verb|info| variable and, if
|
||||
not zero, an error condition is raised. This process continues on all the
|
||||
levels of nested calls until the level where the user decides to abort
|
||||
the program execution.
|
||||
|
||||
Figure~\ref{fig:routerr} shows the layout of a generic \verb|psb_foo|
|
||||
routine with respect to the PSBLAS-2.0 error handling policy. It is
|
||||
possible to see how, whenever an error condition is detected, the
|
||||
\verb|info| variable is set to the corresponding error code which is,
|
||||
then, pushed on top of the stack by means of the
|
||||
\verb|psb_errpush|. An error condition may be directly detected inside
|
||||
a routine or indirectly checking the error code returned returned by a
|
||||
called routine. Whenever an error is encountered, after it has been
|
||||
pushed on stack, the program execution skips to a point where the
|
||||
error condition is handled; the error condition is handled either by
|
||||
returning control to the caller routine or by calling the
|
||||
\verb|psb\_error| routine which prints the content of the error stack
|
||||
and aborts the program execution.
|
||||
|
||||
\begin{figure}[h!]
|
||||
\begin{Sbox}
|
||||
\begin{minipage}[tl]{0.95\textwidth}
|
||||
\small
|
||||
\begin{verbatim}
|
||||
subroutine psb_foo(some args, info)
|
||||
...
|
||||
if(error detected) then
|
||||
info=errcode1
|
||||
call psb_errpush('psb_foo', errcode1)
|
||||
goto 9999
|
||||
end if
|
||||
...
|
||||
call psb_bar(some args, info)
|
||||
if(info .ne. zero) then
|
||||
info=errcode2
|
||||
call psb_errpush('psb_foo', errcode2)
|
||||
goto 9999
|
||||
end if
|
||||
...
|
||||
9999 continue
|
||||
if (err_act .eq. act_abort) then
|
||||
call psb_error(icontxt)
|
||||
return
|
||||
else
|
||||
return
|
||||
end if
|
||||
|
||||
end subroutine psb_foo
|
||||
\end{verbatim}
|
||||
\end{minipage}
|
||||
\end{Sbox}
|
||||
\setlength{\fboxsep}{8pt}
|
||||
\begin{center}
|
||||
\fbox{\TheSbox}
|
||||
\end{center}
|
||||
\caption{\label{fig:routerr}The layout of a generic \texttt{psb\_foo}
|
||||
routine with respect to PSBLAS-2.0 error handling policy.}
|
||||
\end{figure}
|
||||
|
||||
|
||||
|
||||
|
||||
Figure~\ref{fig:errormsg} reports a sample error message generated by
|
||||
the PSBLAS-2.0 library. This error has been generated by the fact that
|
||||
the user has chosen the invalid ``FOO'' storage format to represent
|
||||
the sparse matrix. From this error message it is possible to see that
|
||||
the error has been detected inside the \verb|psb_cest| subroutine
|
||||
called by \verb|psb_spasb| ... by process 0 (i.e. the root process).
|
||||
|
||||
|
||||
\begin{figure}[h!]
|
||||
\begin{Sbox}
|
||||
\begin{minipage}[tl]{0.95\textwidth}
|
||||
\begin{verbatim}
|
||||
==========================================================
|
||||
Process: 0. PSBLAS Error (4010) in subroutine: df_sample
|
||||
Error from call to subroutine mat dist
|
||||
==========================================================
|
||||
Process: 0. PSBLAS Error (4010) in subroutine: mat_distv
|
||||
Error from call to subroutine psb_spasb
|
||||
==========================================================
|
||||
Process: 0. PSBLAS Error (4010) in subroutine: psb_spasb
|
||||
Error from call to subroutine psb_cest
|
||||
==========================================================
|
||||
Process: 0. PSBLAS Error (136) in subroutine: psb_cest
|
||||
Format FOO is unknown
|
||||
==========================================================
|
||||
Aborting...
|
||||
\end{verbatim}
|
||||
\end{minipage}
|
||||
\end{Sbox}
|
||||
\setlength{\fboxsep}{8pt}
|
||||
\begin{center}
|
||||
\fbox{\TheSbox}
|
||||
\end{center}
|
||||
\caption{\label{fig:errormsg}A sample PSBLAS-2.0 error
|
||||
message. Process 0 detected an error condition inside the {\textrm
|
||||
psb\_cest} subroutine}
|
||||
\end{figure}
|
||||
|
||||
|
||||
\subroutine{psb\_errpush}{Pushes an error code onto the error stack}
|
||||
|
||||
\syntax{call psb\_errpush}{err\_c, r\_name, i\_err, a\_err}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[err\_c] the error code\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\item[r\_name] the soutine where the error has been caught.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a string.\\
|
||||
\item[i\_err] addional info for error code\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: an integer array\\
|
||||
\item[a\_err] addional info for error code\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: a string.\\
|
||||
\end{description}
|
||||
|
||||
\subroutine{psb\_error}{Prints the error stack content and aborts execution}
|
||||
|
||||
\syntax{call psb\_error}{icontxt}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[icontxt] the communication context.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: an integer.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_set\_errverbosity}{Sets the verbosity of error messages.}
|
||||
|
||||
\syntax{call psb\_set\_errverbosity}{v}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[v] the verbosity level\\
|
||||
Scope: {\bf global}\\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\end{description}
|
||||
|
||||
\subroutine{psb\_set\_erraction}{Set the type of action to be taken
|
||||
upon error condition.}
|
||||
|
||||
\syntax{call psb\_set\_erraction}{err\_act}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[err\_act] the type of action.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_errcomm}{Error communication routine}
|
||||
|
||||
\syntax{call psb\_errcomm}{icontxt, err}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[icontxt] the communication context.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.
|
||||
\item[err] the error code to be communicated\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.\\
|
||||
\end{description}
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "userguide"
|
||||
%%% End:
|
||||
@@ -1,6 +1,148 @@
|
||||
\section{Preconditioner routines}
|
||||
\label{sec:precs}
|
||||
|
||||
% \section{Preconditioners}
|
||||
\label{sec:psprecs}
|
||||
Preconditioning is somehow regarded as ``black magic''. This is due to
|
||||
the fact that theory doesn't provide a reliable support in the choice
|
||||
of a preconditioner. It is clear that the influence of a
|
||||
preconditioning technique on the convergence behavior of an iterative
|
||||
method mostly depends on the characteristics of the system matrix and
|
||||
of the method itself. Anyway it is not possible a priori to say that
|
||||
one preconditioner is algebrically better than another and this perfectly explains
|
||||
the importance of providing a wide range of preconditioners techniques
|
||||
so that the user can find by itself which one is more suitable for his
|
||||
problem. Moreover, there are some other issues to consider when
|
||||
choosing a preconditioner such as balancing the overhead of building
|
||||
the preconditioner with the reduction in the number of
|
||||
iterations. 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:
|
||||
\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 (see
|
||||
chapter~\ref{sec:pprec})
|
||||
\item Two-Level Additive Schwarz; this is actually a family of
|
||||
preconditioners since there is the possibility to choose between
|
||||
many variants as explained in chapter~\ref{sec:mlprec}
|
||||
\end{itemize}
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_precset}{Sets the precodntioner type}
|
||||
|
||||
\syntax{call psb\_precset}{prec, ptype, iv, rs, rv, ierr}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[prec]
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: e pronditioner data structure \precdata.
|
||||
\item[ptype] the type of preconditioner.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a string.
|
||||
\item[iv] integer parameters for the precondtioner.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer array.
|
||||
\item[rs]
|
||||
Scope: {\bf } \\
|
||||
Type: {\bf }\\
|
||||
Specified as: .
|
||||
\item[rv]
|
||||
Scope: {\bf } \\
|
||||
Type: {\bf }\\
|
||||
Specified as: .
|
||||
\item[ierr]
|
||||
Scope: {\bf } \\
|
||||
Type: {\bf }\\
|
||||
Specified as: .
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_precbld}{Builds a preconditioner}
|
||||
|
||||
\syntax{call psb\_precbld}{a, desc\_a, prec, info, upd}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[a] the system sparse matrix.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a sparse matrix data structure \spdata.
|
||||
\item[desc\_a] the problem communication descriptor.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a communication descriptor data structure \descdata.
|
||||
\item[upd]
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: a character.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[prec] the precodntioner.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a precondtioner data structure \precdata\\
|
||||
\item[info] the return error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.\\
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{psb\_precaply}{Preconditioner application routine}
|
||||
|
||||
\syntax{call psb\_precaply}{prec,x,y,desc\_a,info,trans,work}
|
||||
\syntax{call psb\_precaply}{prec,x,desc\_a,info,trans}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Entry]
|
||||
\item[prec] the preconditioner.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a preconditioner data structure \precdata.
|
||||
\item[x] the source vector.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf require}\\
|
||||
Specified as: a double precision array.
|
||||
\item[desc\_a] the problem communication descriptor.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a communication data structure \descdata.
|
||||
\item[trans]
|
||||
Scope: {\bf } \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: a character.
|
||||
\item[work] an optional work space
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: a double precision array.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[y] the destination vector.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: a double precision array.
|
||||
\item[info] the return error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Specified as: an integer.\\
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "userguide"
|
||||
|
||||
@@ -90,7 +90,7 @@
|
||||
\include{toolsrout}
|
||||
\include{methods}
|
||||
\include{precs}
|
||||
|
||||
\include{error}
|
||||
\end{document}
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
|
||||
Reference in New Issue
Block a user