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/toolsrout.tex

1410 lines
41 KiB
TeX

\section{Data management routines}
\label{sec:toolsrout}
19 years ago
%
%% psb_cdall %%
19 years ago
%
\subroutine{psb\_cdall}{Allocates a communication descriptor}
19 years ago
18 years ago
\syntax{call psb\_cdall}{icontxt, desc\_a, info,mg=mg,parts=parts}
\syntax*{call psb\_cdall}{icontxt, desc\_a, info,vg=vg,flag=flag}
\syntax*{call psb\_cdall}{icontxt, desc\_a, info,vl=vl}
\syntax*{call psb\_cdall}{icontxt, desc\_a, info,nl=nl}
\syntax*{call psb\_cdall}{icontxt, desc\_a, info,mg=mg,repl=.true.}
19 years ago
This subroutine initializes the communication descriptor associated
18 years ago
with an index space. Exactly one of the optional arguments
\verb|parts|, \verb|vg|, \verb|vl| or \verb|nl|
must be specified, thereby choosing
18 years ago
the specific initialization strategy:
19 years ago
\begin{description}
18 years ago
\item[\bf On Entry ]
\item[Type:] Synchronous.
\item[icontxt] the communication context.\\
Scope:{\bf global}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value.
18 years ago
\item[vg] Data allocation: each index $i\in \{1\dots mg\}$ is allocated
to process $vg(i)$.
Scope:{\bf global}.\\
18 years ago
Type:{\bf optional}.\\
Intent: {\bf in}.\\
18 years ago
Specified as: an integer array.
\item[flag] Specifies whether entries in $vg$ are zero- or one-based.
Scope:{\bf global}.\\
18 years ago
Type:{\bf optional}.\\
Intent: {\bf in}.\\
18 years ago
Specified as: an integer value $0,1$, default $0$.
\item[mg] the (global) number of rows of the problem.\\
Scope:{\bf global}.\\
18 years ago
Type:{\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value. It is required if \verb|parts| or
\verb|repl| is specified.
18 years ago
\item[parts] the subroutine that defines the partitioning scheme.\\
Scope:{\bf global}.\\
18 years ago
Type:{\bf required}.\\
Specified as: a subroutine.
\item[vl] Data allocation: the set of global indices belonging to the
calling process.
Scope:{\bf local}.\\
Type:{\bf optional}.\\
Intent: {\bf in}.\\
18 years ago
Specified as: an integer array.
\item[nl] Data allocation: in a generalized block-row distribution the
number of indices belonging to the current process.
Scope:{\bf local}.\\
Type:{\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value.
\item[repl] Data allocation: build a replicated index space (i.e. all
processes own all indices).
Scope:{\bf global}.\\
Type:{\bf optional}.\\
Intent: {\bf in}.\\
Specified as: the logical value \verb|.true.|
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf out}.\\
Specified as: a structured data of type \descdata.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
18 years ago
\item Exactly one of the optional arguments \verb|parts|, \verb|vg|,
\verb|vl|, \verb|nl| must be specified, thereby choosing the
initialization strategy as follows:
18 years ago
\begin{description}
\item[parts] In this case we have a subroutine specifying the mapping
between global indices and process/local index pairs. If this
optional argument is specified, then it is mandatory to
specify the argument \verb|mg| as well.
The subroutine must conform to the following interface:
\begin{verbatim}
interface
subroutine psb_parts(glob_index,mg,np,pv,nv)
integer, intent (in) :: glob_index,np,mg
integer, intent (out) :: nv, pv(*)
end subroutine psb_parts
end interface
\end{verbatim}
The input arguments are:
\begin{description}
\item[glob\_index] The global index to be mapped;
\item[np] The number of processes in the mapping;
\item[mg] The total number of global rows in the mapping;
\end{description}
The output arguments are:
\begin{description}
\item[nv] The number of entries in \verb|pv|;
\item[pv] A vector containint the indices of the processes to
which the global index should be assigend; each entry must satisfy
$0\le pv(i) < np$; if $nv>1$ we have an index assigned to multiple
processes, i.e. we have an overlap among the subdomains.
\end{description}
18 years ago
\item[vg] In this case the association between an index and a process
is specified via an integer vector; the size of the index space is
equal to the size of \verb|vg|, and each index $i$ is assigned to
the process $vg(i)$. The vector \verb|vg| must be identical on all
calling processes; its entries may have the ranges $(0\dots np-1)$
or $(1\dots np)$ according to the value of \verb|flag|.
\item[vl] In this case we are specifying the list of indices assigned
to the current process; thus, the global problem size $mg$ is given by
the sum of the sizes of the individual vectors \verb|vl| specified
on the calling processes. The subroutine will check that each entry
in the global index space $(1\dots mg)$ is specified exactly once.
\item[nl] In this case we are implying a generalized row-block
distribution in which each process $I$ gets assigned a consecutive
chunk of $N_I=nl$ global indices.
\item[repl] In this case we are asking to replicate all indices on
all processes. This is a special purpose data allocation that is
useful in the construction of some multilevel preconditioners.
18 years ago
\end{description}
\item On exit from this routine the descriptor is in the build state
\end{enumerate}
19 years ago
%
%% psb_cdins %%
19 years ago
%
\subroutine{psb\_cdins}{Communication descriptor insert routine}
19 years ago
\syntax{call psb\_cdins}{nz, ia, ja, desc\_a, info}
19 years ago
This subroutine examines the edges of the graph associated with the
discretization mesh (and isomorphic to the sparsity pattern of a
linear system coefficient matrix), storing them as necessary into the
communication descriptor.
19 years ago
\begin{description}
\item[Type:] Asynchronous.
19 years ago
\item[\bf On Entry]
\item[nz] the number of points being inserted.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value.
\item[ia] the indices of the starting vertex of the edges being inserted.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer array of length $nz$.
\item[ja] the indices of the end vertex of the edges being inserted.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer array of length $nz$.
%% \item[is] the row offset.\\
%% Scope:{\bf local}.\\
%% Type:{\bf optional}.\\
%% Specified as: an integer value.
%% \item[js] the column offset.\\
%% Scope: {\bf local}.\\
%% Type: {\bf optional}.\\
%% Specified as: an integer value.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[desc\_a] the updated communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \descdata.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item This routine may only be called if the descriptor is in the
build state;
\item This routine automatically ignores edges that do not
insist on the current process, i.e. edges for which neither the starting
nor the end vertex belong to the current process.
\end{enumerate}
19 years ago
19 years ago
%
%% psb_cdasb %%
19 years ago
%
\subroutine{psb\_cdasb}{Communication descriptor assembly routine}
19 years ago
\syntax{call psb\_cdasb}{desc\_a, info}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \descdata.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \descdata.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
%\item[arg]
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item On exit from this routine the descriptor is in the assembled
state.
\end{enumerate}
19 years ago
%
%% psb_cdcpy %%
19 years ago
%
\subroutine{psb\_cdcpy}{Copies a communication descriptor}
19 years ago
\syntax{call psb\_cdcpy}{desc\_in, desc\_out, info}
19 years ago
\begin{description}
\item[Type:] Asynchronous.
19 years ago
\item[\bf On Entry]
\item[desc\_in] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[desc\_out] the communication descriptor copy.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf out}.\\
Specified as: a structured data of type \descdata.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
%
%% psb_cdfree %%
19 years ago
%
\subroutine{psb\_cdfree}{Frees a communication descriptor}
19 years ago
\syntax{call psb\_cdfree}{desc\_a, info}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[desc\_a] the communication descriptor to be freed.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \descdata.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
%
%% psb_cdcpy %%
%
\subroutine{psb\_cdbldext}{Build an extended communication descriptor}
\syntax{call psb\_cdbldext}{a,desc\_a,nl,desc\_out, info, extype}
This subroutine builds an extended communication descriptor, based on
the input descriptor \verb|desc_a| and on the stencil specified
through the input sparse matrix \verb|a|.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[a] A sparse matrix
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data type.
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\item[nl] the number of additional layers desired.\\
Scope:{\bf global}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value $nl\ge 0$.
\item[extype] the kind of estension required.\\
Scope:{\bf global}.\\
Type:{\bf optional }.\\
Intent: {\bf in}.\\
Specified as: an integer value
\verb|psb_ovt_xhal_|, \verb|psb_ovt_asov_|, default: \verb|psb_ovt_xhal_|
\end{description}
\begin{description}
\item[\bf On Return]
\item[desc\_out] the extended communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \descdata.
\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}
\section*{Notes}
\begin{enumerate}
\item Specifying \verb|psb_ovt_xhal_| for the \verb|extype| argument
the user will obtain a descriptor for a domain partition in which
the additional layers are fetched as part of an (extended) halo;
however the index-to-process mapping is identical to that of the
base descriptor;
\item Specifying \verb|psb_ovt_asov_| for the \verb|extype| argument
the user will obtain a descriptor with an overlapped decomposition:
the additional layer is aggregated to the local subdomain (and thus
is an overlap), and a new halo extending beyond the last additional
layer is formed.
\end{enumerate}
%% %
%% %% psb_cdren %%
%% %
%% \subroutine{psb\_cdren}{Applies a renumeration to a communication descriptor}
%% \syntax{call psb\_cdren}{trans, iperm, desc\_a, info}
%% \begin{description}
%% \item[\bf On Entry]
%% \item[Type:] Asynchronous.
%% \item[trans] A character that specifies whether to permute $A$ or $A^T$.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a single character with value 'N' for $A$ or 'T' for $A^T$.\\
%% \item[iperm] An integer array containing permutation information.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: an integer one-dimensional array.\\
%% \item[desc\_a] the communication descriptor.\\
%% Scope:{\bf local}.\\
%% Type:{\bf required}.\\
%% Specified as: a structured data of type \descdata.
%% \end{description}
%% \begin{description}
%% \item[\bf On Return]
%% \item[info] Error code.
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: an integer variable.
%% \end{description}
19 years ago
%
%% psb_descprt %%
19 years ago
%
%% \subroutine{psb\_cdprt}{Prints a descriptor}
19 years ago
%% \syntax{call psb\_cdprt}{iout, desc\_a, glob, short}
19 years ago
%% \begin{description}
%% \item[Type:] Asynchronous.
%% \item[\bf On Entry]
%% \item[iout] An integer that defines the output unit.
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: Integer scalar.\\
%% \item[desc\_a] The communication descriptor of type \descdata that
%% must be printed.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a variable of type \descdata.\\
%% \end{description}
19 years ago
%% \begin{description}
%% \item[\bf On Return]
%% \item[glob] ??????
%% \item[short] ??????
%% \end{description}
19 years ago
%
%% psb_spalloc %%
19 years ago
%
\subroutine{psb\_spall}{Allocates a sparse matrix}
19 years ago
\syntax{call psb\_spall}{a, desc\_a, info, nnz}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[nnz] An estimate of the number of nonzeroes in the local
part of the assembled matrix.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[a] the matrix to be allocated.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf out}.\\
Specified as: a structured data of type \spdata.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item On exit from this routine the sparse matrix is in the build
state.
\item The descriptor may be in either the build or assembled state.
\item Providing a good estimate for the number of nonzeroes $nnz$ in
the assembled matrix may substantially improve performance in the
matrix build phase, as it will reduce or eliminate the need for
(potentially multiple) data reallocations.
\end{enumerate}
19 years ago
%
%% psb_spins %%
19 years ago
%
\subroutine{psb\_spins}{Insert a cloud of elements into a sparse matrix}
19 years ago
\syntax{call psb\_spins}{nz, ia, ja, val, a, desc\_a, info}
19 years ago
\begin{description}
\item[Type:] Asynchronous.
19 years ago
\item[\bf On Entry]
\item[nz] the number of elements to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer scalar.
\item[ia] the row indices of the elements to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer array of size $nz$.
\item[ja] the column indices of the elements to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer array of size $nz$.
\item[val] the elements to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an array of size $nz$.
\item[desc\_a] The communication descriptor.\\
Scope: {\bf local}. \\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a variable of type \descdata.\\
%% \item[is] the starting row on matrix $a$.\\
%% Scope:{\bf local}.\\
%% Type:{\bf optional}.\\
%% Specified as: an integer vaule.
%% \item[js] the starting column on matrix $a$.\\
%% Scope:{\bf local}.\\
%% Type:{\bf optional}\\
%% Specified as: an integer value
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[a] the matrix into which elements will be inserted.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \spdata.
\item[desc\_a] The communication descriptor.\\
Scope: {\bf local}. \\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a variable of type \descdata.\\
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item On entry to this routine the descriptor may be in either the
build or assembled state.
\item On entry to this routine the sparse matrix may be in either the
build or update state.
\item If the descriptor is in the build state, then the sparse matrix
must also be in the build state; the action of the routine is to
(implicitly) call \verb|psb_cdins| to add entries to the sparsity
pattern; each sparse matrix entry implicitly defines a graph edge,
that is passed to the descriptor routine for the appropriate
processing.
\item Any coefficients from matrix rows not assigned to the calling
process are silently ignored;
\item If the descriptor is in the assembled state, then any entries in
the sparse matrix that would generate additional communication
requirements will be ignored;
\item If the matrix is in the update state, any entries in positions
that were not present in the original matrix will be ignored.
\end{enumerate}
19 years ago
%
%% psb_spasb %%
%
\subroutine{psb\_spasb}{Sparse matrix assembly routine}
\syntax{call psb\_spasb}{a, desc\_a, info, afmt, upd, dupl}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[afmt] the storage format for the sparse matrix.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an array of characters. Defalt: 'CSR'.
\item[upd] Provide for updates to the matrix coefficients.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: integer, possible values: \verb|psb_upd_srch_|, \verb|psb_upd_perm_|
\item[dupl] How to handle duplicate coefficients.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: integer, possible values: \verb|psb_dupl_ovwrt_|,
\verb|psb_dupl_add_|, \verb|psb_dupl_err_|.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[a] the matrix to be assembled.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \spdata.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item On entry to this routine the descriptor must be in the
assembled state, i.e. \verb|psb_cdasb| must already have been called.
\item The sparse matrix may be in either the build or update state;
\item Duplicate entries are detected and handled in both build and
update state, with the exception of the error action that is only
taken in the build state, i.e. on the first assembly;
\item If the update choice is \verb|psb_upd_perm_|, then subsequent
calls to \verb|psb_spins| to update the matrix must be arranged in
such a way as to produce exactly the same sequence of coefficient
values as encountered at the first assembly;
\item On exit from this routine the matrix is in the assembled state,
and thus is suitable for the computational routines.
\end{enumerate}
19 years ago
%% %
%% %% psb_spcnv %%
%% %
%% \subroutine{psb\_spcnv}{Converts a sparse matrix storage format}
%% \syntax{call psb\_spcnv}{a, b, desc\_a, info}
%% \begin{description}
%% \item[\bf On Entry]
%% \item[a] the matrix to be converted.\\
%% Scope:{\bf local}\\
%% Type:{\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[desc\_a] the communication descriptor.\\
%% Scope:{\bf local}.\\
%% Type:{\bf required}.\\
%% Specified as: a structured data of type \descdata.
%% \end{description}
%% \begin{description}
%% \item[\bf On Return]
%% \item[b] the converted matrix.\\
%% Scope:{\bf local}\\
%% Type:{\bf required}\\
%% Specified as: a structured data of type \spdata.
%% \item[info] Error code.
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: an integer variable.
%% \end{description}
19 years ago
%
%% psb_spfree %%
19 years ago
%
\subroutine{psb\_spfree}{Frees a sparse matrix}
19 years ago
\syntax{call psb\_spfree}{a, desc\_a, info}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[a] the matrix to be freed.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \spdata.
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
19 years ago
%
%% psb_sprn %%
19 years ago
%
\subroutine{psb\_sprn}{Reinit sparse matrix structure for psblas routines.}
19 years ago
\syntax{call psb\_sprn}{a, decsc\_a, info, clear}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[a] the matrix to be reinitialized.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf inout}.\\
Specified as: a structured data of type \spdata.
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[clear] Choose whether to zero out matrix coefficients\\
Scope:{\bf local}.\\
Type:{\bf optional}.\\
Intent: {\bf in}.\\
Default: true.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item On exit from this routine the sparse matrix is in the update
state.
\end{enumerate}
%
%% psb_spupdate %%
%
%% \subroutine{psb\_spupdate}{Updates a sparse matrix.}
%% \syntax{call psb\_spupdate}{a, ia, ja, blck, desc\_a, info, ix, jx, updflag}
%% \begin{description}
%% \item[\bf On Entry]
%% \end{description}
%% \begin{description}
%% \item[\bf On Return]
%% \end{description}
%% %
%% %% psb_csrp %%
%% %
%% \subroutine{psb\_csrp}{Applies a right permutation to a sparse matrix}
%% \syntax{call psb\_csrp}{trans, iperm, a, info}
%% \begin{description}
%% \item[\bf On Entry]
%% \item[trans] A character that specifies whether to permute $A$ or $A^T$.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a single character with value 'N' for $A$ or 'T' for $A^T$.\\
%% \item[iperm] An integer array containing permutation information.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: an integer one-dimensional array.\\
%% \item[a] The sparse matrix to be permuted.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: a \spdata variable.\\
%% \begin{description}
%% \item[\bf On Return]
%% \item[info] Error code.\\
%% Scope: {\bf local} \\
%% Type: {\bf required}\\
%% Specified as: Integer scalar.\\
%% \end{description}
%
%% psb_alloc %%
%
\subroutine{psb\_geall}{Allocates a dense matrix}
\syntax{call psb\_geall}{x, desc\_a, info, n, lb}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[desc\_a] The communication descriptor.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a variable of type \descdata.\\
\item[n] The number of columns of the dense matrix to be allocated.\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: Integer scalar, default $1$. It is not a valid argument if $x$ is a
rank-1 array.
\item[lb] The lower bound for the column index range of the dense matrix to be allocated.\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: Integer scalar, default $1$. It is not a valid argument if $x$ is a
rank-1 array.
\end{description}
\begin{description}
\item[\bf On Return]
\item[x] The dense matrix to be allocated.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf out}.\\
Specified as: a rank one or two array with the ALLOCATABLE
attribute, of type real, complex or integer.\\
\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}
19 years ago
%
%% psb_ins %%
19 years ago
%
\subroutine{psb\_geins}{Dense matrix insertion routine}
19 years ago
\syntax{call psb\_geins}{m, irw, val, x, desc\_a, info,dupl}
19 years ago
\begin{description}
\item[Type:] Asynchronous.
19 years ago
\item[\bf On Entry]
\item[m] Number of rows in $val$ to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value.
\item[irw] Indices of the rows to be inserted. Specifically, row $i$
of $val$ will be inserted into the local row corresponding to the
global row index $irw(i)$.
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer array.
\item[val] the dense submatrix to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a rank 1 or 2 array.
Specified as: an integer value.
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[dupl] How to handle duplicate coefficients.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: integer, possible values: \verb|psb_dupl_ovwrt_|,
\verb|psb_dupl_add_|.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[x] the output dense matrix.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one or two array with the ALLOCATABLE
attribute, of type real, complex or integer.\\
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item Dense vectors/matrices do not have an associated state;
\item Duplicate entries are either overwritten or added, there is no
provision for raising an error condition.
\end{enumerate}
%
%% psb_asb %%
%
\subroutine{psb\_geasb}{Assembly a dense matrix}
\syntax{call psb\_geasb}{x, desc\_a, info}
19 years ago
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[desc\_a] The communication descriptor.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a variable of type \descdata.\\
\end{description}
19 years ago
\begin{description}
\item[\bf On Return]
\item[x] The dense matrix to be assembled.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one or two array with the ALLOCATABLE
attribute, of type real, complex or integer.\\
\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}
19 years ago
%
%% psb_free %%
19 years ago
%
\subroutine{psb\_gefree}{Frees a dense matrix}
19 years ago
\syntax{call psb\_gefree}{x, desc\_a, info}
19 years ago
\begin{description}
\item[Type:] Synchronous.
19 years ago
\item[\bf On Entry]
\item[x] The dense matrix to
be freed.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one or two array with the ALLOCATABLE
attribute, of type real, complex or integer.\\
\item[desc\_a] The communication descriptor.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a variable of type \descdata.\\
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
19 years ago
%
%% psb_gelp %%
19 years ago
%
\subroutine{psb\_gelp}{Applies a left permutation to a dense matrix}
19 years ago
\syntax{call psb\_gelp}{trans, iperm, x, info}
19 years ago
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[trans] A character that specifies whether to permute $A$ or $A^T$.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a single character with value 'N' for $A$ or 'T' for $A^T$.\\
\item[iperm] An integer array containing permutation information.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer one-dimensional array.\\
\item[x] The dense matrix to be permuted.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a one or two dimensional array.\\
\end{description}
19 years ago
\begin{description}
\item[\bf On Return]
\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}
19 years ago
%
%% psb_glob_to_loc %%
%
\subroutine{psb\_glob\_to\_loc}{Global to local indices convertion}
\syntax{call psb\_glob\_to\_loc}{x, y, desc\_a, info, iact,owned}
\syntax*{call psb\_glob\_to\_loc}{x, desc\_a, info, iact,owned}
19 years ago
\begin{description}
\item[Type:] Asynchronous.
19 years ago
\item[\bf On Entry]
\item[x] An integer vector of indices to be converted.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in, inout}.\\
Specified as: a rank one integer array.\\
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[iact] specifies action to be taken in case of range errors.
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: a character variable \verb|I|gnore, \verb|W|arning or
\verb|A|bort, default \verb|I|gnore.
\item[owned] Specfies valid range of input
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
If true, then only indices strictly owned by the current process are
considered valid, if false then halo indices are also
accepted. Default: false.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[x] If $y$ is not present,
then $x$ is overwritten with the translated integer indices.
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one integer array.
\item[y] If $y$ is present,
then $y$ is overwritten with the translated integer indices, and $x$
is left unchanged.
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Specified as: a rank one integer array.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
19 years ago
\end{description}
\section*{Notes}
\begin{enumerate}
\item If an input index is out of range, then the corresponding output
index is set to a negative number;
\item The default \verb|I|gnore means that the negative output is the
only action taken on an out-of-range input.
\end{enumerate}
19 years ago
%
%% psb_loc_to_glob %%
%
\subroutine{psb\_loc\_to\_glob}{Local to global indices conversion}
\syntax{call psb\_loc\_to\_glob}{x, y, desc\_a, info, iact}
\syntax*{call psb\_loc\_to\_glob}{x, desc\_a, info, iact}
19 years ago
\begin{description}
\item[Type:] Asynchronous.
19 years ago
\item[\bf On Entry]
\item[x] An integer vector of indices to be converted.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in, inout}.\\
Specified as: a rank one integer array.\\
\item[desc\_a] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[iact] specifies action to be taken in case of range errors.
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: a character variable \verb|I|gnore, \verb|W|arning or
\verb|A|bort, default \verb|I|gnore.
19 years ago
\end{description}
\begin{description}
\item[\bf On Return]
\item[x] If $y$ is not present,
then $x$ is overwritten with the translated integer indices.
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one integer array.
\item[y] If $y$ is not present,
then $y$ is overwritten with the translated integer indices, and $x$
is left unchanged.
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Specified as: a rank one integer array.
\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}
%
%% psb_ins %%
%
\subroutine{psb\_get\_boundary}{Extract list of boundary elements}
\syntax{call psb\_get\_boundary}{bndel, desc, info}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[desc] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[bndel] The list of boundary elements on the calling process, in
local numbering.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf out}.\\
Specified as: a rank one array with the ALLOCATABLE
attribute, of type integer.\\
\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}
\section*{Notes}
\begin{enumerate}
\item If there are no boundary elements (i.e., if the local part of
the connectivity graph is self-contained) the output vector is set
to the ``not allocated'' state.
\item Otherwise the size of \verb|bndel| will be exactly equal to the
number of boundary elements.
\end{enumerate}
\subroutine{psb\_get\_overlap}{Extract list of overlap elements}
\syntax{call psb\_get\_overlap}{ovrel, desc, info}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[desc] the communication descriptor.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[ovrel] The list of overlap elements on the calling process, in
local numbering.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf out}.\\
Specified as: a rank one array with the ALLOCATABLE
attribute, of type integer.\\
\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}
\section*{Notes}
\begin{enumerate}
\item If there are no overlap elements the output vector is set
to the ``not allocated'' state.
\item Otherwise the size of \verb|ovrel| will be exactly equal to the
number of overlap elements.
\end{enumerate}
\subroutine{psb\_sp\_getrow}{Extract row(s) from a sparse matrix}
\syntax{call psb\_sp\_getrow}{row, a, nz, ia, ja, val, info, append,
nzin, lrw}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[row] The (first) row to be extracted.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer $>0$.
\item[a] the matrix from which to get rows.\\
Scope:{\bf local}\\
Type:{\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\item[append] Whether to append or overwrite existing output.\\
Scope:{\bf local}\\
Type:{\bf optional}\\
Intent: {\bf in}.\\
Specified as: a logical value default: false (overwrite).
\item[nzin] Input size to be appended to.\\
Scope:{\bf local}\\
Type:{\bf optional}\\
Intent: {\bf in}.\\
Specified as: an integer $>0$. When append is true, specifies how many
entries in the output vectors are already filled.
\item[lrw] The last row to be extracted.\\
Scope:{\bf local}\\
Type:{\bf optional}\\
Intent: {\bf in}.\\
Specified as: an integer $>0$, default: $row$.
%% \item[is] the starting row on matrix $a$.\\
%% Scope:{\bf local}.\\
%% Type:{\bf optional}.\\
%% Specified as: an integer vaule.
%% \item[js] the starting column on matrix $a$.\\
%% Scope:{\bf local}.\\
%% Type:{\bf optional}\\
%% Specified as: an integer value
\end{description}
\begin{description}
\item[\bf On Return]
\item[nz] the number of elements returned by this call.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf out}.\\
Returned as: an integer scalar.
\item[ia] the row indices.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer array with the \verb|ALLOCATABLE| attribute.
\item[ja] the column indices of the elements to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer array with the \verb|ALLOCATABLE| attribute.
\item[val] the elements to be inserted.\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
Intent: {\bf inout}.\\
Specified as: a real array with the \verb|ALLOCATABLE| attribute.
\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}
\section*{Notes}
\begin{enumerate}
\item The output $nz$ is always the size of the output generated by
the current call; thus, if \verb|append=.true.|, the total output
size will be $nzin+nz$, with the newly extracted coefficients stored in
entries \verb|nzin+1:nzin+nz| of the array arguments;
\item When \verb|append=.true.| the output arrays are reallocated as
necessary;
\item The row and column indices are returned in the local numbering
scheme; if the global numbering is desired, the user may employ the
\verb|psb_loc_to_glob| routine on the output.
\end{enumerate}
\subroutine{psb\_sizeof}{Memory occupation}
This function computes the memory occupation of a PSBLAS object.
\syntax{psb\_sizeof}{a}
\syntax*{psb\_sizeof}{desc\_a}
\syntax*{psb\_sizeof}{prec}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[a] A sparse matrix
$A$. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\item[desc\_a] Communication descriptor.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[prec]
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a preconditioner data structure \precdata.
\item[\bf On Return]
\item[Function value] The memory occupation of the object specified in
the calling sequence, in bytes.\\
Scope: {\bf local} \\
Returned as: an integer number.
\end{description}
\subroutine{Sorting utilities}{}
\subroutine*{psb\_msort}{Sorting by the Merge-sort algorithm}
\subroutine*{psb\_qsort}{Sorting by the Quicksort algorithm}
\subroutine*{psb\_hsort}{Sorting by the Heapsort algorithm}
\syntax{call psb\_msort}{x,ix,dir,flag}
\syntax*{call psb\_qsort}{x,ix,dir,flag}
\syntax*{call psb\_hsort}{x,ix,dir,flag}
These serial routines sort a sequence $X$ into ascending or
descending order. The argument meaning is identical for the three
calls; the only difference is the algorithm used to accomplish the
task (see Usage Notes below).
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[x] The sequence to be sorted.\\
Type:{\bf required}.\\
Specified as: an integer, real or complex 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_|,
\verb|psb_sort_down_|, \verb|psb_asort_up_|, \verb|psb_asort_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, real or complex 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 sorting can be performed in the up/down direction, on the
natural or absolute values; for complex data the sorting can only
be done on the absolute values;
\item The routines return the items in the chosen ordering; the
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 three sorting algorithms have a similar $O(n \log n)$ expected
running time; in the average case quicksort will be the
fastest and merge-sort the slowest. 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 and heap-sort is
$O(n\log n)$ as the average case;
\item The merge-sort algorithm is implemented to take advantage of
subsequences that may be already in the desired ordering prior to
the subroutine call; this situation is relatively common when
dealing with groups of indices of sparse matrix entries, thus
merge-sort is often the preferred choice when a sorting is needed
by other routines in the library.
\end{enumerate}
\end{enumerate}
19 years ago
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: