|
|
|
|
@ -1,149 +1,6 @@
|
|
|
|
|
\section{Data management, environment handling and auxiliary
|
|
|
|
|
communication routines}
|
|
|
|
|
\section{Data management 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 %%
|
|
|
|
|
@ -1004,230 +861,6 @@ 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}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Salvatore Filippone
19 years ago