psblas3/docs/pdf/toolsrout.tex

\section{Data management and environment handling  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\_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}



%
%%   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] 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
  multiple data allocations. 
\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}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: