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.
1393 lines
41 KiB
TeX
1393 lines
41 KiB
TeX
\section{Data management routines}
|
|
\label{sec:toolsrout}
|
|
|
|
|
|
%
|
|
%% psb_cdall %%
|
|
%
|
|
\subroutine{psb\_cdall}{Allocates a communication descriptor}
|
|
|
|
\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}
|
|
|
|
This subroutine initializes the communication descriptor associated
|
|
with an index space. Exactly one of the optional arguments
|
|
\verb|parts|, \verb|vg|, \verb|vl| or \verb|nl|
|
|
must be specified, thereby choosing
|
|
the specific initialization strategy:
|
|
\begin{description}
|
|
\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.
|
|
\item[vg] Data allocation: each index $i\in \{1\dots mg\}$ is allocated
|
|
to process $vg(i)$.
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer array.
|
|
\item[flag] Specifies whether entries in $vg$ are zero- or one-based.
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer value $0,1$, default $0$.
|
|
|
|
\item[mg] the (global) number of rows of the problem.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Intent: {\bf in}.\\
|
|
Specified as: an integer value. It is required if \verb|parts| is
|
|
specified.
|
|
\item[parts] the subroutine that defines the partitioning scheme.\\
|
|
Scope:{\bf global}.\\
|
|
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}.\\
|
|
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.
|
|
\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.
|
|
\end{description}
|
|
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\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:
|
|
\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}
|
|
\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.
|
|
\end{description}
|
|
\item On exit from this routine the descriptor is in the build state
|
|
\end{enumerate}
|
|
|
|
|
|
%
|
|
%% psb_cdins %%
|
|
%
|
|
\subroutine{psb\_cdins}{Communication descriptor insert routine}
|
|
|
|
\syntax{call psb\_cdins}{nz, ia, ja, desc\_a, info}
|
|
|
|
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.
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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.
|
|
\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.
|
|
\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}
|
|
|
|
|
|
|
|
%
|
|
%% psb_cdasb %%
|
|
%
|
|
\subroutine{psb\_cdasb}{Communication descriptor assembly routine}
|
|
|
|
\syntax{call psb\_cdasb}{desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[Type:] Synchronous.
|
|
\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.
|
|
\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]
|
|
\end{description}
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\item On exit from this routine the descriptor is in the assembled
|
|
state.
|
|
\end{enumerate}
|
|
|
|
|
|
|
|
%
|
|
%% psb_cdcpy %%
|
|
%
|
|
\subroutine{psb\_cdcpy}{Copies a communication descriptor}
|
|
|
|
\syntax{call psb\_cdcpy}{desc\_in, desc\_out, info}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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.
|
|
|
|
\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.
|
|
\end{description}
|
|
|
|
|
|
%
|
|
%% psb_cdfree %%
|
|
%
|
|
\subroutine{psb\_cdfree}{Frees a communication descriptor}
|
|
|
|
\syntax{call psb\_cdfree}{desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[Type:] Synchronous.
|
|
\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.
|
|
\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.
|
|
\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}
|
|
|
|
|
|
|
|
|
|
%
|
|
%% psb_descprt %%
|
|
%
|
|
%% \subroutine{psb\_cdprt}{Prints a descriptor}
|
|
|
|
%% \syntax{call psb\_cdprt}{iout, desc\_a, glob, short}
|
|
|
|
%% \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}
|
|
|
|
%% \begin{description}
|
|
%% \item[\bf On Return]
|
|
%% \item[glob] ??????
|
|
%% \item[short] ??????
|
|
%% \end{description}
|
|
|
|
|
|
|
|
%
|
|
%% psb_spalloc %%
|
|
%
|
|
\subroutine{psb\_spall}{Allocates a sparse matrix}
|
|
|
|
\syntax{call psb\_spall}{a, desc\_a, info, nnz}
|
|
|
|
\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 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.
|
|
\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.
|
|
\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}
|
|
|
|
|
|
|
|
%
|
|
%% psb_spins %%
|
|
%
|
|
\subroutine{psb\_spins}{Insert a cloud of elements into a sparse matrix}
|
|
|
|
\syntax{call psb\_spins}{nz, ia, ja, val, a, desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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
|
|
\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.
|
|
\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}
|
|
|
|
%
|
|
%% psb_spasb %%
|
|
%
|
|
\subroutine{psb\_spasb}{Sparse matrix assembly routine}
|
|
|
|
\syntax{call psb\_spasb}{a, desc\_a, info, afmt, upd, dupl}
|
|
|
|
\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 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_|.
|
|
\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.
|
|
\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}
|
|
|
|
|
|
|
|
%% %
|
|
%% %% 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}
|
|
|
|
|
|
|
|
%
|
|
%% psb_spfree %%
|
|
%
|
|
\subroutine{psb\_spfree}{Frees a sparse matrix}
|
|
|
|
\syntax{call psb\_spfree}{a, desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[Type:] Synchronous.
|
|
\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.
|
|
\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.
|
|
\end{description}
|
|
|
|
|
|
|
|
|
|
%
|
|
%% psb_sprn %%
|
|
%
|
|
\subroutine{psb\_sprn}{Reinit sparse matrix structure for psblas routines.}
|
|
|
|
\syntax{call psb\_sprn}{a, decsc\_a, info, clear}
|
|
|
|
\begin{description}
|
|
\item[Type:] Synchronous.
|
|
\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.
|
|
\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.
|
|
\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}
|
|
|
|
\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 ignored 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}
|
|
|
|
|
|
%
|
|
%% psb_ins %%
|
|
%
|
|
\subroutine{psb\_geins}{Dense matrix insertion routine}
|
|
|
|
\syntax{call psb\_geins}{m, irw, val, x, desc\_a, info,dupl}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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_|.
|
|
\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.
|
|
\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}
|
|
|
|
\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}
|
|
|
|
\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}
|
|
%
|
|
%% psb_free %%
|
|
%
|
|
\subroutine{psb\_gefree}{Frees a dense matrix}
|
|
|
|
\syntax{call psb\_gefree}{x, desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[Type:] Synchronous.
|
|
\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.\\
|
|
\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.
|
|
\end{description}
|
|
|
|
|
|
%
|
|
%% psb_gelp %%
|
|
%
|
|
\subroutine{psb\_gelp}{Applies a left permutation to a dense matrix}
|
|
|
|
\syntax{call psb\_gelp}{trans, iperm, x, info}
|
|
|
|
\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}
|
|
|
|
\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}
|
|
|
|
|
|
%
|
|
%% 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}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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.
|
|
\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.
|
|
\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}
|
|
|
|
|
|
%
|
|
%% 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}
|
|
|
|
\begin{description}
|
|
\item[Type:] Asynchronous.
|
|
\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.
|
|
\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; for
|
|
complex data the sorting must 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}
|
|
|
|
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: "userguide"
|
|
%%% End:
|