\section{Computational routines} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % DENSE MATRIX SUM % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_geaxpby}{General Dense Matrix Sum} This subroutine is an interface to the computational kernel for dense matrix sum: \[ y \leftarrow \alpha\> x+ \beta y \] %% where: %% \begin{description} %% \item[$x$] represents the global dense submatrix $x_{:, :1}$ %% \item[$y$] represents the global dense submatrix $y_{:, :}$ %% \end{description} \syntax{call psb\_geaxpby}{alpha, x, beta, y, desc\_a, info} %% \syntax*{call psb\_geaxpby}{alpha, x, beta, y, desc\_a, info, n, jx, jy} %( calculating y <- alpha*x+beta*y ) \begin{table}[h] \begin{center} \begin{tabular}{ll} \hline $x$, $y$, $\alpha$, $\beta$ & {\bf Subroutine}\\ \hline Short Precision Real & psb\_geaxpby \\ Long Precision Real & psb\_geaxpby \\ Short Precision Complex & psb\_geaxpby \\ Long Precision Complex & psb\_geaxpby \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90axpby}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[alpha] the scalar $\alpha$.\\ Scope: {\bf global} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a number of the data type indicated in Table~\ref{tab:f90axpby}. \item[x] the local portion of global dense matrix $x$.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90axpby}. The rank of $x$ must be the same of $y$. \item[beta] the scalar $\beta$.\\ Scope: {\bf global} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a number of the data type indicated in Table~\ref{tab:f90axpby}. \item[y] the local portion of the global dense matrix $y$. \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf inout}.\\ Specified as: a rank one or two array containing numbers of the type indicated in Table~\ref{tab:f90axpby}. The rank of $y$ must be the same of $x$. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. %% \item[n] number of columns in dense submatrices $x$ and $y$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ and $y$ are of rank 2.\\ %% Default: \verb|min(size(x,2),size(y,2))|.\\ %% Specified as: an integer variable $n\ge 0$. %% \item[jx] the column index of the global dense matrix $x$, %% identifying the first column of the submatrix $x$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ and $y$ are of rank 2.\\ %% Default: $jx = 1$.\\ %% Specified as: an integer variable $jx\ge 1$. %% \item[jy] the column index of the global dense matrix $y$, %% identifying the first column of the submatrix $y$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ and $y$ are of rank 2.\\ %% Default: $jy = 1$.\\ %% Specified as: an integer variable $jy\ge 1$. \end{description} \begin{description} \item[\bf On Return] \item[y] the local portion of result submatrix $y$.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf inout}.\\ Specified as: a rank one or two array containing numbers of the type indicated in Table~\ref{tab:f90axpby}. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % F90DOT PRODUCT % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_gedot}{Dot Product} This function computes dot product between two vectors $x$ and $y$.\\ If $x$ and $y$ are real vectors it computes dot-product as: \[dot \leftarrow x^T y\] Else if $x$ and $y$ are complex vectors then it computes dot-product as: \[dot \leftarrow x^H y\] %% where: %% \begin{description} %% \item[$x$] represents the global subvector $x_{:,jx}$ %% \item[$y$] represents the global subvector $y_{:,jy}$ %% \end{description} \syntax{psb\_gedot}{x, y, desc\_a, info} %% \syntax*{psb\_gedot}{x, y, desc\_a, info, jx, jy} \begin{table}[h] \begin{center} \begin{tabular}{ll} \hline $dot$, $x$, $y$ & {\bf Function}\\ \hline Short Precision Real & psb\_gedot \\ Long Precision Real & psb\_gedot \\ Short Precision Complex & psb\_gedot \\ Long Precision Complex & psb\_gedot \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90dot}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$.\\ %% This function computes the location of the first element of %% local subarray used, based on $jx$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: an array of rank one or two containing numbers of type specified in Table~\ref{tab:f90dot}. The rank of $x$ must be the same of $y$. \item[y] the local portion of global dense matrix $y$. \\ %% This function computes the location of the first element of %% local subarray used, based on $iy, jy$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: an array of rank one or two containing numbers of type specified in Table~\ref{tab:f90dot}. The rank of $y$ must be the same of $x$. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. %% \item[jx] the column index of global dense matrix $x$, %% identifying the column of subvector $x$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ and $y$ are of rank 2.\\ %% Default: $jx = 1$.\\ %% \item[jy] the column index of global dense matrix $y$, %% identifying the column of subvector $y$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ and $y$ are of rank 2.\\ %% Default: $jy = 1$.\\ %% Specified as: an integer variable $jy\ge 1$. \item[\bf On Return] \item[Function value] is the dot product of subvectors $x$ and $y$.\\ Scope: {\bf global} \\ Specified as: a number of the data type indicated in Table~\ref{tab:f90dot}. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % F90DOT PRODUCT % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_gedots}{Generalized Dot Product} This subroutine computes a series of dot products among the columns of two dense matrices $x$ and $y$: \[ res(i) \leftarrow x(:,i)^T y(:,i)\] If the matrices are complex, then the usual convention applies, i.e. the conjugate transpose of $x$ is used. If $x$ and $y$ are of rank one, then $res$ is a scalar, else it is a rank one array. \syntax{call psb\_gedots}{res, x, y, desc\_a, info} \begin{table}[h] \begin{center} \begin{tabular}{ll} \hline $res$, $x$, $y$ & {\bf Subroutine}\\ \hline Short Precision Real & psb\_gedots \\ Long Precision Real & psb\_gedots \\ Short Precision Complex & psb\_gedots \\ Long Precision Complex & psb\_gedots \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90mdot}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$. \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: an array of rank one or two containing numbers of type specified in Table~\ref{tab:f90mdot}. The rank of $x$ must be the same of $y$. \item[y] the local portion of global dense matrix $y$. \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: an array of rank one or two containing numbers of type specified in Table~\ref{tab:f90mdot}. The rank of $y$ must be the same of $x$. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[\bf On Return] \item[res] is the dot product of subvectors $x$ and $y$.\\ Scope: {\bf global} \\ Intent: {\bf out}.\\ Specified as: a number or a rank-one array of the data type indicated in Table~\ref{tab:f90dot}. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % VECTOR INFINITY-NORM % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_geamax}{Infinity-Norm of Vector} This function computes the infinity-norm of a vector $x$.\\ If $x$ is a real vector it computes infinity norm as: \[ amax \leftarrow \max_i |x_i|\] else if $x$ is a complex vector then it computes infinity-norm as: \[ amax \leftarrow \max_i {(|re(x_i)| + |im(x_i)|)}\] %% where: %% \begin{description} %% \item[$x$] represents the global subvector $x_{:,jx}$ %% \end{description} \syntax{psb\_geamax}{x, desc\_a, info} %% \syntax*{psb\_geamax}{x, desc\_a, info, jx} \begin{table}[h] \begin{center} \begin{tabular}{lll} \hline $amax$ & $x$ & {\bf Function}\\ \hline Short Precision Real& Short Precision Real & psb\_geamax \\ Long Precision Real&Long Precision Real & psb\_geamax \\ Short Precision Real&Short Precision Complex & psb\_geamax \\ Long Precision Real&Long Precision Complex & psb\_geamax \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90amax}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$. %% This function computes the location of the first element of %% local subarray used, based on $jx$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90amax}. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. %% \item[jx] the column index of global dense matrix $x$, %% identifying the column of subvector $x$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ is of rank 2.\\ %% Default: $jx = 1$\\ %% Specified as: an integer variable $jx\ge 1$. \item[\bf On Return] \item[Function value] is the infinity norm of subvector $x$.\\ Scope: {\bf global} \\ Specified as: a long precision real number. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % Infinity norm % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_geamaxs}{Generalized Infinity Norm} This subroutine computes a series of infinity norms on the columns of a dense matrix $x$: \[ res(i) \leftarrow \max_k |x(k,i)| \] \syntax{call psb\_geamaxs}{res, x, desc\_a, info} \begin{table}[h] \begin{center} \begin{tabular}{lll} \hline $res$& $x$& {\bf Subroutine}\\ \hline Short Precision Real &Short Precision Real & psb\_geamaxs\\ Long Precision Real &Long Precision Real & psb\_geamaxs\\ Short Precision Real &Short Precision Complex & psb\_geamaxs\\ Long Precision Real &Long Precision Complex & psb\_geamaxs\\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90mamax}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$. \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90mamax}. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[\bf On Return] \item[res] is the infinity norm of the columns of $x$.\\ Scope: {\bf global} \\ Intent: {\bf out}.\\ Specified as: a number or a rank-one array of long precision real numbers. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % 1-NORM OF A VECTOR % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_geasum}{1-Norm of Vector} This function computes the 1-norm of a vector $x$.\\ If $x$ is a real vector it computes 1-norm as: \[ asum \leftarrow \|x_i\|\] else if $x$ is a vector then it computes 1-norm as: \[ asum \leftarrow \|re(x)\|_1 + \|im(x)\|_1\] \syntax{psb\_geasum}{x, desc\_a, info} \begin{table}[h] \begin{center} \begin{tabular}{lll} \hline $asum$ & $x$ & {\bf Function}\\ \hline Short Precision Real&Short Precision Real & psb\_geasum \\ Long Precision Real&Long Precision Real & psb\_geasum \\ Short Precision Real&Short Precision Complex & psb\_geasum \\ Long Precision Real&Long Precision Complex & psb\_geasum \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90asum}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$. %% This function computes the location of the first element of %% local subarray used, based on the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90asum}. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[\bf On Return] \item[Function value] is the 1-norm of vector $x$.\\ Scope: {\bf global} \\ Specified as: a long precision real number. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} \subroutine{psb\_geasums}{Generalized 1-Norm of Vector} This subroutine computes a series of 1-norms on the columns of a dense matrix $x$: \[ res(i) \leftarrow \max_k |x(k,i)| \] This function computes the 1-norm of a vector $x$.\\ If $x$ is a real vector it computes 1-norm as: \[ res(i) \leftarrow \|x_i\|\] else if $x$ is a complex vector then it computes 1-norm as: \[ res(i) \leftarrow \|re(x)\|_1 + \|im(x)\|_1\] \syntax{call psb\_geasums}{res, x, desc\_a, info} \begin{table}[h] \begin{center} \begin{tabular}{lll} \hline $res$ & $x$ & {\bf Subroutine}\\ \hline Short Precision Real&Short Precision Real & psb\_geasums \\ Long Precision Real&Long Precision Real & psb\_geasums \\ Short Precision Real&Short Precision Complex & psb\_geasums \\ Long Precision Real&Long Precision Complex & psb\_geasums \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90asums}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$. %% This function computes the location of the first element of %% local subarray used, based on the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90asums}. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[\bf On Return] \item[res] contains the 1-norm of (the columns of) $x$.\\ Scope: {\bf global} \\ Intent: {\bf out}.\\ Short as: a long precision real number. Specified as: a long precision real number. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % 2-NORM OF A VECTOR % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine {psb\_genrm2}{2-Norm of Vector} This function computes the 2-norm of a vector $x$.\\ If $x$ is a double precision real vector it computes 2-norm as: \[ nrm2 \leftarrow \sqrt{x^T x}\] else if $x$ is double precision complex vector then it computes 2-norm as: \[ nrm2 \leftarrow \sqrt{x^H x}\] %% where: %% \begin{description} %% \item[$x$] represents the global subvector $x_{:,jx}$ %% \end{description} \begin{table}[h] \begin{center} \begin{tabular}{lll} \hline $nrm2$ & $x$ & {\bf Function}\\ \hline Short Precision Real&Short Precision Real & psb\_genrm2 \\ Long Precision Real&Long Precision Real & psb\_genrm2 \\ Short Precision Real&Short Precision Complex & psb\_genrm2 \\ Long Precision Real&Long Precision Complex & psb\_genrm2 \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90nrm2}} \end{table} \syntax{psb\_genrm2}{x, desc\_a, info} %% \syntax*{psb\_genrm2}{x, desc\_a, info, jx} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$.%% This function computes the location of the first element of %% local subarray used, based on $jx$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90nrm2}. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. %% \item[jx] the column index of global dense matrix $x$, %% identifying the column of subvector $x$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ is of rank 2.\\ %% Default: $jx = 1$\\ %% Specified as: an integer variable $jx\ge 1$. \item[\bf On Return] \item[Function Value] is the 2-norm of subvector $x$.\\ Scope: {\bf global} \\ Type: {\bf required} \\ Specified as: a long precision real number. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} \subroutine{psb\_genrm2s}{Generalized 1-Norm of Vector} This subroutine computes a series of 1-norms on the columns of a dense matrix $x$: \[ res(i) \leftarrow \max_k |x(k,i)| \] This function computes the 1-norm of a vector $x$.\\ If $x$ is a real vector it computes 1-norm as: \[ res(i) \leftarrow \sqrt{x^T x}\] else if $x$ is a complex vector then it computes 1-norm as: \[ res(i) \leftarrow \sqrt{x^H x}\] \syntax{call psb\_genrm2s}{res, x, desc\_a, info} \begin{table}[h] \begin{center} \begin{tabular}{lll} \hline $res$ & $x$ & {\bf Subroutine}\\ \hline Short Precision Real&Short Precision Real & psb\_genrm2s \\ Long Precision Real&Long Precision Real & psb\_genrm2s \\ Short Precision Real&Short Precision Complex & psb\_genrm2s \\ Long Precision Real&Long Precision Complex & psb\_genrm2s \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90nrm2s}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[x] the local portion of global dense matrix $x$. %% This function computes the location of the first element of %% local subarray used, based on the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90nrm2s}. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[\bf On Return] \item[res] contains the 1-norm of (the columns of) $x$.\\ Scope: {\bf global} \\ Intent: {\bf out}.\\ Specified as: a long precision real number. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % INFINITY-NORM OF A MATRIX % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_spnrmi}{Infinity Norm of Sparse Matrix} This function computes the infinity-norm of a matrix $A$:\\ \[ nrmi \leftarrow \|A\|_\infty \] where: \begin{description} \item[$A$] represents the global matrix $A$ \end{description} \begin{table}[h] \begin{center} \begin{tabular}{ll} \hline $A$ & {\bf Function}\\ \hline Short Precision Real & psb\_spnrmi \\ Long Precision Real & psb\_spnrmi \\ Short Precision Complex & psb\_spnrmi \\ Long Precision Complex & psb\_spnrmi \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90nrmi}} \end{table} \syntax{psb\_spnrmi}{A, desc\_a, info} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[a] the local portion of the global sparse matrix $A$. \\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \spdata. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[\bf On Return] \item[Function value] is the infinity-norm of sparse submatrix $A$.\\ Scope: {\bf global} \\ Specified as: a long precision real number. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % SPARSE MATRIX by DENSE MATRIX PRODUCT % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_spmm}{Sparse Matrix by Dense Matrix Product} This subroutine computes the Sparse Matrix by Dense Matrix Product: \begin{equation} y \leftarrow \alpha P_r A P_c x + \beta y \label{eq:f90spmm_no_tra} \end{equation} \begin{equation} y \leftarrow \alpha P_r A^T P_c x + \beta y \label{eq:f90spmm_tra} \end{equation} \begin{equation} y \leftarrow \alpha P_r A^H P_c x + \beta y \label{eq:f90spmm_con} \end{equation} where: \begin{description} \item[$x$] is the global dense submatrix $x_{:, :}$ \item[$y$] is the global dense submatrix $y_{:, :}$ \item[$A$] is the global sparse submatrix $A$ \item[$P_r, P_c$] are the permutation matrices. \end{description} \begin{table}[h] \begin{center} \begin{tabular}{ll} \hline $A$, $x$, $y$, $\alpha$, $\beta$ & {\bf Subroutine}\\ \hline Short Precision Real & psb\_spmm \\ Long Precision Real & psb\_spmm \\ Short Precision Complex & psb\_spmm \\ Long Precision Complex & psb\_spmm \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90spmm}} \end{table} \syntax{call psb\_spmm}{alpha, a, x, beta, y, desc\_a, info} \syntax*{call psb\_spmm}{alpha, a, x, beta, y,desc\_a, info, trans, work} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[alpha] the scalar $\alpha$.\\ Scope: {\bf global} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a number of the data type indicated in Table~\ref{tab:f90spmm}. \item[a] the local portion of the sparse matrix $A$. \\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \spdata. \item[x] the local portion of global dense matrix $x$. %% This subroutine computes the location of the first element of %% local subarray used, based on $jx$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90spmm}. The rank of $x$ must be the same of $y$. \item[beta] the scalar $\beta$.\\ Scope: {\bf global} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a number of the data type indicated in Table~\ref{tab:f90spmm}. \item[y] the local portion of global dense matrix $y$. %% This subroutine computes the location of the first element of %% local subarray used, based on $jy$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf inout}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90spmm}. The rank of $y$ must be the same of $x$. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[trans] indicate what kind of operation to perform. \begin{description} \item[trans = N] the operation is specified by equation \ref{eq:f90spmm_no_tra} \item[trans = T] the operation is specified by equation \ref{eq:f90spmm_tra} \item[trans = C] the operation is specified by equation \ref{eq:f90spmm_con} \end{description} Scope: {\bf global} \\ Type: {\bf optional}\\ Intent: {\bf in}.\\ Default: $trans = N$\\ Specified as: a character variable. %% \item[k] number of columns in dense submatrices $x$ and $y$. \\ %% Scope: {\bf global} \\ %% Type: {\bf optional}\\ %% Default: \verb|min(size(x,2)-jx+1,size(y,2)-jy+1)|\\ %% Specified as: an integer variable $ k \ge 1$. %% \item[jx] the column index of global dense matrix $x$, %% identifying the column of subvector $x$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $x$ is of rank 2.\\ %% Default: $iy = 1$\\ %% Specified as: an integer variable $jx\ge 1$. %% \item[jy] the column index of global dense matrix $y$, %% identifying the column of subvector $y$.\\ %% Scope: {\bf global} \\ %% Type: {\bf optional}; can only be present if $y$ is of rank 2.\\ %% Default: $jy = 1$\\ %% Specified as: an integer variable $jy\ge 1$. \item[work] work array.\\ Scope: {\bf local} \\ Type: {\bf optional}\\ Intent: {\bf inout}.\\ Specified as: a rank one array of the same type of $x$ and $y$ with the TARGET attribute. \item[\bf On Return] \item[y] the local portion of result submatrix $y$.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf inout}.\\ Specified as: an array of rank one or two containing numbers of type specified in Table~\ref{tab:f90spmm}. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % % TRIANGULAR SYSTEM SOLVE % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subroutine{psb\_spsm}{Triangular System Solve} This subroutine computes the Triangular System Solve: \begin{eqnarray*} y &\leftarrow& \alpha P_r T^{-1} P_c x + \beta y\\ y &\leftarrow& \alpha D P_r T^{-1} P_c x + \beta y\\ y &\leftarrow& \alpha P_r T^{-1} P_c D x + \beta y\\ y &\leftarrow& \alpha P_r T^{-T} P_c x + \beta y\\ y &\leftarrow& \alpha D P_r T^{-T} P_c x + \beta y\\ y &\leftarrow& \alpha P_r T^{-T} P_c D x + \beta y\\ y &\leftarrow& \alpha P_r T^{-H} P_c x + \beta y\\ y &\leftarrow& \alpha D P_r T^{-H} P_c x + \beta y\\ y &\leftarrow& \alpha P_r T^{-H} P_c D x + \beta y\\ \end{eqnarray*} where: \begin{description} \item[$x$] is the global dense submatrix $x_{:, :}$ \item[$y$] is the global dense submatrix $y_{:, :}$ \item[$T$] is the global sparse block triangular submatrix $T$ \item[$D$] is the scaling diagonal matrix. \item[$P_r, P_c$] are the permutation matrices. \end{description} \syntax{call psb\_spsm}{alpha, t, x, beta, y, desc\_a, info} \syntax*{call psb\_spsm}{alpha, t, x, beta, y, desc\_a, info, trans, unit, choice, diag, work} \begin{table}[h] \begin{center} \begin{tabular}{ll} \hline $T$, $x$, $y$, $D$, $\alpha$, $\beta$ & {\bf Subroutine}\\ \hline Short Precision Real & psb\_spsm \\ Long Precision Real & psb\_spsm \\ Short Precision Complex & psb\_spsm \\ Long Precision Complex & psb\_spsm \\ \hline \end{tabular} \end{center} \caption{Data types\label{tab:f90spsm}} \end{table} \begin{description} \item[Type:] Synchronous. \item[\bf On Entry] \item[alpha] the scalar $\alpha$.\\ Scope: {\bf global} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a number of the data type indicated in Table~\ref{tab:f90spsm}. \item[t] the global portion of the sparse matrix $T$. \\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data type specified in \S~\ref{sec:datastruct}. \item[x] the local portion of global dense matrix $x$. %% This subroutine computes the location of the first element of %% local subarray used, based on $jx$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90spsm}. The rank of $x$ must be the same of $y$. \item[beta] the scalar $\beta$.\\ Scope: {\bf global} \\ Type: {\bf required} \\ Intent: {\bf in}.\\ Specified as: a number of the data type indicated in Table~\ref{tab:f90spsm}. \item[y] the local portion of global dense matrix $y$. %% This subroutine computes the location of the first element of %% local subarray used, based on $jy$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf inout}.\\ Specified as: a rank one or two array containing numbers of type specified in Table~\ref{tab:f90spsm}. The rank of $y$ must be the same of $x$. \item[desc\_a] contains data structures for communications.\\ Scope: {\bf local} \\ Type: {\bf required}\\ Intent: {\bf in}.\\ Specified as: a structured data of type \descdata. \item[trans] specify with {\em unitd} the operation to perform. \begin{description} \item[trans = 'N'] the operation is with no transposed matrix \item[trans = 'T'] the operation is with transposed matrix. \item[trans = 'C'] the operation is with conjugate transposed matrix. \end{description} Scope: {\bf global} \\ Type: {\bf optional}\\ Intent: {\bf in}.\\ Default: $trans = N$\\ Specified as: a character variable. \item[unitd] specify with {\em trans} the operation to perform. \begin{description} \item[unitd = 'U'] the operation is with no scaling \item[unitd = 'L'] the operation is with left scaling \item[unitd = 'R'] the operation is with right scaling. \end{description} Scope: {\bf global} \\ Type: {\bf optional}\\ Intent: {\bf in}.\\ Default: $unitd = U$\\ Specified as: a character variable. \item[choice] specifies the update of overlap elements to be performed on exit: \begin{description} \item \verb|psb_none_| \item \verb|psb_sum_| \item \verb|psb_avg_| \item \verb|psb_square_root_| \end{description} Scope: {\bf global} \\ Type: {\bf optional}\\ Intent: {\bf in}.\\ Default: \verb|psb_avg_|\\ Specified as: an integer variable. \item[diag] the diagonal scaling matrix.\\ Scope: {\bf local} \\ Type: {\bf optional}\\ Intent: {\bf in}.\\ Default: $diag(1) = 1 (no scaling)$\\ Specified as: a rank one array containing numbers of the type indicated in Table~\ref{tab:f90spsm}. \item[work] a work array. \\ Scope: {\bf local} \\ Type: {\bf optional}\\ Intent: {\bf inout}.\\ Specified as: a rank one array of the same type of $x$ with the TARGET attribute. \item[\bf On Return] \item[y] the local portion of global dense matrix $y$. %% This subroutine computes the location of the first element of %% local subarray used, based on $jy$ and the field $matrix\_data$ of $desc\_a$ . \\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf inout}.\\ Specified as: an array of rank one or two containing numbers of type specified in Table~\ref{tab:f90spsm}. \item[info] Error code.\\ Scope: {\bf local} \\ Type: {\bf required} \\ Intent: {\bf out}.\\ An integer value; 0 means no error has been detected. \end{description} %%% Local Variables: %%% mode: latex %%% TeX-master: "userguide" %%% End: