You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
346 lines
10 KiB
TeX
346 lines
10 KiB
TeX
\section{Utilities}
|
|
\label{sec:util}
|
|
|
|
We have some utilities available for input and output of
|
|
sparse matrices; the interfaces to these routines are available in the
|
|
module \verb|psb_util_mod|.
|
|
|
|
|
|
|
|
%\subroutine{PSB\_HBIO\_MOD}{Input/Output in Harwell-Boeing format}
|
|
|
|
\clearpage\subsection{ hb\_read --- Read a sparse matrix from a file in the
|
|
Harwell--Boeing format}
|
|
|
|
|
|
\begin{lstlisting}
|
|
call hb_read(a, iret, iunit, filename, b, mtitle)
|
|
\end{lstlisting}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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(s).\\
|
|
Type: {\bf Optional} \\
|
|
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.
|
|
\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}
|
|
|
|
|
|
|
|
\clearpage\subsection{hb\_write --- Write a sparse matrix to a file
|
|
in the Harwell--Boeing format}
|
|
|
|
|
|
\begin{lstlisting}
|
|
call hb_write(a, iret, iunit, filename, key, rhs, mtitle)
|
|
\end{lstlisting}
|
|
|
|
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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}
|
|
|
|
\clearpage\subsection{mm\_mat\_read --- Read a sparse matrix from a
|
|
file in the MatrixMarket format}
|
|
|
|
\begin{lstlisting}
|
|
call mm_mat_read(a, iret, iunit, filename)
|
|
\end{lstlisting}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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}
|
|
|
|
|
|
\clearpage\subsection{mm\_array\_read --- Read a dense array from a
|
|
file in the MatrixMarket format}
|
|
|
|
\begin{lstlisting}
|
|
call mm_array_read(b, iret, iunit, filename)
|
|
\end{lstlisting}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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[b] Rigth hand side(s).\\
|
|
Type: {\bf required} \\
|
|
An array of type real or complex, rank 1 or 2 and having the ALLOCATABLE
|
|
attribute, or an
|
|
object of type \vdata, of type real or complex.\\
|
|
Will be allocated and filled in if the input file contains
|
|
a right hand side, otherwise will be left in the UNALLOCATED state. \\
|
|
\item[iret] Error code.\\
|
|
Type: {\bf required} \\
|
|
An integer value; 0 means no error has been detected.
|
|
\end{description}
|
|
|
|
|
|
|
|
\clearpage\subsection{mm\_mat\_write --- Write a sparse matrix to a
|
|
file in the MatrixMarket format}
|
|
|
|
|
|
\begin{lstlisting}
|
|
call mm_mat_write(a, mtitle, iret, iunit, filename)
|
|
\end{lstlisting}
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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}
|
|
|
|
{\par\noindent\large\bfseries Notes}
|
|
|
|
If this function is called on a matrix \lstinline|a| on a distributed communicator
|
|
only the local part is written in output. To get a single MatrixMarket file with
|
|
the whole matrix when appropriate, e.g. for debugging purposes, one could \emph{gather}
|
|
the whole matrix on a single rank and then write it. Consider the following example
|
|
for a \emph{double} precision matrix\vspace{-0.5em}
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
|
|
type(psb_ldspmat_type) :: aglobal
|
|
|
|
call psb_gather(aglobal,a,desc_a,info)
|
|
if (iam == psb_root_) then
|
|
call mm_mat_write(aglobal,mtitle,info,filename)
|
|
end if
|
|
call psb_spfree(aglobal, desc_a, info)
|
|
\end{minted}
|
|
\else
|
|
\begin{center}
|
|
\begin{minipage}[tl]{0.9\textwidth}
|
|
\begin{verbatim}
|
|
type(psb_ldspmat_type) :: aglobal
|
|
|
|
call psb_gather(aglobal,a,desc_a,info)
|
|
if (iam == psb_root_) then
|
|
call mm_mat_write(aglobal,mtitle,info,filename)
|
|
end if
|
|
call psb_spfree(aglobal, desc_a, info)
|
|
\end{verbatim}
|
|
\end{minipage}
|
|
\end{center}
|
|
\fi
|
|
To simplify this procedure in \verb|C|, there is a utility function\vspace{-0.5em}
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{c}
|
|
psb_i_t psb_c_<s,d,c,z>global_mat_write(ah,cdh);
|
|
\end{minted}
|
|
\else
|
|
\begin{center}
|
|
\begin{minipage}[tl]{0.9\textwidth}
|
|
\begin{verbatim}
|
|
psb_i_t psb_c_<s,d,c,z>global_mat_write(ah,cdh);
|
|
\end{verbatim}
|
|
\end{minipage}
|
|
\end{center}
|
|
\fi
|
|
that produces exactly this result.
|
|
|
|
|
|
\clearpage\subsection{mm\_array\_write --- Write a dense array from a
|
|
file in the MatrixMarket format}
|
|
|
|
\begin{lstlisting}
|
|
call mm_array_write(b, vtitle, iret, iunit, filename)
|
|
\end{lstlisting}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\item[\bf On Entry ]
|
|
\item[b] Rigth hand side(s).\\
|
|
Type: {\bf required} \\
|
|
An array of type real or complex, rank 1 or 2, or an
|
|
object of type \vdata, of type real or complex; its contents will be
|
|
written to disk.\\
|
|
\item[filename] The name of the file to be written.\\
|
|
\item[vtitle] Matrix title.\\
|
|
Type: {\bf required} \\
|
|
A charachter variable holding a descriptive title for the vector to be
|
|
written to file.
|
|
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[iret] Error code.\\
|
|
Type: {\bf required} \\
|
|
An integer value; 0 means no error has been detected.
|
|
\end{description}
|
|
|
|
{\par\noindent\large\bfseries Notes}
|
|
|
|
If this function is called on a vector \lstinline|v| on a distributed communicator
|
|
only the local part is written in output. To get a single MatrixMarket file with
|
|
the whole vector when appropriate, e.g. for debugging purposes, one could \emph{gather}
|
|
the whole vector on a single rank and then write it. Consider the following example
|
|
for a \emph{double} precision vector
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
|
|
real(psb_dpk_), allocatable :: vglobal(:)
|
|
|
|
call psb_gather(vglobal,v,desc,info)
|
|
if (iam == psb_root_) then
|
|
call mm_array_write(vglobal,vtitle,info,filename)
|
|
end if
|
|
call deallocate(vglobal, stat=info)
|
|
\end{minted}
|
|
\else
|
|
\begin{center}
|
|
\begin{minipage}[tl]{0.9\textwidth}
|
|
\begin{verbatim}
|
|
real(psb_dpk_), allocatable :: vglobal(:)
|
|
|
|
call psb_gather(vglobal,v,desc,info)
|
|
if (iam == psb_root_) then
|
|
call mm_array_write(vglobal,vtitle,info,filename)
|
|
end if
|
|
call deallocate(vglobal, stat=info)
|
|
\end{verbatim}
|
|
\end{minipage}
|
|
\end{center}
|
|
\fi
|
|
To simplify this procedure in \verb|C|, there is a utility function
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{c}
|
|
psb_i_t psb_c_<s,d,c,z>global_vec_write(vh,cdh);
|
|
\end{minted}
|
|
\else
|
|
\begin{center}
|
|
\begin{minipage}[tl]{0.9\textwidth}
|
|
\begin{verbatim}
|
|
psb_i_t psb_c_<s,d,c,z>global_vec_write(vh,cdh);
|
|
\end{verbatim}
|
|
\end{minipage}
|
|
\end{center}
|
|
\fi
|
|
that produces exactly this result.
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: "userguide"
|
|
%%% End:
|