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.
1238 lines
34 KiB
TeX
1238 lines
34 KiB
TeX
\section{Data management, environment handling and auxiliary
|
|
communication routines}
|
|
\label{sec:toolsrout}
|
|
|
|
\subroutine{psb\_init}{Initializes PSBLAS parallel environment}
|
|
|
|
\syntax{call psb\_init}{ictxt, np}
|
|
|
|
This subroutine initializes the PSBLAS parallel environment, defining
|
|
a virtual parallel machine.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[np] Number of processes in the PSBLAS virtual parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Specified as: an integer value. \
|
|
Default: use all available processes provided by the underlying
|
|
parallel environment.
|
|
\end{description}
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\item A call to this routine must precede any other PSBLAS call.
|
|
\item It is an error to specify a value for $np$ greater than the
|
|
number of processes available in the underlying parallel execution
|
|
environment.
|
|
\end{enumerate}
|
|
|
|
|
|
\subroutine{psb\_info}{Return information about PSBLAS parallel environment}
|
|
|
|
\syntax{call psb\_info}{ictxt, iam, np}
|
|
|
|
This subroutine returns informantion about the PSBLAS parallel environment, defining
|
|
a virtual parallel machine.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[iam] Identifier of current process in the PSBLAS virtual parallel machine.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value. $-1 \le iam \le np-1$\
|
|
\item[np] Number of processes in the PSBLAS virtual parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable. \
|
|
\end{description}
|
|
|
|
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\item For processes in the virtual parallel machine the identifier
|
|
will satisfy $0 \le iam \le np-1$;
|
|
\item If the user has requested on \verb|psb_init| a number of
|
|
processes less than the total available in the parallel execution
|
|
environment, the remaining processes will have on return $iam=-1$;
|
|
any such process may only place a call to \verb|psb_exit|, and is
|
|
required to do so.
|
|
\end{enumerate}
|
|
|
|
|
|
\subroutine{psb\_exit}{Exit from PSBLAS parallel environment}
|
|
|
|
\syntax{call psb\_exit}{ictxt}
|
|
|
|
This subroutine exits from the PSBLAS parallel virtual machine.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\item This routine may be called even if a previous call to
|
|
\verb|psb_info| has returned with $iam=-1$; indeed, it it is the ONLY
|
|
routine that may be called in this situation, and it is required to
|
|
do so.
|
|
\end{enumerate}
|
|
|
|
\subroutine{psb\_wtime}{Wall clock timing}
|
|
|
|
\syntax{time = psb\_wtime}{}
|
|
|
|
This function returns a wall clock timer. The resolution of the timer
|
|
is dependent on the underlying parallel environment implementation.
|
|
\begin{description}
|
|
\item[\bf On Exit ]
|
|
\item[Function value] the elapsed time in seconds.\\
|
|
Returned as: a \verb|real(kind(1.d0))| integer variable.
|
|
\end{description}
|
|
|
|
|
|
\subroutine{psb\_barrier}{Sinchronization point parallel environment}
|
|
|
|
\syntax{call psb\_barrier}{ictxt}
|
|
|
|
This subroutine acts as a synchronization point for the PSBLAS
|
|
parallel virtual machine. As such, it must be called by all
|
|
participating processes.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
|
|
\subroutine{psb\_abort}{Abort a computation}
|
|
|
|
\syntax{call psb\_abort}{ictxt}
|
|
|
|
This subroutine aborts computation on the parallel virtual machine.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
|
|
|
|
%
|
|
%% psb_cdall %%
|
|
%
|
|
\subroutine{psb\_cdall}{Allocates a communication descriptor}
|
|
|
|
\syntax{call psb\_cdall}{m, n, parts, icontxt, desc\_a, info}
|
|
\syntax*{call psb\_cdall}{m, v, icontxt, desc\_a, info, flag}
|
|
|
|
This subroutine initializes the communication descriptor associated
|
|
with an index space. It takes two forms depending on whether the user
|
|
specifies the domain partitioning through a subroutine or through a vector
|
|
\begin{description}
|
|
\item[\bf First Form: On Entry ]
|
|
\item[m] the number of rows of the problem.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value.
|
|
\item[n] the number of columns of the problem.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value. Currently constrained to be $m=n$.
|
|
\item[parts] the subroutine that defines the partitioning scheme.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: a subroutine.
|
|
\item[icontxt] the communication context.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value.
|
|
\end{description}
|
|
\begin{description}
|
|
\item[\bf Second Form: On Entry ]
|
|
\item[m] the size of the index space.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value $m>0$.
|
|
\item[v] Data allocation: each index $i\in \{1\dots m\}$ is allocated
|
|
to process $v(i)$.
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer array of size $m$.
|
|
\item[icontxt] the communication context.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value.
|
|
\item[flag] Specifies whether entries in $v$ are zero- or one-based.
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Specified as: an integer value $0,1$, default $0$.
|
|
\end{description}
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[desc\_a] the communication descriptor.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: a structured data of type \descdata.
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.\\
|
|
\end{description}
|
|
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\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}
|
|
|
|
\begin{description}
|
|
\item[\bf On Entry]
|
|
\item[nz] the number of points being inserted.\\
|
|
Scope: {\bf local}.\\
|
|
Type: {\bf required}.\\
|
|
Specified as: an integer value.
|
|
\item[ia] the row indices of the points being inserted.\\
|
|
Scope: {\bf local}.\\
|
|
Type: {\bf required}.\\
|
|
Specified as: an integer array of length $nz$.
|
|
\item[ja] the column indices of the points being inserted.\\
|
|
Scope: {\bf local}.\\
|
|
Type: {\bf required}.\\
|
|
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}.\\
|
|
Specified as: a structured data of type \descdata.
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
\section*{Notes}
|
|
\begin{enumerate}
|
|
\item This routine may only be called if the descriptor is in the
|
|
build state
|
|
\end{enumerate}
|
|
|
|
|
|
|
|
%
|
|
%% psb_cdasb %%
|
|
%
|
|
\subroutine{psb\_cdasb}{Communication descriptor assembly routine}
|
|
|
|
\syntax{call psb\_cdasb}{desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[\bf On Entry]
|
|
\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.
|
|
%\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\_out, desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[\bf On Entry]
|
|
\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[desc\_out] the communication descriptor copy.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: a structured data of type \descdata.
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.\\
|
|
\end{description}
|
|
|
|
|
|
%
|
|
%% psb_cdfree %%
|
|
%
|
|
\subroutine{psb\_cdfree}{Frees a communication descriptor}
|
|
|
|
\syntax{call psb\_cdfree}{desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[\bf On Entry]
|
|
\item[desc\_a] the communication descriptor to be freed.\\
|
|
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_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[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[\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[\bf On Entry]
|
|
\item[desc\_a] the communication descriptor.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
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}.\\
|
|
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}\\
|
|
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}
|
|
\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[\bf On Entry]
|
|
\item[nz] the number of elements to be inserted.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer scalar.
|
|
\item[ia] the row indices of the elements to be inserted.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
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}.\\
|
|
Specified as: an integer array of size $nz$.
|
|
\item[val] the elements to be inserted.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an array of size $nz$.
|
|
\item[desc\_a] The communication descriptor.\\
|
|
Scope: {\bf local}. \\
|
|
Type: {\bf required}.\\
|
|
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}\\
|
|
Specified as: a structured data of type \spdata.
|
|
\item[desc\_a] The communication descriptor.\\
|
|
Scope: {\bf local}. \\
|
|
Type: {\bf required}.\\
|
|
Specified as: a variable of type \descdata.\\
|
|
\item[info] Error code.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
\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
|
|
ought 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;
|
|
\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[\bf On Entry]
|
|
\item[desc\_a] the communication descriptor.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: a structured data of type \descdata.
|
|
\item[afmt] the storage format for the sparse matrix.\\
|
|
Scope: {\bf global}.\\
|
|
Type: {\bf optional}.\\
|
|
Specified as: an array of characters. Defalt: 'CSR'.
|
|
\item[upd] Provide for updates to the matrix coefficients.\\
|
|
Scope: {\bf global}.\\
|
|
Type: {\bf optional}.\\
|
|
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}.\\
|
|
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}\\
|
|
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}
|
|
|
|
\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[\bf On Entry]
|
|
\item[a] the matrix to be freed.\\
|
|
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[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.
|
|
\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[\bf On Entry]
|
|
\item[a] the matrix to be reinitialized.\\
|
|
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.
|
|
\item[clear] Choose whether to zero out matrix coefficients\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf optional}.\\
|
|
Default: true.
|
|
\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}
|
|
\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, desc\_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.\\
|
|
%% \item[desc\_a] The communication descriptor of type \descdata.\\
|
|
%% Scope: {\bf local} \\
|
|
%% Type: {\bf required}\\
|
|
%% 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}\\
|
|
%% 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[\bf On Entry]
|
|
\item[desc\_a] The communication descriptor.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
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}\\
|
|
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}\\
|
|
Specified as: a rank one or two array with the POINTER
|
|
attribute, of type real, complex or integer.\\
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: Integer scalar.
|
|
\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[\bf On Entry]
|
|
\item[m] Number of rows in $val$ to be inserted.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
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}.\\
|
|
Specified as: an integer array.
|
|
\item[val] the dense submatrix to be inserted.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
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}.\\
|
|
Specified as: a structured data of type \descdata.
|
|
\item[dupl] How to handle duplicate coefficients.\\
|
|
Scope: {\bf global}.\\
|
|
Type: {\bf optional}.\\
|
|
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}\\
|
|
Specified as: a rank one or two array with the POINTER
|
|
attribute, of type real, complex or integer.\\
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.
|
|
\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[\bf On Entry]
|
|
\item[desc\_a] The communication descriptor.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
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}\\
|
|
Specified as: a rank one or two array with the POINTER
|
|
attribute, of type real, complex or integer.\\
|
|
\item[info] Error code.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: Integer scalar.\\
|
|
\end{description}
|
|
%
|
|
%% psb_free %%
|
|
%
|
|
\subroutine{psb\_gefree}{Frees a dense matrix}
|
|
|
|
\syntax{call psb\_gefree}{x, desc\_a, info}
|
|
|
|
\begin{description}
|
|
\item[\bf On Entry]
|
|
\item[x] The dense matrix to
|
|
be freed.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: a rank one or two array with the POINTER
|
|
attribute, of type real, complex or integer.\\
|
|
|
|
\item[desc\_a] The communication descriptor.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
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}\\
|
|
Specified as: Integer scalar.\\
|
|
\end{description}
|
|
|
|
|
|
%
|
|
%% psb_gelp %%
|
|
%
|
|
\subroutine{psb\_gelp}{Applies a left permutation to a dense matrix}
|
|
|
|
\syntax{call psb\_gelp}{trans, iperm, x, desc\_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[x] The dense matrix to be permuted.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: a one or two dimensional array.\\
|
|
\item[desc\_a] The communication descriptor.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
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}\\
|
|
Specified as: Integer scalar.\\
|
|
\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}
|
|
\syntax*{call psb\_glob\_to\_loc}{x, desc\_a, info, iact}
|
|
|
|
\begin{description}
|
|
\item[\bf On Entry]
|
|
\item[x] An integer vector of indices to be converted.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: a rank one integer array.\\
|
|
\item[desc\_a] the communication descriptor.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
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}\\
|
|
Specified as: a character variable \verb|E|, \verb|W| or \verb|A|.
|
|
\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}\\
|
|
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}\\
|
|
Specified as: a rank one integer array.
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
|
|
|
|
%
|
|
%% 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[\bf On Entry]
|
|
\item[x] An integer vector of indices to be converted.\\
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: a rank one integer array.\\
|
|
\item[desc\_a] the communication descriptor.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
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}\\
|
|
Specified as: a character variable \verb|E|, \verb|W| or \verb|A|.
|
|
\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}\\
|
|
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}\\
|
|
Specified as: a rank one integer array.
|
|
\item[info] Error code.
|
|
Scope: {\bf local} \\
|
|
Type: {\bf required}\\
|
|
Specified as: an integer variable.
|
|
\end{description}
|
|
|
|
|
|
\subroutine{psb\_bcast}{Broadcast data}
|
|
|
|
\syntax{call psb\_bcast}{ictxt, dat, root}
|
|
|
|
This subroutine implements a broadcast operation based on the
|
|
underlying communication library.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\item[dat] On the root process, the data to be broadcast.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type, rank and size must agree on all processes.
|
|
\item[root] Root process holding data to be broadcast.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Specified as: an integer value $0<= root <= np-1$, default 0 \
|
|
\end{description}
|
|
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[dat] On processes other than root, the data to be broadcast.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type, rank and size must agree on all processes.
|
|
\end{description}
|
|
|
|
|
|
\subroutine{psb\_sum}{Global sum}
|
|
|
|
\syntax{call psb\_sum}{ictxt, dat, root}
|
|
|
|
This subroutine implements a sum reduction operation based on the
|
|
underlying communication library.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\item[dat] The local contribution to the global sum.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type, rank and size must agree on all processes.
|
|
\item[root] Process to hold the final sum, or $-1$ to make it available
|
|
on all processes.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Specified as: an integer value $-1<= root <= np-1$, default -1. \
|
|
\end{description}
|
|
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[dat] On destination process(es), the result of the sum operation.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \\
|
|
Type, rank and size must agree on all processes.
|
|
\end{description}
|
|
|
|
\subroutine{psb\_amx}{Global maximum absolute value}
|
|
|
|
\syntax{call psb\_amx}{ictxt, dat, root}
|
|
|
|
This subroutine implements a maximum absolute value reduction
|
|
operation based on the underlying communication library.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\item[dat] The local contribution to the global maximum.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type, rank and size must agree on all processes.
|
|
\item[root] Process to hold the final sum, or $-1$ to make it available
|
|
on all processes.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Specified as: an integer value $-1<= root <= np-1$, default -1. \\
|
|
\end{description}
|
|
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[dat] On destination process(es), the result of the maximum operation.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type, rank and size must agree on all processes.
|
|
\end{description}
|
|
|
|
\subroutine{psb\_amn}{Global minimum absolute value}
|
|
|
|
\syntax{call psb\_amn}{ictxt, dat, root}
|
|
|
|
This subroutine implements a minimum absolute value reduction
|
|
operation based on the underlying communication library.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\item[dat] The local contribution to the global minimum.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type, rank and size must agree on all processes.
|
|
\item[root] Process to hold the final sum, or $-1$ to make it available
|
|
on all processes.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf optional}.\\
|
|
Specified as: an integer value $-1<= root <= np-1$, default -1. \\
|
|
\end{description}
|
|
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[dat] On destination process(es), the result of the minimum operation.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \\
|
|
Type, rank and size must agree on all processes.
|
|
\end{description}
|
|
|
|
|
|
\subroutine{psb\_snd}{Send data}
|
|
|
|
\syntax{call psb\_snd}{ictxt, dat, dst, m}
|
|
|
|
This subroutine sends a packet of data to a destination.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\item[dat] The data to be sent.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type and rank must agree on sender and receiver process; if $m$ is
|
|
not specified, size must agree as well.
|
|
\item[dst] Destination process.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value $0<= dst <= np-1$. \\
|
|
\item[m] Number of rows.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf Optional}.\\
|
|
Specified as: an integer value $0<= m <= size(dat,1)$. \\
|
|
When $dat$ is a rank 2 array, specifies the number of rows to be sent
|
|
independently of the leading dimension $size(dat,1)$; must have the
|
|
same value on sending and receiving processes.
|
|
\end{description}
|
|
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\end{description}
|
|
|
|
\subroutine{psb\_rcv}{Receive data}
|
|
|
|
\syntax{call psb\_rcv}{ictxt, dat, src, m}
|
|
|
|
This subroutine receives a packet of data to a destination.
|
|
\begin{description}
|
|
\item[\bf On Entry ]
|
|
\item[icontxt] the communication context identifying the virtual
|
|
parallel machine.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer variable.
|
|
\item[src] Source process.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer value $0<= src <= np-1$. \\
|
|
\item[m] Number of rows.\\
|
|
Scope:{\bf global}.\\
|
|
Type:{\bf Optional}.\\
|
|
Specified as: an integer value $0<= m <= size(dat,1)$. \\
|
|
When $dat$ is a rank 2 array, specifies the number of rows to be sent
|
|
independently of the leading dimension $size(dat,1)$; must have the
|
|
same value on sending and receiving processes.
|
|
\end{description}
|
|
|
|
|
|
\begin{description}
|
|
\item[\bf On Return]
|
|
\item[dat] The data to be received.\\
|
|
Scope:{\bf local}.\\
|
|
Type:{\bf required}.\\
|
|
Specified as: an integer, real or complex variable, which may be a
|
|
scalar, or a rank 1 or 2 array. \
|
|
Type and rank must agree on sender and receiver process; if $m$ is
|
|
not specified, size must agree as well.
|
|
\end{description}
|
|
|
|
|
|
|
|
|
|
|
|
%%% Local Variables:
|
|
%%% mode: latex
|
|
%%% TeX-master: "userguide"
|
|
%%% End:
|