\section{Parallel environment routines}
\label{sec:parenv}

\subroutine{psb\_init}{Initializes PSBLAS parallel environment}

\syntax{call psb\_init}{icontxt, np}

This subroutine initializes the PSBLAS parallel environment, defining
a virtual parallel machine.
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[np] Number of processes in the PSBLAS virtual parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf out}.\\
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}{icontxt, iam, np}

This subroutine returns information about  the PSBLAS parallel environment, defining
a virtual parallel machine.
\begin{description}
\item[Type:] Asynchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf out}.\\
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}.\\
Intent: {\bf out}.\\
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$;
  the only call involving \verb|icontxt| that any such process may
  execute is  to \verb|psb_exit|. 
\end{enumerate}


\subroutine{psb\_exit}{Exit from  PSBLAS parallel environment}

\syntax{call psb\_exit}{icontxt}
\syntax*{call psb\_exit}{icontxt,close}

This subroutine exits from the  PSBLAS parallel virtual  machine.
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[close] Whether to close all data structures related to the
  virtual parallel machine, besides those associated with icontxt.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: a logical  variable, default value: true.
\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 with argument \verb|icontxt| in this
  situation.
\item If the user whishes to use multiple communication contexts in the
  same program, this routine may be called multiple times to
  selectively close the contexts with \verb|close=.false.|, while on
  the last call it should be called with \verb|close=.true.| to
  shutdown in a clean way the entire parallel environment.
\end{enumerate}


\subroutine{psb\_get\_mpicomm}{Get the MPI communicator}

\syntax{call psb\_get\_mpicomm}{icontxt, icomm}

This subroutine returns the MPI communicator associated with a PSBLAS context
\begin{description}
\item[Type:] Asynchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}

\begin{description}
\item[\bf On Return]
\item[icomm] The MPI communicator associated with the  PSBLAS virtual parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
\end{description}


\subroutine{psb\_get\_rank}{Get the MPI rank}

\syntax{call psb\_get\_rank}{rank, icontxt, id}

This subroutine returns the MPI rank of the  PSBLAS process $id$
\begin{description}
\item[Type:] Asynchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[id] Identifier of a   process in the PSBLAS virtual parallel machine.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value. $0 \le id \le np-1$\
\end{description}

\begin{description}
\item[\bf On Return]
\item[rank] The MPI rank associated with the  PSBLAS process $id$.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
\end{description}




\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[Type:] Asynchronous.
\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}{icontxt}

This subroutine acts as an explicit synchronization point for  the  PSBLAS
parallel virtual  machine. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}


\subroutine{psb\_abort}{Abort a computation}

\syntax{call psb\_abort}{icontxt}

This subroutine aborts computation on the parallel virtual machine. 
\begin{description}
\item[Type:] Asynchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}





\subroutine{psb\_bcast}{Broadcast data}

\syntax{call psb\_bcast}{icontxt, dat, root}

This subroutine implements a broadcast operation based on the
underlying communication library. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] On the root process, the data to be broadcast.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
Type, rank and size must agree on all processes.
\item[root] Root process holding data to be broadcast.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
Type, rank and size must agree on all processes.
\end{description}


\subroutine{psb\_sum}{Global sum}

\syntax{call psb\_sum}{icontxt, dat, root}

This subroutine implements a sum reduction  operation based on the
underlying communication library. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global sum.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
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}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf inout}.\\
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}

\section*{Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
  value may be changed even on processes different from the final
  result destination.
\end{enumerate}



\subroutine{psb\_max}{Global maximum}

\syntax{call psb\_max}{icontxt, dat, root}

This subroutine implements a maximum valuereduction
operation based on the underlying communication library. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global maximum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer or  real 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 maximum, or $-1$ to make it available
  on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf in}.\\
Specified as: an integer or  real variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, rank and size must agree on all processes.
\end{description}


\section*{Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
  value may be changed even on processes different from the final
  result destination.
\end{enumerate}

\subroutine{psb\_min}{Global minimum}

\syntax{call psb\_min}{icontxt, dat, root}

This subroutine implements a minimum value reduction
operation based on the underlying communication library. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global minimum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer  or real 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 value, or $-1$ to make it available
  on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf inout}.\\
Specified as: an integer  or  real variable, which may be a
scalar, or a rank 1 or 2 array. \\
Type, rank and size must agree on all processes.
\end{description}


\section*{Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
  value may be changed even on processes different from the final
  result destination.
\end{enumerate}

\subroutine{psb\_amx}{Global maximum absolute value}

\syntax{call psb\_amx}{icontxt, dat, root}

This subroutine implements a maximum absolute value reduction
operation based on the underlying communication library. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global maximum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
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 value, or $-1$ to make it available
  on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf inout}.\\
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}


\section*{Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
  value may be changed even on processes different from the final
  result destination.
\end{enumerate}

\subroutine{psb\_amn}{Global minimum absolute value}

\syntax{call psb\_amn}{icontxt, dat, root}

This subroutine implements a minimum absolute value reduction
operation based on the underlying communication library. 
\begin{description}
\item[Type:] Synchronous.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global minimum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
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 value, or $-1$ to make it available
  on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf inout}.\\
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}


\section*{Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
  value may be changed even on processes different from the final
  result destination.
\end{enumerate}


\subroutine{psb\_snd}{Send data}

\syntax{call psb\_snd}{icontxt, dat, dst, m}

This subroutine sends a packet of data to a destination.
\begin{description}
\item[Type:] Synchronous: see usage notes. 
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The data to be sent.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
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}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= dst <= np-1$. \\
\item[m] Number of rows.\\
Scope: {\bf global}.\\
Type: {\bf Optional}.\\
Intent: {\bf in}.\\
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}

\section*{Notes}
\begin{enumerate}
\item This subroutine implies a synchronization, but only between the
  calling process and the destination  process $dst$.
\end{enumerate}


\subroutine{psb\_rcv}{Receive data}

\syntax{call psb\_rcv}{icontxt, dat, src, m}

This subroutine receives a packet of data to a destination.
\begin{description}
\item[Type:] Synchronous: see usage notes.
\item[\bf  On Entry ]
\item[icontxt] the communication context identifying the virtual
  parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[src] Source process.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= src <= np-1$. \\
\item[m] Number of rows.\\
Scope: {\bf global}.\\
Type: {\bf Optional}.\\
Intent: {\bf in}.\\
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}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
Type and  rank must agree on sender and receiver process; if $m$ is
not specified, size must agree as well. 
\end{description}

\section*{Notes}
\begin{enumerate}
\item This subroutine implies a synchronization, but only between the
  calling process and the source  process $src$.
\end{enumerate}