fdurastante/psblas3
1
0
Fork 0
mirror of https://github.com/sfilippone/psblas3.git synced 2026-10-06 22:55:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

psblas3:

Browse Source 
Updated docs.
This commit is contained in:
Salvatore Filippone
2014-03-25 11:24:42 +00:00
parent 38b70b287f
commit fdaa0f5d74
127 changed files with 14415 additions and 14395 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/html/node111.html
+190 -292
View File
@@ -7,8 +7,8 @@ original version by: Nikos Drakos, CBLU, University of Leeds
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>Utilities</TITLE>
<META NAME="description" CONTENT="Utilities">
<TITLE>Error handling</TITLE>
<META NAME="description" CONTENT="Error handling">
<META NAME="keywords" CONTENT="userhtml">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
@@ -19,60 +19,142 @@ original version by: Nikos Drakos, CBLU, University of Leeds
<LINK REL="STYLESHEET" HREF="userhtml.css">
<LINK REL="next" HREF="node112.html">
<LINK REL="previous" HREF="node110.html">
<LINK REL="previous" HREF="node94.html">
<LINK REL="up" HREF="userhtml.html">
<LINK REL="next" HREF="node112.html">
</HEAD>
<BODY >
<!--Navigation Panel-->
<A NAME="tex2html1618"
<A NAME="tex2html1621"
HREF="node112.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html1614"
<A NAME="tex2html1617"
HREF="userhtml.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html1608"
<A NAME="tex2html1611"
HREF="node110.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html1616"
<A NAME="tex2html1619"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1619"
HREF="node112.html">Preconditioner routines</A>
<B> Up:</B> <A NAME="tex2html1615"
<B> Next:</B> <A NAME="tex2html1622"
HREF="node112.html">Utilities</A>
<B> Up:</B> <A NAME="tex2html1618"
HREF="userhtml.html">userhtml</A>
<B> Previous:</B> <A NAME="tex2html1609"
HREF="node110.html">Error handling</A>
&nbsp; <B> <A NAME="tex2html1617"
<B> Previous:</B> <A NAME="tex2html1612"
HREF="node110.html">psb_rcv Receive</A>
&nbsp; <B> <A NAME="tex2html1620"
HREF="node1.html">Contents</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION000100000000000000000"></A>
<A NAME="sec:util"></A>
<BR>
Utilities
<H1><A NAME="SECTION00090000000000000000">
Error handling</A>
</H1>
<P>
We have some utitlities available for input and output of
sparsematrices; the interfaces to these routines are available in the
module <code>psb_util_mod</code>.
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 <code>info</code> variable; whenever,
inside the routine, an 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 <code>info</code> 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.
<P>
ifstarsubroutinesubroutinehb_readRead a sparse matrix from a file in the
Harwell-Boeing format
Figure&nbsp;<A HREF="#fig:routerr">9</A> shows the layout of a generic <code>psb_foo</code>
routine with respect to the PSBLAS-2.0 error handling policy. It is
possible to see how, whenever an error condition is detected, the
<code>info</code> variable is set to the corresponding error code which is,
then, pushed on top of the stack by means of the
<code>psb_errpush</code>. 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
<code>psb\_error</code> routine which prints the content of the error stack
and aborts the program execution, according to the choice made by the
user with <code>psb_set_erraction</code>. The default is to print the error
and terminate the program, but the user may choose to handle the error
explicitly.
<P>
<DIV ALIGN="CENTER"><A NAME="fig:routerr"></A><A NAME="7079"></A>
<TABLE>
<CAPTION ALIGN="BOTTOM"><STRONG>Figure 9:</STRONG>
The layout of a generic <TT>psb_foo</TT>
routine with respect to PSBLAS-2.0 error handling policy.</CAPTION>
<TR><TD>
<BR>
<DIV ALIGN="CENTER">
<!-- MATH
$\fbox{\TheSbox}$
-->
<IMG
WIDTH="563" HEIGHT="482" ALIGN="MIDDLE" BORDER="0"
SRC="img143.png"
ALT="\fbox{\TheSbox}">
</DIV></TD></TR>
</TABLE>
</DIV>
<P>
Figure&nbsp;<A HREF="#fig:errormsg">10</A> 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 <code>psb_cest</code> subroutine
called by <code>psb_spasb</code> ... by process 0 (i.e. the root process).
<P>
<DIV ALIGN="CENTER"><A NAME="fig:errormsg"></A><A NAME="7080"></A>
<TABLE>
<CAPTION ALIGN="BOTTOM"><STRONG>Figure 10:</STRONG>
A sample PSBLAS-2.0 error
message. Process 0 detected an error condition inside the psb_cest subroutine</CAPTION>
<TR><TD>
<BR>
<DIV ALIGN="CENTER">
<!-- MATH
$\fbox{\TheSbox}$
-->
<IMG
WIDTH="563" HEIGHT="482" ALIGN="MIDDLE" BORDER="0"
SRC="img143.png"
ALT="\fbox{\TheSbox}">
</DIV></TD></TR>
</TABLE>
</DIV>
<P>
ifstarsubroutinesubroutinepsb_errpushPushes an error code onto the error
stack
<P>
<BR>
<IMG
WIDTH="461" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img149.png"
WIDTH="423" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img145.png"
ALT="\begin{lstlisting}
call hb_read(a, iret, iunit, filename, b, mtitle)
call psb_errpush(err_c, r_name, i_err, a_err)
\end{lstlisting}">
<BR>
@@ -81,77 +163,62 @@ call hb_read(a, iret, iunit, filename, b, mtitle)
<DT><STRONG>Type:</STRONG></DT>
<DD>Asynchronous.
</DD>
<DT><STRONG><B>On Entry </B></STRONG></DT>
<DT><STRONG><B>On Entry</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>filename</STRONG></DT>
<DD>The name of the file to be read.
<DT><STRONG>err_c</STRONG></DT>
<DD>the error code
<BR>
Type:<B>optional</B>.
Scope: <B>local</B>
<BR>
Specified as: a character variable containing a valid file name, or
<code>-</code>, in which case the default input unit 5 (i.e. standard input
in Unix jargon) is used. Default: <code>-</code>.
Type: <B>required</B>
<BR>
Intent: <B>in</B>.
<BR>
Specified as: an integer.
</DD>
<DT><STRONG>iunit</STRONG></DT>
<DD>The Fortran file unit number.
<DT><STRONG>r_name</STRONG></DT>
<DD>the soutine where the error has been caught.
<BR>
Type:<B>optional</B>.
Scope: <B>local</B>
<BR>
Specified as: an integer value. Only meaningful if filename is not <code>-</code>.
</DD>
Type: <B>required</B>
<BR>
Intent: <B>in</B>.
<BR>
Specified as: a string.
<BR></DD>
<DT><STRONG>i_err</STRONG></DT>
<DD>addional info for error code
<BR>
Scope: <B>local</B>
<BR>
Type: <B>optional</B>
<BR>
Specified as: an integer array
<BR></DD>
<DT><STRONG>a_err</STRONG></DT>
<DD>addional info for error code
<BR>
Scope: <B>local</B>
<BR>
Type: <B>optional</B>
<BR>
Specified as: a string.
<BR></DD>
</DL>
<P>
<DL>
<DT><STRONG><B>On Return</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>a</STRONG></DT>
<DD>the sparse matrix read from file.
<BR>
Type:<B>required</B>.
<BR>
Specified as: a structured data of type spdata<TT>psb_Tspmat_type</TT>.
</DD>
<DT><STRONG>b</STRONG></DT>
<DD>Rigth hand side(s).
<BR>
Type: <B>Optional</B>
<BR>
An array of type real or complex, rank 2 and having the ALLOCATABLE
attribute; will be allocated and filled in if the input file contains
a right hand side, otherwise will be left in the UNALLOCATED state.
</DD>
<DT><STRONG>mtitle</STRONG></DT>
<DD>Matrix title.
<BR>
Type: <B>Optional</B>
<BR>
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.
</DD>
<DT><STRONG>iret</STRONG></DT>
<DD>Error code.
<BR>
Type: <B>required</B>
<BR>
An integer value; 0 means no error has been detected.
</DD>
</DL>
<P>
ifstarsubroutinesubroutinehb_writeWrite a sparse matrix to a file
in the Harwell-Boeing format
ifstarsubroutinesubroutinepsb_errorPrints the error stack content and aborts
execution
<P>
<BR>
<IMG
WIDTH="538" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img150.png"
WIDTH="213" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img146.png"
ALT="\begin{lstlisting}
call hb_write(a, iret, iunit, filename, key, rhs, mtitle)
call psb_error(icontxt)
\end{lstlisting}">
<BR>
@@ -160,86 +227,33 @@ call hb_write(a, iret, iunit, filename, key, rhs, mtitle)
<DT><STRONG>Type:</STRONG></DT>
<DD>Asynchronous.
</DD>
<DT><STRONG><B>On Entry </B></STRONG></DT>
<DT><STRONG><B>On Entry</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>a</STRONG></DT>
<DD>the sparse matrix to be written.
<DT><STRONG>icontxt</STRONG></DT>
<DD>the communication context.
<BR>
Type:<B>required</B>.
Scope: <B>global</B>
<BR>
Specified as: a structured data of type spdata<TT>psb_Tspmat_type</TT>.
</DD>
<DT><STRONG>b</STRONG></DT>
<DD>Rigth hand side.
Type: <B>optional</B>
<BR>
Type: <B>Optional</B>
Intent: <B>in</B>.
<BR>
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.
</DD>
<DT><STRONG>filename</STRONG></DT>
<DD>The name of the file to be written to.
<BR>
Type:<B>optional</B>.
<BR>
Specified as: a character variable containing a valid file name, or
<code>-</code>, in which case the default output unit 6 (i.e. standard output
in Unix jargon) is used. Default: <code>-</code>.
</DD>
<DT><STRONG>iunit</STRONG></DT>
<DD>The Fortran file unit number.
<BR>
Type:<B>optional</B>.
<BR>
Specified as: an integer value. Only meaningful if filename is not <code>-</code>.
</DD>
<DT><STRONG>key</STRONG></DT>
<DD>Matrix key.
<BR>
Type: <B>Optional</B>
<BR>
A charachter variable of length 8 holding the
matrix key as specified by the Harwell-Boeing format and to be
written to file.
</DD>
<DT><STRONG>mtitle</STRONG></DT>
<DD>Matrix title.
<BR>
Type: <B>Optional</B>
<BR>
A charachter variable of length 72 holding the
matrix title as specified by the Harwell-Boeing format and to be
written to file.
Specified as: an integer.
</DD>
</DL>
<P>
<DL>
<DT><STRONG><B>On Return</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>iret</STRONG></DT>
<DD>Error code.
<BR>
Type: <B>required</B>
<BR>
An integer value; 0 means no error has been detected.
</DD>
</DL>
<P>
ifstarsubroutinesubroutinemm_mat_readRead a sparse matrix from a
file in the MatrixMarket format
ifstarsubroutinesubroutinepsb_set_errverbositySets the verbosity of error
messages.
<P>
<BR>
<IMG
WIDTH="394" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img151.png"
WIDTH="261" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img147.png"
ALT="\begin{lstlisting}
call mm_mat_read(a, iret, iunit, filename)
call psb_set_errverbosity(v)
\end{lstlisting}">
<BR>
@@ -248,57 +262,33 @@ call mm_mat_read(a, iret, iunit, filename)
<DT><STRONG>Type:</STRONG></DT>
<DD>Asynchronous.
</DD>
<DT><STRONG><B>On Entry </B></STRONG></DT>
<DT><STRONG><B>On Entry</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>filename</STRONG></DT>
<DD>The name of the file to be read.
<DT><STRONG>v</STRONG></DT>
<DD>the verbosity level
<BR>
Type:<B>optional</B>.
Scope: <B>global</B>
<BR>
Specified as: a character variable containing a valid file name, or
<code>-</code>, in which case the default input unit 5 (i.e. standard input
in Unix jargon) is used. Default: <code>-</code>.
</DD>
<DT><STRONG>iunit</STRONG></DT>
<DD>The Fortran file unit number.
Type: <B>required</B>
<BR>
Type:<B>optional</B>.
Intent: <B>in</B>.
<BR>
Specified as: an integer value. Only meaningful if filename is not <code>-</code>.
Specified as: an integer.
</DD>
</DL>
<P>
<DL>
<DT><STRONG><B>On Return</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>a</STRONG></DT>
<DD>the sparse matrix read from file.
<BR>
Type:<B>required</B>.
<BR>
Specified as: a structured data of type spdata<TT>psb_Tspmat_type</TT>.
</DD>
<DT><STRONG>iret</STRONG></DT>
<DD>Error code.
<BR>
Type: <B>required</B>
<BR>
An integer value; 0 means no error has been detected.
</DD>
</DL>
ifstarsubroutinesubroutinepsb_set_erractionSet the type of action to be
taken upon error condition.
<P>
ifstarsubroutinesubroutinemm_vet_readRead a dense vector from a
file in the MatrixMarket format
<BR>
<IMG
WIDTH="394" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img152.png"
WIDTH="289" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img148.png"
ALT="\begin{lstlisting}
call mm_vet_read(b, iret, iunit, filename)
call psb_set_erraction(err_act)
\end{lstlisting}">
<BR>
@@ -307,138 +297,46 @@ call mm_vet_read(b, iret, iunit, filename)
<DT><STRONG>Type:</STRONG></DT>
<DD>Asynchronous.
</DD>
<DT><STRONG><B>On Entry </B></STRONG></DT>
<DT><STRONG><B>On Entry</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>filename</STRONG></DT>
<DD>The name of the file to be read.
<DT><STRONG>err_act</STRONG></DT>
<DD>the type of action.
<BR>
Type:<B>optional</B>.
Scope: <B>global</B>
<BR>
Specified as: a character variable containing a valid file name, or
<code>-</code>, in which case the default input unit 5 (i.e. standard input
in Unix jargon) is used. Default: <code>-</code>.
</DD>
<DT><STRONG>iunit</STRONG></DT>
<DD>The Fortran file unit number.
Type: <B>required</B>
<BR>
Type:<B>optional</B>.
Intent: <B>in</B>.
<BR>
Specified as: an integer value. Only meaningful if filename is not <code>-</code>.
</DD>
</DL>
<P>
<DL>
<DT><STRONG><B>On Return</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>b</STRONG></DT>
<DD>Rigth hand side(s).
<BR>
Type: <B>required</B>
<BR>
An array of type real or complex, rank 2 and having the ALLOCATABLE
attribute; will be allocated and filled in if the input file contains
a right hand side, otherwise will be left in the UNALLOCATED state.
</DD>
<DT><STRONG>iret</STRONG></DT>
<DD>Error code.
<BR>
Type: <B>required</B>
<BR>
An integer value; 0 means no error has been detected.
</DD>
</DL>
<P>
ifstarsubroutinesubroutinemm_mat_writeWrite a sparse matrix to a
file in the MatrixMarket format
<BR>
<IMG
WIDTH="480" HEIGHT="16" ALIGN="BOTTOM" BORDER="0"
SRC="img153.png"
ALT="\begin{lstlisting}
call mm_mat_write(a, mtitle, iret, iunit, filename)
\end{lstlisting}">
<BR>
<DL>
<DT><STRONG>Type:</STRONG></DT>
<DD>Asynchronous.
</DD>
<DT><STRONG><B>On Entry </B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>a</STRONG></DT>
<DD>the sparse matrix to be written.
<BR>
Type:<B>required</B>.
<BR>
Specified as: a structured data of type spdata<TT>psb_Tspmat_type</TT>.
</DD>
<DT><STRONG>mtitle</STRONG></DT>
<DD>Matrix title.
<BR>
Type: <B>required</B>
<BR>
A charachter variable holding a descriptive title for the matrix to be
written to file.
</DD>
<DT><STRONG>filename</STRONG></DT>
<DD>The name of the file to be written to.
<BR>
Type:<B>optional</B>.
<BR>
Specified as: a character variable containing a valid file name, or
<code>-</code>, in which case the default output unit 6 (i.e. standard output
in Unix jargon) is used. Default: <code>-</code>.
</DD>
<DT><STRONG>iunit</STRONG></DT>
<DD>The Fortran file unit number.
<BR>
Type:<B>optional</B>.
<BR>
Specified as: an integer value. Only meaningful if filename is not <code>-</code>.
</DD>
</DL>
<P>
<DL>
<DT><STRONG><B>On Return</B></STRONG></DT>
<DD>
</DD>
<DT><STRONG>iret</STRONG></DT>
<DD>Error code.
<BR>
Type: <B>required</B>
<BR>
An integer value; 0 means no error has been detected.
Specified as: an integer. Possible values: <code>psb_act_ret</code>,
<code>psb_act_abort</code>.
</DD>
</DL>
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html1618"
<A NAME="tex2html1621"
HREF="node112.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html1614"
<A NAME="tex2html1617"
HREF="userhtml.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html1608"
<A NAME="tex2html1611"
HREF="node110.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html1616"
<A NAME="tex2html1619"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1619"
HREF="node112.html">Preconditioner routines</A>
<B> Up:</B> <A NAME="tex2html1615"
<B> Next:</B> <A NAME="tex2html1622"
HREF="node112.html">Utilities</A>
<B> Up:</B> <A NAME="tex2html1618"
HREF="userhtml.html">userhtml</A>
<B> Previous:</B> <A NAME="tex2html1609"
HREF="node110.html">Error handling</A>
&nbsp; <B> <A NAME="tex2html1617"
<B> Previous:</B> <A NAME="tex2html1612"
HREF="node110.html">psb_rcv Receive</A>
&nbsp; <B> <A NAME="tex2html1620"
HREF="node1.html">Contents</A></B>
<!--End of Navigation Panel-->