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.
psblas3/docs/pdf/util.tex

229 lines
8.2 KiB
TeX

18 years ago
\section{Utilities}
\label{sec:util}
We have some utitlities available for input and output of
sparsematrices; the interfaces to these routines are available in the
module \verb|psb_util_mod|.
18 years ago
%% \subroutine{}{Sorting utilities}
%% \subroutine*{psb\_msort}{Sorting by the Merge-sort algorithm}
%% \subroutine*{psb\_qsort}{Sorting by the Quicksort algorithm}
%% \syntax{call psb\_msort}{x,ix,dir,flag}
%% \syntax*{call psb\_qsort}{x,ix,dir,flag}
%% These serial routines sort a sequence $X$ into ascending or
%% descending order. The argument meaning is identical for the two
%% calls; the only difference is the algorithm used to accomplish the
%% task (see Usage Notes below).
%% \begin{description}
%% \item[\bf On Entry ]
%% \item[x] The sequence to be sorted.\\
%% Type:{\bf required}.\\
%% Specified as: an integer array of rank 1.
%% \item[ix] A vector of indices.\\
%% Type:{\bf optional}.\\
%% Specified as: an integer array of (at least) the same size as $X$.
%% \item[dir] The desired ordering.\\
%% Type:{\bf optional}.\\
%% Specified as: an integer value \verb|psb_sort_up_| or
%% \verb|psb_sort_down_|; default \verb|psb_sort_up_|.
%% \item[flag] Whether to keep the original values in $IX$.\\
%% Type:{\bf optional}.\\
%% Specified as: an integer value \verb|psb_sort_ovw_idx_| or
%% \verb|psb_sort_keep_idx_|; default \verb|psb_sort_ovw_idx_|.
%% \end{description}
%% \begin{description}
%% \item[\bf On Return]
%% \item[x] The sequence of values, in the chosen ordering.\\
%% Type:{\bf required}.\\
%% Specified as: an integer array of rank 1.
%% \item[ix] A vector of indices.\\
%% Type: {\bf Optional} \\
%% An integer array of rank 1, whose entries are moved to the same
%% position as the corresponding entries in $x$.
%% \end{description}
%% \section*{Usage notes}
%% \begin{enumerate}
%% \item The two routines return the items in the chosen ordering; the
%% only output difference is the handling of ties (i.e. items with an
%% equal value) in the original input. With the merge-sort algorithm
%% ties are preserved in the same order as they had in the original
%% sequence, while this is not guaranteed for quicksort
%% \item If $flag = psb\_sort\_ovw\_idx\_$ then the entries in $ix(1:n)$
%% where $n$ is the size of $x$ are initialized to $ix(i) \leftarrow
%% i$; thus, upon return from the subroutine, for each
%% index $i$ we have in $ix(i)$ the position that the item $x(i)$
%% occupied in the original data sequence;
%% \item If $flag = psb\_sort\_keep\_idx\_$ the routine will assume that
%% the entries in $ix(:)$ have already been initialized by the user;
%% \item The two sorting algorithms have a similar $O(n \log n)$ expected
%% running time; in the average case quicksort will be the
%% fastest. However note that:
%% \begin{enumerate}
%% \item The worst case running time for quicksort is $O(n^2)$; the algorithm
%% implemented here follows the well-known median-of-three heuristics,
%% but the worst case may still apply;
%% \item The worst case running time for merge-sort is the same as the
%% average case;
%% \item The merge-sort algorithm is implemented to take advantage of
%% subsequences that may be already in the desired ordering at the
%% beginning; this situation is relatively common when dealing with
%% indices of sparse matrix entries, thus merge-sort is the
%% preferred choice when a sorting is needed by other routines in the
%% library.
%% \end{enumerate}
%% \end{enumerate}
%\subroutine{PSB\_HBIO\_MOD}{Input/Output in Harwell-Boeing format}
\subroutine{hb\_read}{Read a sparse matrix from a file in the
18 years ago
Harwell--Boeing format}
\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 in the Harwell--Boeing format}
\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 in the MatrixMarket format}
\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 in the MatrixMarket format}
\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}
18 years ago
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: