\section{Data management and initialization routines} % %% psb_alloc %% % \subroutine{psb\_alloc}{Allocates a dense matrix} \syntax{call psb\_alloc}{m, n, x, desc\_a, info, js} \begin{description} \item[\bf On Entry] \item[m] The number of rows of the dense matrix to be allocated.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Specified as: Integer scalar. \item[n] The number of columns of the dense matrix to be allocated.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Specified as: Integer scalar. \item[desc\_a] The communication descriptor.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Specified as: a variable of type \descdata.\\ \item[js] The starting column.\\ Scope: {\bf local} \\ Type: {\bf optional}\\ Specified as: Integer scalar. \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 one or two dimensional array.\\ \item[info] Error code. Scope: {\bf local} \\ Type: {\bf required}\\ Specified as: Integer scalar. \end{description} % %% psb_asb %% % \subroutine{psb\_asb}{Assembly a dense matrix} \syntax{call psb\_asb}{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 one or two dimensional array.\\ \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Specified as: Integer scalar.\\ \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_descprt %% % \subroutine{psb\_descprt}{Prints a descriptor} \syntax{call psb\_descprt}{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_free %% % \subroutine{psb\_free}{Frees a dense matrix} \syntax{call psb\_free}{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 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_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_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, is, js} \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[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required}\\ \end{description} % %% psb_dscall %% % \subroutine{psb\_dscall}{Allocates a communication descriptor} \syntax{call psb\_dscall}{m, n, parts, icontxt, desc\_a, info} \syntax*{call psb\_dscall}{m, v, icontxt, desc\_a, info, flag} \begin{description} \item[\bf 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. \item[parts] the subroutine that defines the partitioning scheme.\\ Scope:{\bf global}.\\ Type:{\bf required}.\\ Specified as: a subroutine as described in ??? \item[icontxt] the communication context.\\ Scope:{\bf global}.\\ Type:{\bf required}.\\ Specified as: an integer value. \end{description} \begin{description} \item[\bf On Return] \item[desc\_a] the communication descriptor.\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ 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_dscasb %% % \subroutine{psb\_dscasb}{Communication descriptor assembly routine} \syntax{call psb\_dscasb}{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} % %% psb_dsccpy %% % \subroutine{psb\_dsccpy}{Copies a communication descriptor} \syntax{call psb\_dsccpy}{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_dscfree %% % \subroutine{psb\_dscfree}{Frees a communication descriptor} \syntax{call psb\_dscfree}{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_dscins %% % \subroutine{psb\_dscins}{Comunnication descriptor insert routine} \syntax{call psb\_dscins}{nz, ia, ja, desc\_a, info, is, js} \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 communication descriptor to be freed.\\ 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_dscren %% % \subroutine{psb\_dscren}{Applies a renumeration to a communication descriptor} \syntax{call psb\_dscren}{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_spalloc %% % \subroutine{psb\_spalloc}{Allocates a sparse matrix} \syntax{call psb\_spalloc}{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 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} % %% psb_spasb %% % \subroutine{psb\_spasb}{Sparse matrix assembly routine} \syntax{call psb\_spasb}{a, desc\_a, info, afmt, up, dup} \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. If not specified 'CSR' will be assumed. \item[up] ???.\\ Scope: {\bf global}.\\ Type: {\bf optional}.\\ Specified as: . \item[dup] ???.\\ Scope: {\bf global}.\\ Type: {\bf optional}.\\ Specified as: \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} % %% 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_ins %% % \subroutine{psb\_ins}{Sparse matrix insertion routine} \syntax{call psb\_ins}{m, n, x, ix, jx, blck, desc\_a, info, iblck, jblck} \begin{description} \item[\bf On Entry] \item[m] rows number of submatrix belonging to blck to be inserted..\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ Specified as: an integer value. \item[n] columns number of submatrix belonging to blck to be inserted.\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ Specified as: an integer value. \item[ix] x global-row corresponding to position at which blck submatrix must be inserted.\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ Specified as: an integer value. \item[jx] x global-col corresponding to position at which blck submatrix must be inserted.\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ Specified as: an integer value. \item[blck] the dense submatrix to be inserted.\\ 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 structured data of type \descdata. \item[iblck] first row of submatrix belonging to blck to be inserted.\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ Specified as: an integer value. \item[jblck] first column of submatrix belonging to blck to be inserted.\\ Scope:{\bf local}.\\ Type:{\bf required}.\\ Specified as: an integer value. \end{description} \begin{description} \item[\bf On Return] \item[x] the output dense matrix.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Specified as: a one or two dimensional array.\\ \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} \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. \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_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_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: