fdurastante/psblas3
1
0
Fork 0
mirror of https://github.com/sfilippone/psblas3.git synced 2026-10-06 22:55:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Modified interface to GEALL, GEINS et al.

Browse Source 
Changed ITRACE behaviour in solver routines.
Updated documentation.
This commit is contained in:
Salvatore Filippone
2006-04-24 12:02:04 +00:00
parent 41d7626b66
commit d003f55d95
48 changed files with 18464 additions and 17667 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pdf/commrout.tex
+11 -19
View File
@@ -39,7 +39,7 @@ Long Precision Complex & psb\_halo \\
\item[x] global dense matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a rank one or two array with the POINTER attribute
Specified as: a rank one or two array with the TARGET attribute
containing numbers of type specified in
Table~\ref{tab:f90halo}.
\item[desc\_a] contains data structures for communications.\\
@@ -61,7 +61,7 @@ POINTER attribute.
\item[x] global dense result matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Returned as: a rank one or two array with the POINTER attribute
Returned as: a rank one or two array
containing numbers of type specified in
Table~\ref{tab:f90halo}.
\item[info] the local portion of result submatrix $y$.\\
@@ -104,37 +104,29 @@ Long Precision Complex & psb\_ovrl \\
\end{table}
\syntax{CALL psb\_ovrl}{x, desc\_a, info}
\syntax*{CALL psb\_ovrl}{x, desc\_a, info, choice=choice,
update\_type=update\_type, work=work}
\syntax*{CALL psb\_ovrl}{x, desc\_a, info, update=update\_type, work=work}
\begin{description}
\item[\bf On Entry]
\item[x] global dense matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a rank one or two array with the POINTER attribute
Specified as: a rank one or two array
containing numbers of type specified in
Table~\ref{tab:f90ovrl}.
\item[desc\_a] contains data structures for communications.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Specified as: a structured data of type \descdata.
\item[choice] specify if exchange overlap elements.
\item[update] Update operator. \\
\begin{description}
\item[choice = .true.] exchange overlap elements, i.e. apply operator
$P^{T}$;
\item[choice = .false.] don't exchange overlap elements
\item[update = psb\_none\_] Do nothing;
\item[update = psb\_add\_] Sum overlap entries;
\item[update = psb\_avg\_] Average overlap entries;
%% \item[update = psb\_square\_root\_] square root update $\sqrt{P_a}$;
\end{description}
Scope: {\bf global} \\
Type: {\bf optional} \\
Default: $choice = .true. $\\
Specified as: a logical variable.
\begin{description}
\item[update\_type = 1] normal update $P_a$;
\item[update\_type = 2] square root update $\sqrt{P_a}$;
\end{description}
Scope: {\bf global} \\
Default: $update\_type = .true. $\\
Default: $update\_type = psb\_avg\_ $\\
Scope: {\bf global} \\
Specified as: a integer variable.
\item[work] the work array. \\
@@ -146,7 +138,7 @@ Specified as: a one dimensional array of the same type of $x$.
\item[x] global dense result matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a pointer to array of rank one or two
Specified as: an array of rank one or two
containing numbers of type specified in
Table~\ref{tab:f90ovrl}.
\item[info] the local portion of result submatrix $y$.\\
docs/pdf/datastruct.tex
+93 -9
View File
@@ -21,7 +21,7 @@ Fields contained in Sparse matrix structures are:
\item[{\bf aspk}] Contains values of the local distributed sparse
matrix.\\
Specified as: a pointer to an array of rank one of type corresponding
to matrix entries type .
to matrix entries type.
\item[{\bf ia1}] Holds integer information on distributed sparse
matrix. Actual information will depend on data format used.\\
Specified as: a pointer to an integer array of rank one.
@@ -30,7 +30,7 @@ matrix. Actual information will depend on data format used.\\
Specified as: a pointer to an integer array of rank one.
\item[{\bf infoa}] On entry can hold auxiliary information on distributed sparse
matrix. Actual information will depend on data format used.\\
Specified as: integer array of length 10.
Specified as: integer array of length \verb|psb_ifasize_|.
\item[{\bf fida}] Defines the format of the distributed sparse matrix.\\
Specified as: a string of length 5
\item[{\bf descra}] Describe the characteristic of the distributed sparse matrix.\\
@@ -61,7 +61,7 @@ type psb_dspmat_type
integer :: m, k
character :: fida(5)
character :: descra(10)
integer :: infoa(10)
integer :: infoa(psb_ifa_size_)
real(kind(1.d0)), pointer :: aspk(:)
integer, pointer :: ia1(:), ia2(:), pr(:), pl(:)
end type psb_dspmat_type
@@ -72,7 +72,9 @@ end type psb_dspmat_type
\begin{center}
\fbox{\TheSbox}
\end{center}
\caption{\label{fig:spmattype}The PSBLAS defined data type that contains a sparse matrix.}
\caption{\label{fig:spmattype}
The PSBLAS defined data type that
contains a sparse matrix.}
\end{figure}
The following two cases are among the most commonly used:
@@ -98,6 +100,36 @@ column index are stored into \verb|apsk(j)|, \verb|ia1(j)| and
\verb|ia2(j)| respectively.
\end{enumerate}
\end{description}
A sparse matrix has an associated state, which can take the following
values:
\begin{description}
\item[Build:] State entered after the first allocation, and before the
first assembly; in this state it is possible to add nonzero entries.
\item[Assembled:] State entered after the assembly; computations using
the sparse matrix, such as matrix-vector products, are only possible
in this state;
\item[Update:] State entered after a reinitalization; this is used to
handle applications in which the same sparsity pattern is used
multiple times with different coefficients. In this state it is only
possible to enter coefficients for already existing nonzero entries.
\end{description}
\subsubsection{Named Constants}
\label{sec:sp_constants}
\begin{description}
\item[psb\_nztotreq\_] Request to fetch the total number of nonzeroes
stored in a sparse matrix
\item[psb\_nzrowreq\_] Request to fetch the number of nonzeroes in a
given row in a sparse matrix
\item[psb\_dupl\_ovwrt\_] Duplicate coefficients should be overwritten
(i.e. ignore duplications)
\item[psb\_dupl\_add\_] Duplicate coefficients should be added;
\item[psb\_dupl\_err\_] Duplicate coefficients should trigger an error conditino
\item[psb\_upd\_dflt\_] Default update strategy for matrix coefficients;
\item[psb\_upd\_srch\_] Update strategy based on search into the data structure;
\item[psb\_upd\_perm\_] Update strategy based on additional
permutation data (see tools routine description).
\end{description}
\subsection{Descriptor data structure}
@@ -196,6 +228,41 @@ end type psb_desc_type
contains the communication descriptor.}
\end{figure}
A communication descriptor associated with a sparse matrix has a
state, which can take the following values:
\begin{description}
\item[Build:] State entered after the first allocation, and before the
first assembly; in this state it is possible to add communication
requirements among different processes.
\item[Assembled:] State entered after the assembly; computations using
the associated sparse matrix, such as matrix-vector products, are
only possible in this state.
\end{description}
\subsubsection{Named Constants}
\label{sec:cd_constants}
\begin{description}
\item[psb\_none\_] Generic no-op;
\item[psb\_nohalo\_] Do not fetch halo elements;
\item[psb\_halo\_] Fetch halo elements from neighbouring processes;
\item[psb\_sum\_] Sum overlapped elements
\item[psb\_avg\_] Average overlapped elements
%% \item[psb\_square\_root\_] Update with the square root of the average
%% of overlapped elements;
\item[psb\_dec\_type\_] Entry holding decomposition type (in \verb|desc_a%matrix_data|)
\item[psb\_m\_] Entry holding total number of rows
\item[psb\_n\_] Entry holding total number of columns
\item[ psb\_n\_row\_] Entry holding the number of rows stored in the
current process
\item[psb\_n\_col\_] Entry holding the number of columns stored in the
current process
\item[psb\_ctxt\_] Entry holding a copy of the BLACS communication context
\item[psb\_desc\_asb\_] State of the descriptor: assembled,
i.e. suitable for computational tasks.
\item[psb\_desc\_bld\_] State of the descriptor: build, must be
assembled before computational use.
\end{description}
\subsection{Preconditioner data structure}
\label{sec:prec}
PSBLAS-2.0 offers the possibility to use many different types of
@@ -203,8 +270,9 @@ preconditioning schemes. Besides the simple well known preconditioners
like Diagonal Scaling or Block Jacobi (with ILU(0) incomplete
factorization) also more complex preconditioning methods are
implemented like the Additive Schwarz and Two-Level ones. A
preconditioner is held in the \hypertarget{precdata}{{\tt psb\_prec\_type}} data structure
which depends on the \verb|psb_base_prec| reported in
preconditioner is held in the \hypertarget{precdata}{{\tt
psb\_prec\_type}} data structure which depends on the
\verb|psb_base_prec| reported in
figure~\ref{fig:prectype}. The \verb|psb_base_prec|
data type may contain a simple preconditioning matrix with the
associated communication descriptor which may be different than the
@@ -216,7 +284,7 @@ The user can choose the type of preconditioner to be used by means of
the \verb|psb_precset| subroutine; once the type of preconditioning
method is specified, along with all the parameters that characterize
it, the preconditioner data structure can be built using the
\verb|psb_precbuild| subroutine.
\verb|psb_precbld| subroutine.
This data structure wants to be flexible enough to easily allow the
implementation of new kind of preconditioners. The values contained in
the \verb|iprcparm| and \verb|dprcparm| define tha type of
@@ -257,8 +325,24 @@ to be interpreted.
\end{center}
\caption{\label{fig:prectype}The PSBLAS defined data type that contains a preconditioner.}
\end{figure}
\subsubsection{Named Constants}
\label{sec:prec_constants}
\begin{description}
\item[f\_ilu\_n\_] Incomplete LU factorization with $n$ levels of
fill-in; currently only $n=0$ is implemented;
\item[f\_slu\_] Sparse factorization using SuperLU;
\item[f\_umf\_] Sparse factorization using UMFPACK;
\item[add\_ml\_prec\_] Additive multilevel correction;
\item[mult\_ml\_prec\_] Multiplicative multilevel correction;
\item[pre\_smooth\_] Pre-smoothing in applying multiplicative
multilevel corrections;
\item[post\_smooth\_] Post-smoothing in applying multiplicative
multilevel corrections;
\item[smooth\_both\_] Two-sided (i.e. symmetric) smoothing in applying multiplicative
multilevel corrections;
\item[mat\_distr\_] Coarse matrix distributed among processes
\item[mat\_repl\_] Coarse matrix replicated among processes
\end{description}
%%% Local Variables:
docs/pdf/intro.tex
+9
View File
@@ -124,6 +124,15 @@ internally defined in the PSBLAS software package:
Interface overloading allows the usage of the same subroutine
interfaces for both real and complex data.
\end{itemize}
In the description of the subroutines, arguments or argument entries
are classified as:
\begin{description}
\item[global] For input arguments, the value must be the same on all processes
participating in the subroutine call; for output arguments the value
is guaranteed to be the same.
\item[local] Each process has its own value(s) independently.
\end{description}
%%% Local Variables:
%%% mode: latex
docs/pdf/methods.tex
+2 -2
View File
@@ -23,7 +23,7 @@ or
according to the value passed through the istop argument (see later).
\syntax{call psb\_cgs}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}
\syntax{call psb\_cg}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop}
\begin{description}
\item[\bf On Entry]
@@ -57,7 +57,7 @@ Scope: {\bf global} \\
Type: {\bf optional}\\
Default: $itmax = 1000$.\\
Specified as: an integer variable $itmax \ge 1$.
\item[itrace] A tracing parameter.\\
\item[itrace] If $>0$ print out a convergence message every $itrace$ iterations.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
\item[istop] An integer specifying the stopping criterion.\\
docs/pdf/psbrout.tex
+168 -186
View File
@@ -10,14 +10,14 @@
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_{:, jx:jx+n-1}$
\item[$y$] represents the global dense submatrix $y_{:, jy:jy+n-1}$
\end{description}
%% 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}
%% \syntax*{call psb\_geaxpby}{alpha, x, beta, y, desc\_a, info, n, jx, jy}
%( calculating y <- alpha*x+beta*y )
\begin{table}[h]
@@ -44,7 +44,7 @@ Specified as: a number of the data type indicated in Table~\ref{tab:f90axpby}.
$x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a rank one or two array with the POINTER attribute
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$.\\
@@ -55,30 +55,29 @@ Specified as: a number of the data type indicated in Table~\ref{tab:f90axpby}.
$y$. \\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a rank one or two array with the POINTER
attributecontaining numbers of the type
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}\\
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$.
%% \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}
@@ -111,14 +110,14 @@ computes dot-product as:
\[dot \leftarrow x^T y\]
Else if $x$ and $y$ are double precision complex vectors then 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}
%% 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}
%% \syntax*{psb\_gedot}{x, y, desc\_a, info, jx, jy}
\begin{table}[h]
\begin{center}
\begin{tabular}{ll}
@@ -136,37 +135,39 @@ Long Precision Complex & psb\_gedot \\
\begin{description}
\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$ . \\
$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} \\
Specified as: a pointer to array of rank one or two
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$ . \\
$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} \\
Specified as: a pointer to array of rank one or two
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}\\
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[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[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} \\
@@ -213,14 +214,14 @@ Long Precision Complex & psb\_gedot \\
$x$. \\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a pointer to array of rank one or two
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} \\
Specified as: a pointer to array of rank one or two
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.\\
@@ -232,7 +233,7 @@ Specified as: a structured data of type \descdata.
Scope: {\bf global} \\
Specified as: a number or a rank-one array of the data type indicated
in Table~\ref{tab:f90dot}.
\item[info] the local portion of result submatrix $y$.\\
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
@@ -254,13 +255,13 @@ computes infinity norm as:
\[ amax \leftarrow \max_i |x_i|\]
else if $x$ is a double precision complex vector then 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}
%% 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}
%% \syntax*{psb\_geamax}{x, desc\_a, info, jx}
\begin{table}[h]
\begin{center}
@@ -280,30 +281,31 @@ Long Precision Real&Long Precision Complex & psb\_geamax \\
\begin{description}
\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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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}\\
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[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 number of the data type indicated in Table~\ref{tab:f90amax}.
\item[info] the local portion of result submatrix $y$.\\
Scope: {\bf local} \\
Specified as: a long precision real number.
\item[info]
Scope: {\bf global} \\
Type: {\bf required} \\
An integer value that contains an error code.
\end{description}
@@ -340,7 +342,7 @@ Long Precision Real &Long Precision Complex & psb\_geamax\\
$x$. \\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a rank one or two array with the POINTER attribute
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.\\
@@ -350,9 +352,8 @@ 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} \\
Specified as: a number or a rank-one array of the data type indicated
in Table~\ref{tab:f90amax}.
\item[info] the local portion of result submatrix $y$.\\
Specified as: a number or a rank-one array of long precision real numbers.
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
@@ -373,22 +374,18 @@ computes 1-norm as:
\[ asum \leftarrow \|x_i\|\]
else if $x$ ic double precision complex vector then computes 1-norm as:
\[ asum \leftarrow \|re(x)\|_1 + \|im(x)\|_1\]
where:
\begin{description}
\item[$x$] represents the global subvector $x_{:,jx}$
\end{description}
\syntax{psb\_geasum}{x, desc\_a, info}
\syntax*{psb\_geasum}{x, desc\_a, info, jx}
\begin{table}[h]
\begin{center}
\begin{tabular}{ll}
\begin{tabular}{lll}
\hline
$dot$, $x$, $y$ & {\bf Function}\\
$asum$ & $x$ & {\bf Function}\\
\hline
Long Precision Real & psb\_geasum \\
Long Precision Complex & psb\_geasum \\
Long Precision Real&Long Precision Real & psb\_geasum \\
Long Precision Real&Long Precision Complex & psb\_geasum \\
\hline
\end{tabular}
\end{center}
@@ -398,29 +395,24 @@ Long Precision Complex & psb\_geasum \\
\begin{description}
\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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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}\\
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 1-norm of subvector $x$.\\
\item[Function value] is the 1-norm of vector $x$.\\
Scope: {\bf global} \\
Specified as: a number of the data type indicated in Table~\ref{tab:f90asum}.
\item[info] the local portion of result submatrix $y$.\\
Specified as: a long precision real number.
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
@@ -442,19 +434,19 @@ computes 2-norm as:
\[ nrm2 \leftarrow \sqrt{x^T x}\]
else if $x$ is double precision complex vector then computes 2-norm as:
\[ nrm2 \leftarrow \sqrt{x^H x}\]
where:
\begin{description}
\item[$x$] represents the global subvector $x_{:,jx}$
\end{description}
%% where:
%% \begin{description}
%% \item[$x$] represents the global subvector $x_{:,jx}$
%% \end{description}
\begin{table}[h]
\begin{center}
\begin{tabular}{ll}
\begin{tabular}{lll}
\hline
$nrm2$, $x$ & {\bf Function}\\
$nrm2$ & $x$ & {\bf Function}\\
\hline
Long Precision Real & psb\_genrm2 \\
Long Precision Complex & psb\_genrm2 \\
Long Precision Real&Long Precision Real & psb\_genrm2 \\
Long Precision Real&Long Precision Complex & psb\_genrm2 \\
\hline
\end{tabular}
\end{center}
@@ -462,34 +454,35 @@ Long Precision Complex & psb\_genrm2 \\
\end{table}
\syntax{psb\_genrm2}{x, desc\_a, info}
\syntax*{psb\_genrm2}{x, desc\_a, info, jx}
%% \syntax*{psb\_genrm2}{x, desc\_a, info, jx}
\begin{description}
\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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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}\\
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[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 number of the data type indicated in Table~\ref{tab:f90nrm2}.
\item[info] the local portion of result submatrix $y$.\\
Specified as: a long precision real number.
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
@@ -516,7 +509,7 @@ where:
\begin{center}
\begin{tabular}{ll}
\hline
$nrmi$, $A$ & {\bf Function}\\
$A$ & {\bf Function}\\
\hline
Long Precision Real & psb\_spnrmi \\
Long Precision Complex & psb\_spnrmi \\
@@ -542,8 +535,8 @@ 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 number of the data type indicated in Table~\ref{tab:f90nrmi}.
\item[info] the local portion of result submatrix $y$.\\
Specified as: a long precision real number.
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
@@ -576,8 +569,8 @@ y \leftarrow \alpha P_r A^H P_c x + \beta y
where:
\begin{description}
\item[$x$] is the global dense submatrix $x_{:, jx:jx+k-1}$
\item[$y$] is the global dense submatrix $y_{:, jy:jy+k-1}$
\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}
@@ -598,7 +591,7 @@ Long Precision Complex & psb\_spmm \\
\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, k, jx, jy, work}
trans, work}
\begin{description}
\item[\bf On Entry]
@@ -613,11 +606,12 @@ Scope: {\bf local} \\
Type: {\bf required}\\
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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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$.\\
@@ -625,11 +619,12 @@ Scope: {\bf global} \\
Type: {\bf required} \\
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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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.\\
@@ -648,37 +643,38 @@ Scope: {\bf global} \\
Type: {\bf optional}\\
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[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] the work array.\\
\item[work] work array.\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Specified as: a rank one array of the same type of $x$ and $y$ with
the POINTER attribute.
the TARGET attribute.
\item[\bf On Return]
\item[y] the local portion of result submatrix $y$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Specified as: a pointer to array of rank one or two
Specified as: an array of rank one or two
containing numbers of type specified in
Table~\ref{tab:f90spmm}.
\item[info] the local portion of result submatrix $y$.\\
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
@@ -710,8 +706,8 @@ y &\leftarrow& \alpha P_r T^{-H} P_c D x + \beta y\\
where:
\begin{description}
\item[$x$] is the global dense submatrix $x_{:, jx:jx+n-1}$
\item[$y$] is the global dense submatrix $y_{:, jy:jy+n-1}$
\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.
@@ -719,7 +715,7 @@ where:
\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, n, jx, jy, work}
trans, unit, choice, diag, work}
\begin{table}[h]
\begin{center}
@@ -751,11 +747,12 @@ Type: {\bf required}\\
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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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$.\\
@@ -763,11 +760,12 @@ Scope: {\bf global} \\
Type: {\bf required} \\
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$ . \\
$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} \\
Specified as: a rank one or two array with the POINTER attribute
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.\\
@@ -794,57 +792,41 @@ Scope: {\bf global} \\
Type: {\bf optional}\\
Default: $unitd = U$\\
Specified as: a character variable.
\item[choice] specify whether a cleanup of the overlapped elements is
required on exit.
\item[choice] specifies the update of overlap elements to be performed
on exit:
\begin{description}
\item[choice = .false.] no cleanup on exit
\item[choice = .true.] cleanup on exit.\\
\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}\\
Default: $choice = .true.$\\
Specified as: a logical variable.
Default: \verb|psb_avg_|\\
Specified as: an integer variable.
\item[diag] the diagonal scaling matrix.\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Default: $diag(1) = 1 (no scaling)$\\
Specified as: a rank one array containing numbers of the type
indicated in Table~\ref{tab:f90spsm}.
\item[n] 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 $ n \ge 0$.
\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[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$. \\
Scope: {\bf global} \\
Specified as: a number of the data type indicated in Table~\ref{tab:f90spsm}.
\item[work] the work array. \\
\item[work] a work array. \\
Scope: {\bf local} \\
Type: {\bf optional}\\
Specified as: a rank one array of the same type of $x$ with the
POINTER attribute.
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$ . \\
$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} \\
Specified as: a pointer to array of rank one or two
containing numbers of type specified in
Table~\ref{tab:f90spsm}.
\item[info] the local portion of result submatrix $y$.\\
\item[info]
Scope: {\bf local} \\
Type: {\bf required} \\
An integer value that contains an error code.
docs/pdf/toolsrout.tex
+430 -402
View File
@@ -1,248 +1,5 @@
\section{Data management and initialization routines}
\label{sec:toolsrout}
%
%% psb_alloc %%
%
\subroutine{psb\_geall}{Allocates a dense matrix}
\syntax{call psb\_geall}{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\_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 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\_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_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 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}
%
@@ -253,8 +10,11 @@ Type: {\bf required}\\
\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 On Entry]
\item[\bf First Form: On Entry ]
\item[m] the number of rows of the problem.\\
Scope:{\bf global}.\\
Type:{\bf required}.\\
@@ -262,16 +22,36 @@ 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.
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 as described in ???
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]
@@ -286,6 +66,51 @@ Specified as: an integer variable.\\
\end{description}
%
%% 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 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_cdasb %%
%
@@ -307,7 +132,7 @@ Specified as: a structured data of type \descdata.
Scope: {\bf local} \\
Type: {\bf required}\\
Specified as: an integer variable.
\item[arg]
%\item[arg]
\end{description}
@@ -365,81 +190,65 @@ Specified as: an integer variable.
\end{description}
%
%% psb_cdins %%
%
\subroutine{psb\_cdins}{Comunnication descriptor insert routine}
%% %
%% %% psb_cdren %%
%% %
%% \subroutine{psb\_cdren}{Applies a renumeration to a communication descriptor}
\syntax{call psb\_cdins}{nz, ia, ja, desc\_a, info, is, js}
%% \syntax{call psb\_cdren}{trans, iperm, 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 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}
\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_cdren %%
%% psb_descprt %%
%
\subroutine{psb\_cdren}{Applies a renumeration to a communication descriptor}
%% \subroutine{psb\_cdprt}{Prints a descriptor}
\syntax{call psb\_cdren}{trans, iperm, desc\_a, info}
%% \syntax{call psb\_cdprt}{iout, desc\_a, glob, short}
\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 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[info] Error code.
Scope: {\bf local} \\
Type: {\bf required}\\
Specified as: an integer variable.
\end{description}
%% \begin{description}
%% \item[\bf On Return]
%% \item[glob] ??????
%% \item[short] ??????
%% \end{description}
@@ -456,10 +265,13 @@ Specified as: an integer variable.
Scope:{\bf local}.\\
Type:{\bf required}.\\
Specified as: a structured data of type \descdata.
\item[nnz] the number of nonzeroes in the matrix.\\
\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.
Specified as: an integer value. Note: a good estimate for the number
of nonzeroes in the assembled matrix may substantially improve
performance in the matrix build phase, as it will reduce or eliminate
the need for multiple data allocation.
\end{description}
\begin{description}
@@ -476,12 +288,67 @@ Specified as: an integer variable.
%
%% 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}
%
%% psb_spasb %%
%
\subroutine{psb\_spasb}{Sparse matrix assembly routine}
\syntax{call psb\_spasb}{a, desc\_a, info, afmt, up, dup}
\syntax{call psb\_spasb}{a, desc\_a, info, afmt, upd, dupl}
\begin{description}
\item[\bf On Entry]
@@ -492,15 +359,16 @@ 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] ???.\\
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: .
\item[dup] ???.\\
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:
Specified as: integer, possible values: \verb|psb_dupl_ovwrt_|,
\verb|psb_dupl_add_|, \verb|psb_dupl_err_|.
\end{description}
\begin{description}
@@ -517,36 +385,36 @@ Specified as: an integer variable.
%
%% psb_spcnv %%
%
\subroutine{psb\_spcnv}{Converts a sparse matrix storage format}
%% %
%% %% psb_spcnv %%
%% %
%% \subroutine{psb\_spcnv}{Converts a sparse matrix storage format}
\syntax{call psb\_spcnv}{a, b, desc\_a, info}
%% \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 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}
%% \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}
@@ -579,62 +447,6 @@ Specified as: an integer variable.
%
%% psb_ins %%
%
\subroutine{psb\_geins}{Dense matrix insertion routine}
\syntax{call psb\_geins}{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 %%
@@ -677,7 +489,223 @@ Specified as: an integer variable.
%% \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, n, blck, x, ix, jx, desc\_a, info,dupl}
\syntax*{call psb\_geins}{m, blck, x, ix, desc\_a, info,dupl}
\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
(only when $x$ is of rank 2).\\
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[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 (only when $x$ is of rank 2).\\
Scope:{\bf local}.\\
Type:{\bf required}.\\
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_|, \verb|psb_dupl_err_|.
\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}
%
%% 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}
%
docs/userguide.pdf
+16960 -16267
View File
File diff suppressed because one or more lines are too long