From 5dd25f596d7106027ca549cca45bb36495138775 Mon Sep 17 00:00:00 2001 From: Alfredo Buttari Date: Thu, 3 Nov 2005 17:26:55 +0000 Subject: [PATCH] (Module): --- docs/pdf/Makefile | 3 +- docs/pdf/commrout.tex | 371 +++++++++++++++++ docs/pdf/datastruct.tex | 195 +++++++++ docs/pdf/intro.tex | 6 + docs/pdf/methods.tex | 482 ++++++++++++++++++++++ docs/pdf/precs.tex | 7 + docs/pdf/psbrout.tex | 878 ++++++++++++++++++++++++++++++++++++++++ docs/pdf/title.tex | 58 ++- docs/pdf/toolsrout.tex | 451 +++++++++++++++++++++ docs/pdf/userguide.tex | 124 ++---- 10 files changed, 2482 insertions(+), 93 deletions(-) create mode 100644 docs/pdf/commrout.tex create mode 100644 docs/pdf/datastruct.tex create mode 100644 docs/pdf/intro.tex create mode 100644 docs/pdf/methods.tex create mode 100644 docs/pdf/precs.tex create mode 100644 docs/pdf/psbrout.tex create mode 100644 docs/pdf/toolsrout.tex diff --git a/docs/pdf/Makefile b/docs/pdf/Makefile index 73e5779b..2098749f 100644 --- a/docs/pdf/Makefile +++ b/docs/pdf/Makefile @@ -84,7 +84,8 @@ # TOPFILE = userguide.tex -SECFILE = +SECFILE = title.tex intro.tex commrout.tex datastruct.tex psbrout.tex toolsrout.tex\ + methods.tex precs.tex FIGDIR = figures XPDFFLAGS = diff --git a/docs/pdf/commrout.tex b/docs/pdf/commrout.tex new file mode 100644 index 00000000..a562deea --- /dev/null +++ b/docs/pdf/commrout.tex @@ -0,0 +1,371 @@ +\section{Communication routines} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% HALO DATA COMMUNICATION +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\subroutine{psb\_halo}{Halo Data Communication} + +These subroutines restore a consistent status for the halo +elements, and (optionally) scale the result: + +\[ x \leftarrow \alpha x \] +where: +\begin{description} +\item[$x$] is a global dense submatrix. +\end{description} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$\alpha$, $x$ & {\bf Subroutine}\\ +\hline +Single Precision Real & psb\_halo\\ +Long Precision Real & psb\_halo \\ +Long Precision Complex & psb\_halo \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90halo}} +\end{table} + +\syntax{CALL psb\_halo}{x, desc\_a, info} +\syntax*{CALL psb\_halo}{x, desc\_a, info, alpha, 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 +containing numbers of type specified in +Table~\ref{tab:f90halo}. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in +\S~\ref{sec:datastruct}. +\item[alpha] the scalar $\alpha$.\\ +Scope: {\bf global} \\ +Type: {\bf optional} \\ +Default: $alpha = 1 $\\ +Specified as: a number of the data type indicated in Table~\ref{tab:f90halo}. +\item[work] the work array. \\ +Scope: {\bf local} \\ +Type: {\bf optional}\\ +Specified as: a rank one array of the same type of $x$ with the +POINTER attribute. + +\item[\bf On Return] +\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 +containing numbers of type specified in +Table~\ref{tab:f90halo}. +\item[info] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% OVERLAP UPDATE +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\subroutine{psb\_ovrl}{Overlap Update} + +These subroutines restore a consistent status for the overlap +elements: + +\[ x \leftarrow Q x \] +where: +\begin{description} +\item[$x$] is the global dense submatrix $x$ +\item[$Q$] is the overlap operator; it is the composition of two +operators $ P_a$ and $ P^{T}$. +\end{description} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$x$ & {\bf Subroutine}\\ +\hline +Single Precision Real & psb\_ovrl\\ +Long Precision Real & psb\_ovrl \\ +Long Precision Complex & psb\_ovrl \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90ovrl}} +\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} + +\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 +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 type specified in +\S~\ref{sec:datastruct}. +item[choice] specify if exchange overlap elements. +\begin{description} +\item[choice = .true.] exchange overlap elements, i.e. apply operator +$P^{T}$; +\item[choice = .false.] don't exchange overlap elements +\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. $\\ +Scope: {\bf global} \\ +Specified as: a integer variable. +\item[work] the work array. \\ +Scope: {\bf local} \\ +Type: {\bf optional}\\ +Specified as: a one dimensional array of the same type of $x$. + +\item[\bf On Return] +\item[x] global dense result matrix $x$.\\ +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:f90ovrl}. +\item[info] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + + +\section*{Usage notes} +\begin{enumerate} +\item If there is no overlap in the data distribution, no operations +are performed; +\item The operator $P^{T}$ performs the reduction sum of overlap +elements; it is the inverse of a ``stretch'' operator $P$ that +replicates overlap elements, accounting for the physical replication +of data; +\item The operator $P_a$ performs a scaling on the overlap elements by +the amount of replication; thus, when combined with the reduction +operator, it implements the average of replicated elements over all of +their instances. +\item The square root update option makes it possible to applythe +following operator: +\[ x\leftarrow \sqrt{P_a} P^{T} K^{-1} P \sqrt{P_a} x\] +In the case of a symmetric $K$, this preserves simmetry of the overall +preconditioner, which would otherwise be destroyed. +\end{enumerate} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% GATHER GLOBAL DENSE MATRIX +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_gather}{Gather Global Dense Matrix} + +These subroutines collect the portions of global dense matrix +distributed over all process into one single array stored on one +process. + +\[ glob\_x \leftarrow collect(loc\_x_i) \] +where: +\begin{description} +\item[$glob\_x$] is the global submatrix $glob\_x_{iy:iy+m-1,jy:jy+n-1}$ +\item[$loc\_x_i$] is the local portion of global dense matrix on +process $i$. +\item[$collect$] is the collect function. +\end{description} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$x_i, y$ & {\bf Subroutine}\\ +\hline +Single Precision Real & psb\_gather\\ +Long Precision Real & psb\_gather \\ +Long Precision Complex & psb\_gather \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:gather}} +\end{table} + +\syntax{call psb\_gather}{glob\_x, loc\_x, desc\_a, info, + root, iglobx, jglobx, ilocx, jlocx, k} +\syntax{call psb\_gather}{glob\_x, loc\_x, desc\_a, info, + root, iglobx, ilocx} + +\begin{description} +\item[\bf On Entry] +\item[loc\_x] the local portion of global dense matrix +$glob\_x$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one or two array containing numbers of the type +indicated in Table~\ref{tab:gather}. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[root] The process that holds the global copy. If $root=-1$ all + the processes will have a copy of the global vector.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable $0\le ix\le np$. +\item[iglobx] Row index to define a submatrix in glob\_x into which + gather the local pieces.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable $1\le ix\le matrix\_data(psb\_m\_)$. +\item[jglobx] Column index to define a submatrix in glob\_x into which + gather the local pieces.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[ilocx] Row index to define a submatrix in loc\_x that has to + be gathered into glob\_x.\\ +Scope: {\bf local} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[jlocx] Columns index to define a submatrix in loc\_x that has + to be gathered into glob\_x.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[k] The number of columns to gather.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[\bf On Return] +\item[glob\_x] The array where the local parts must be gathered.\\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a rank one or two array. +\item[info] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% SCATTER GLOBAL DENSE MATRIX +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_scatter}{Scatter Global Dense Matrix} + +These subroutines scatters the portions of global dense matrix owned +by a process to all the processes in the processes grid. + +\[ loc\_x_i \leftarrow scatter(glob\_x_i) \] +where: +\begin{description} +\item[$glob\_x$] is the global submatrix $glob\_x_{iy:iy+m-1,jy:jy+n-1}$ +\item[$loc\_x_i$] is the local portion of global dense matrix on +process $i$. +\item[$scatter$] is the scatter function. +\end{description} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$x_i, y$ & {\bf Subroutine}\\ +\hline +Single Precision Real & psb\_scatter\\ +Long Precision Real & psb\_scatter \\ +Long Precision Complex & psb\_scatter \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:scatter}} +\end{table} + +\syntax{call psb\_scatter}{glob\_x, loc\_x, desc\_a, info, + root, iglobx, jglobx, ilocx, jlocx, k} +\syntax{call psb\_scatter}{glob\_x, loc\_x, desc\_a, info, + root, iglobx, ilocx} + +\begin{description} +\item[\bf On Entry] +\item[glob\_x] The array that must be scattered into local pieces.\\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a rank one or two array. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[root] The process that holds the global copy. If $root=-1$ all + the processes have a copy of the global vector.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable $0\le ix\le np$. +\item[iglobx] Row index to define a submatrix in glob\_x that has to + be scattered into local pieces.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable $1\le ix\le matrix\_data(psb\_m\_)$. +\item[jglobx] Column index to define a submatrix in glob\_x that has to + be scattered into local pieces.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[ilocx] Row index to define a submatrix in loc\_x into which + scatter the local piece of glob\_x.\\ +Scope: {\bf local} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[jlocx] Columns index to define a submatrix in loc\_x into which + scatter the local piece of glob\_x.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[k] The number of columns to scatter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Specified as: an integer variable. +\item[\bf On Return] +\item[loc\_x] the local portion of global dense matrix +$glob\_x$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one or two array containing numbers of the type +indicated in Table~\ref{tab:scatter}. +\item[info] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/datastruct.tex b/docs/pdf/datastruct.tex new file mode 100644 index 00000000..2bcfd386 --- /dev/null +++ b/docs/pdf/datastruct.tex @@ -0,0 +1,195 @@ +\section{Data Structures} +\label{sec:datastruct} +%\ifthenelse{\boolean{mtc}}{\minitoc}{} + +In this chapter are illustrated data structures used for definition of +routines interfaces. This include data structure for sparse matrix, +communication descriptor and preconditioner. These data structures are used for +calling PSBLAS routines in Fortran~90 language and will be used to next +chapters containing these callings. Their definitions are included in +the modules \verb|psb_spmat_type|, \verb|psb_descriptor_type| and \verb|psb_prec_type|. + +\subsection{Sparse Matrix data structure} +\label{sec:spmat} +Contains all information about local portion of the sparse matrix and +its storage mode. Many of this fields are set in fully-transparent +mode by PSBLAS-TOOLS routines when inserting a new sparse matrix, user +must set only fields which describe matrix storage mode (see +\S~\ref{psb_spall}). \\ +Fields contained in Sparse matrix structures are: +\begin{description} +\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 . +\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. +\item[{\bf ia2}] 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. +\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. +\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.\\ +Specified as: array of character of length 9. +\item[{\bf pl}] Specifies the local row permutation of distributed sparse +matrix. If pl(1) is equal to 0, then there isn't row permutation.\\ +Specified as: pointer to integer array of dimension equal to number of local row (matrix\_data[psb\_n\_row\_\hbox{]}) +\item[{\bf pr}] Specifies the local column permutation of distributed sparse +matrix. If PR(1) is equal to 0, then there isn't columnm permutation.\\ +Specified as: pointer to integer array of dimension equal to number of +local row (matrix\_data[psb\_n\_col\_\hbox{]}) +\item[{\bf m}] Number of rows; if row indices are stored explicitly, +as in Coordinate Storage, should be greater than or equal to the +maximum row index actually present in the sparse matrix. +Specified as: integer variable. +\item[{\bf k}] Number of columns; if column indices are stored explicitly, +as in Coordinate Storage or Compressed Sparse Rows, should be greater +than or equal to the maximum column index actually present in the sparse matrix. +Specified as: integer variable. +\end{description} +Values assumed by this fields are compatible with ref. 1 (see \S~\ref{chap:appendix}).\\ +FORTRAN95 interface for distributed sparse matrices containing double precision +real entries is defined as follows: +\begin{verbatim} +type d_spmat + integer :: m, k + character*5 :: fida + character*1 :: descra(9) + integer :: infoa(10) + real(kind(1.d0)), pointer :: aspk(:) + integer, pointer :: ia1(:), ia2(:) + integer, pointer :: pl(:), pr(:) +end type d_spmat +\end{verbatim} +The following two cases are used in the data insertion routines: +\begin{description} +\item[fida=``CSR''] Compressed storage rows. In this case the +following should hold: +\begin{enumerate} +\item \verb|ia2(i)| contains the index of the first element of row +\verb|i|; the last element of the sparse matrix is thus stored at +index $ia2(m+1)-1$. It should contain \verb|m+1| entries in +nondecreasing order (strictly increasing, if there are no empty rows). +\item \verb|ia1(j)| contains the column index and \verb|aspk(j)| +contains the corresponding coefficient value, for all $ia2(1) \le j +\le ia2(m+1)-1$. +\end{enumerate} +\item[fida=``COO''] Coordinate storage. In this case the following +should hold: +\begin{enumerate} +\item \verb|infoa(1)| contains the number of nonzero elements in the +matrix; +\item For all $1 \le j \le infoa(1)$, the coefficient, row index and +column index are stored into \verb|apsk(j)|, \verb|ia1(j)| and +\verb|ia2(j)| respectively. +\end{enumerate} +\end{description} + + +\subsubsection{Sparse Matrix storage formats} + +\subsection{Descriptor data structure} +\label{sec:desc} +All the general matrix informations and elements to be +exchanged among processes are stored within a data structure of the type $psb_desc_type$. +Every structure of this type is associated to a sparse matrix, it +contains data about general matrix informations and elements to be +exchanged among processes. \\ +It is not necessary for the user to +know the internal structure of $psb_desc_type$, it is set in +fully-transparent mode by PSBLAS-TOOLS routines when inserting a new +sparse matrix, however the definition of the descriptor is the +following. +\begin{description} +\item[{\bf matrix\_data}] includes general information about matrix and +BLACS grid. More precisely: +\begin{description} +\item[matrix\_data[psb\_dec\_type\_\hbox{]}] Identifies the decomposition type +(global); the actual values are internally defined, so they should +never be accessed directly. +\item[matrix\_data[psb\_ctxt\_\hbox{]}] Communication context as returned by the +BLACS (global). +\item[matrix\_data[psb\_m\_\hbox{]}] Total number of equations (global). +\item[matrix\_data[psb\_n\_\hbox{]}] Total number of variables (global). +\item[matrix\_data[psb\_n\_row\_\hbox{]}] Number of grid variables owned by the +current process (local); equivalent to the number of local rows in the +sparse coefficient matrix. +\item[matrix\_data[psb\_n\_col\_\hbox{]}] Total number of grid variables read by the +current process (local); equivalent to the number of local columns in +the sparse coefficient matrix. They include the halo. +\end{description} +Specified as: a pointer to integer array of dimension 10. +\item[{\bf halo\_index}] A list of the halo and boundary elements for +the current process to be exchanged with other processes; for each +processes with which it is necessary to communicate: +\begin{enumerate} +\item Process identifier; +\item Number of points to be received; +\item Indices of points to be received; +\item Number of points to be sent; +\item Indices of points to be sent; +\end{enumerate} +The list may contain an arbitrary number of groups; its end is marked +by a -1.\\ +Specified as: a pointer to an integer array of rank one. +\item [{\bf ovrlap\_index}] A list of the overlap elements for the +current process, organized in groups like the previous vector: +\begin{enumerate} +\item Process identifier; +\item Number of points to be received; +\item Indices of points to be received; +\item Number of points to be sent; +\item Indices of points to be sent; +\end{enumerate} +The list may contain an arbitrary number of groups; its end is marked +by a -1.\\ +Specified as: a pointer to an integer array of rank one. +\item [{\bf ovrlap\_index}] For all overlap points belonging to th +ecurrent process: +\begin{enumerate} +\item Overlap point index; +\item Number of processes sharing that overlap points; +\end{enumerate} +The list may contain an arbitrary number of groups; its end is marked +by a -1.\\ +Specified as: a pointer to an integer array of rank one. +\item[{\bf loc\_to\_glob}] each element $i$ of this array contains +global identifier of the local variable $i$.\\ +Specified as: a pointer to an integer array of rank one. +\item[{\bf glob\_to\_loc}] if global variable $i$ is read by current +process then element $i$ contains local index correpondent to global variable $i$; +else element $i$ contains -1 (NULL) value.\\ +Specified as: a pointer to an integer array of rank one. +\end{description} +FORTRAN90 interface for $decomp\_data$ structures is therefore defined +as follows: +\begin{verbatim} + type decomp_data_type + integer, pointer :: matrix_data(:) + integer, pointer :: halo_index(:) + integer, pointer :: ovrlap_elem(:) + integer, pointer :: ovrlap_index(:) + integer, pointer :: loc_to_glob(:) + integer, pointer :: glob_to_loc (:) + end type decomp_data_type +\end{verbatim} + +\subsection{Preconditioner data structure} +\label{sec:prec} +\hypertarget{precdata}{ciao finocchio} + + + +\subsection{Building and assembling data structures} + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/intro.tex b/docs/pdf/intro.tex new file mode 100644 index 00000000..ed0527b7 --- /dev/null +++ b/docs/pdf/intro.tex @@ -0,0 +1,6 @@ +\section{Introduction} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/methods.tex b/docs/pdf/methods.tex new file mode 100644 index 00000000..51914449 --- /dev/null +++ b/docs/pdf/methods.tex @@ -0,0 +1,482 @@ +\section{Iterative Methods} +\label{sec:methods} + +In this chapter we provide routines for preconditioners and iterative +methods. Their +interfaces are defined in the module \verb|psb_methd_mod| + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% CG +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_cg \label{cg}}{CG Iterative Method} + +This subroutine implements the CG method with restarting. The +stopping criterion is the normwise backward error, in the infinity +norm, i.e. the iteration is stopped when +\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \] +or +\[ \frac{\|r_i\|}{\|b\|_2} < eps \] +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} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[prec] The data structure containing the preconditioner.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[b] The RHS vector. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[x] The initial guess. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[eps] The stopping tolerance. \\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a real number. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[itmax] The maximum number of iterations to perform.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $itmax = 1000$.\\ +Specified as: an integer variable $itmax \ge 1$. +\item[itrace] A tracing parameter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[istop] An integer specifying the stopping criterion.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ + +\item[\bf On Return] +\item[x] The computed solution. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[iter] The number of iterations performed.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\item[err] The error estimate on exit.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: a real number. +\item[info] An error code.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\end{description} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% CGS +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_cgs \label{cgs}}{CGS Iterative Method} + +This subroutine implements the CGS method with restarting. The +stopping criterion is the normwise backward error, in the infinity +norm, i.e. the iteration is stopped when +\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \] +or +\[ \frac{\|r_i\|}{\|b\|_2} < eps \] +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} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[prec] The data structure containing the preconditioner.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[b] The RHS vector. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[x] The initial guess. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[eps] The stopping tolerance. \\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a real number. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[itmax] The maximum number of iterations to perform.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $itmax = 1000$.\\ +Specified as: an integer variable $itmax \ge 1$. +\item[itrace] A tracing parameter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[istop] An integer specifying the stopping criterion.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ + +\item[\bf On Return] +\item[x] The computed solution. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[iter] The number of iterations performed.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\item[err] The error estimate on exit.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: a real number. +\item[info] An error code.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% BiCG +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subroutine{psb\_bicg \label{bicg}}{BiCG Iterative Method} + +This subroutine implements the BiCG method with restarting. The +stopping criterion is the normwise backward error, in the infinity +norm, i.e. the iteration is stopped when +\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \] +or +\[ \frac{\|r_i\|}{\|b\|_2} < eps \] +according to the value passed through the istop argument (see later). + + +\syntax{call psb\_bicg}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[prec] The data structure containing the preconditioner.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[b] The RHS vector. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[x] The initial guess. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[eps] The stopping tolerance. \\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a real number. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[itmax] The maximum number of iterations to perform.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $itmax = 1000$.\\ +Specified as: an integer variable $itmax \ge 1$. +\item[itrace] A tracing parameter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[istop] An integer specifying the stopping criterion.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ + +\item[\bf On Return] +\item[x] The computed solution. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[iter] The number of iterations performed.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\item[err] The error estimate on exit.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: a real number. +\item[info] An error code.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% BiCGSTAB +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subroutine{psb\_bicgstab \label{bicgstab}}{BiCGSTAB Iterative Method} + +This subroutine implements the BiCGSTAB method with restarting. The +stopping criterion is the normwise backward error, in the infinity +norm, i.e. the iteration is stopped when +\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \] +or +\[ \frac{\|r_i\|}{\|b\|_2} < eps \] +according to the value passed through the istop argument (see later). + + +\syntax{call psb\_bicgstab}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,istop} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[prec] The data structure containing the preconditioner.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[b] The RHS vector. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[x] The initial guess. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[eps] The stopping tolerance. \\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a real number. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[itmax] The maximum number of iterations to perform.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $itmax = 1000$.\\ +Specified as: an integer variable $itmax \ge 1$. +\item[itrace] A tracing parameter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[istop] An integer specifying the stopping criterion.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ + +\item[\bf On Return] +\item[x] The computed solution. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[iter] The number of iterations performed.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\item[err] The error estimate on exit.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: a real number. +\item[info] An error code.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% BiCGSTAB(L) +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subroutine{psb\_bicgstabl \label{bicgstabl}}{BiCGSTAB-$l$ Iterative Method} + +This subroutine implements the BiCGSTAB-$l$ method with restarting. The +stopping criterion is the normwise backward error, in the infinity +norm, i.e. the iteration is stopped when +\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \] +or +\[ \frac{\|r_i\|}{\|b\|_2} < eps \] +according to the value passed through the istop argument (see later). + + +\syntax{call psb\_bicgstab}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,irst,istop} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[prec] The data structure containing the preconditioner.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[b] The RHS vector. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[x] The initial guess. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[eps] The stopping tolerance. \\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a real number. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[itmax] The maximum number of iterations to perform.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $itmax = 1000$.\\ +Specified as: an integer variable $itmax \ge 1$. +\item[itrace] A tracing parameter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[irst] An integer specifying the restarting iteration.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[istop] An integer specifying the stopping criterion.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ + +\item[\bf On Return] +\item[x] The computed solution. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[iter] The number of iterations performed.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\item[err] The error estimate on exit.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: a real number. +\item[info] An error code.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% GMRES +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subroutine{psb\_gmres \label{gmres}}{GMRES Iterative Method} + +This subroutine implements the GMRES method with restarting. The +stopping criterion is the normwise backward error, in the infinity +norm, i.e. the iteration is stopped when +\[ \frac{\|r\|}{(\|A\|\|x\|+\|b\|)} < eps \] +or +\[ \frac{\|r_i\|}{\|b\|_2} < eps \] +according to the value passed through the istop argument (see later). + + +\syntax{call psb\_gmres}{a,prec,b,x,eps,desc\_a,info,itmax,iter,err,itrace,irst,istop} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[prec] The data structure containing the preconditioner.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[b] The RHS vector. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[x] The initial guess. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[eps] The stopping tolerance. \\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +Specified as: a real number. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in \S~\ref{sec:datastruct}. +\item[itmax] The maximum number of iterations to perform.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $itmax = 1000$.\\ +Specified as: an integer variable $itmax \ge 1$. +\item[itrace] A tracing parameter.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[irst] An integer specifying the restart iteration.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +\item[istop] An integer specifying the stopping criterion.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ + +\item[\bf On Return] +\item[x] The computed solution. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a rank one array. +\item[iter] The number of iterations performed.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\item[err] The error estimate on exit.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: a real number. +\item[info] An error code.\\ +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Returned as: an integer variable. +\end{description} + + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/precs.tex b/docs/pdf/precs.tex new file mode 100644 index 00000000..b5c9ebaa --- /dev/null +++ b/docs/pdf/precs.tex @@ -0,0 +1,7 @@ +\section{Preconditioner routines} +\label{sec:precs} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/psbrout.tex b/docs/pdf/psbrout.tex new file mode 100644 index 00000000..9f92bee9 --- /dev/null +++ b/docs/pdf/psbrout.tex @@ -0,0 +1,878 @@ +\section{Algebraic routines} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% DENSE MATRIX SUM +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subroutine{psb\_axpby}{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_{:, jx:jx+n-1}$ +\item[$y$] represents the global dense submatrix $y_{:, jy:jy+n-1}$ +\end{description} + +\syntax{call psb\_axpby}{alpha, x, beta, y, desc\_a, info} +\syntax*{call psb\_axpby}{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 +Single Precision Real & psb\_axpby \\ +Long Precision Real & psb\_axpby \\ +Long Precision Complex & psb\_axpby \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90axpby}} +\end{table} + +\begin{description} +\item[\bf On Entry] +\item[alpha] the scalar $\alpha$.\\ +Scope: {\bf global} \\ +Type: {\bf required} \\ +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} \\ +Specified as: a rank one or two array with the POINTER attribute +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} \\ +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} \\ +Specified as: a rank one or two array with the POINTER +attributecontaining 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 type specified in \S~\ref{sec:datastruct}. +\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} \\ +Specified as: a rank one or two array containing numbers of the type +indicated in Table~\ref{tab:f90axpby}. +\item[info] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% F90DOT PRODUCT +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_dot}{Dot Product} + +This function computes dot product between two vectors $x$ and +$y$.\\ +If $x$ and $y$ are double precision real or single precision real vectors +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} + +\syntax{psb\_dot}{x, y, desc\_a, info} +\syntax*{psb\_dot}{x, y, desc\_a, info, jx, jy} +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$dot$, $x$, $y$ & {\bf Function}\\ +\hline +Single Precision Real & psb\_dot\\ +Long Precision Real & psb\_dot \\ +Long Precision Complex & psb\_dot \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90dot}} +\end{table} + +\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$ . \\ +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: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} \\ +Specified as: a pointer to 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 type specified in +\S~\ref{sec:datastruct}. +\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] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% F90DOT PRODUCT +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_dot}{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{psb\_dot}{res, x, y, desc\_a, info} +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$res$, $x$, $y$ & {\bf Subroutine}\\ +\hline +Single Precision Real & psb\_dot\\ +Long Precision Real & psb\_dot \\ +Long Precision Complex & psb\_dot \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90mdot}} +\end{table} + +\begin{description} +\item[\bf On Entry] +\item[x] the local portion of global dense matrix +$x$. \\ +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: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 +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}\\ +Specified as: a structured data type specified in Sec.~\ref{sec:datastruct}. +\item[\bf On Return] +\item[res] is the dot product of subvectors $x$ and $y$.\\ +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$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% VECTOR INFINITY-NORM +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\subroutine{psb\_amax}{Infinity-Norm of Vector} + +This function computes + the infinity-norm of a vector $x$.\\ +If $x$ is double precision real or single precision real vector +computes infinity norm as: +\[ amax \leftarrow \max_i |x_i|\] +else if $x$ is 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} + +\syntax{psb\_amax}{x, desc\_a, info} +\syntax*{psb\_amax}{x, desc\_a, info, jx} + +\begin{table}[h] +\begin{center} +\begin{tabular}{lll} +\hline +$amax$ & $x$ & {\bf Function}\\ +\hline +Single Precision Real&Single Precision Real & psb\_amax\\ +Long Precision Real&Long Precision Real & psb\_amax \\ +Long Precision Real&Long Precision Complex & psb\_zamax \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90amax}} +\end{table} + + +\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$ . \\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +Specified as: a rank one or two array with the POINTER attribute +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 type specified in +\S~\ref{sec:datastruct}. +\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} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% Infinity norm +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\subroutine{psb\_amax}{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{psb\_amax}{res, x, desc\_a, info} +\begin{table}[h] +\begin{center} +\begin{tabular}{lll} +\hline +$res$& $x$& {\bf Subroutine}\\ +\hline +Single Precision Real &Single Precision Real & psb\_amax\\ +Long Precision Real &Long Precision Real & psb\_amax\\ +Long Precision Real &Long Precision Complex & psb\_amax\\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90mamax}} +\end{table} + +\begin{description} +\item[\bf On Entry] +\item[x] the local portion of global dense matrix +$x$. \\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +Specified as: a rank one or two array with the POINTER attribute +containing numbers of type specified in +Table~\ref{tab:f90mamax}. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in Sec.~\ref{sec:datastruct}. +\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$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% 1-NORM OF A VECTOR +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\subroutine{psb\_asum}{1-Norm of Vector} + +This function computes the 1-norm of a vector $x$.\\ +If $x$ is double precision real or single precision real vector +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\_asum}{x, desc\_a, info} +\syntax*{psb\_asum}{x, desc\_a, info, jx} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$dot$, $x$, $y$ & {\bf Function}\\ +\hline +Single Precision Real & psb\_asum\\ +Long Precision Real & psb\_asum \\ +Long Precision Complex & psb\_asum \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90asum}} +\end{table} + +\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$ . \\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +Specified as: a rank one or two array with the POINTER attribute +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 type specified in +\S~\ref{sec:datastruct}. +\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$.\\ +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$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% 2-NORM OF A VECTOR +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\subroutine {psb\_nrm2}{2-Norm of Vector} + +This function computes the 2-norm of a vector $x$.\\ +If $x$ is double precision real or single precision real vector +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} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$nrm2$, $x$ & {\bf Function}\\ +\hline +Single Precision Real & psb\_nrm2\\ +Long Precision Real & psb\_nrm2 \\ +Long Precision Complex & psb\_nrm2 \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90nrm2}} +\end{table} + +\syntax{psb\_nrm2}{x, desc\_a, info} +\syntax*{psb\_nrm2}{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$ . \\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +Specified as: a rank one or two array with the POINTER attribute +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 type specified in +\S~\ref{sec:datastruct}. +\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$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% INFINITY-NORM OF A MATRIX +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\subroutine{psb\_nrmi}{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 +$nrmi$, $A$ & {\bf Function}\\ +\hline +Single Precision Real & psb\_nrmi\\ +Long Precision Real & psb\_nrmi \\ +Long Precision Complex & psb\_nrmi \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90nrmi}} +\end{table} + +\syntax{psb\_nrmi}{A, desc\_a, info} + +\begin{description} +\item[\bf On Entry] +\item[a] the local portion of the global sparse matrix +$A$. \\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in +\S~\ref{sec:datastruct}. +\item[desc\_a] contains data structures for communications.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +Specified as: a structured data type specified in +\S~\ref{sec:datastruct}. +\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$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\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_{:, jx:jx+k-1}$ +\item[$y$] is the global dense submatrix $y_{:, jy:jy+k-1}$ +\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 +Single Precision Real & psb\_spmm\\ +Long Precision Real & 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, k, jx, jy, work} + +\begin{description} +\item[\bf On Entry] +\item[alpha] the scalar $\alpha$.\\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +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}\\ +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} \\ +Specified as: a rank one or two array with the POINTER attribute +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} \\ +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} \\ +Specified as: a rank one or two array with the POINTER attribute +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}\\ +Specified as: a structured data type specified in +\S~\ref{sec:datastruct}. +\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}\\ +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] the work array.\\ +Scope: {\bf local} \\ +Specified as: a rank one array of the same type of $x$ and $y$ with +the POINTER 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 +containing numbers of type specified in +Table~\ref{tab:f90spmm}. +\item[info] the local portion of result submatrix $y$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\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_{:, jx:jx+n-1}$ +\item[$y$] is the global dense submatrix $y_{:, jy:jy+n-1}$ +\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, n, jx, jy, work} + +\begin{table}[h] +\begin{center} +\begin{tabular}{ll} +\hline +$T$, $x$, $y$, $D$, $\alpha$, $\beta$ & {\bf Subroutine}\\ +\hline +Single Precision Real & psb\_spsm\\ +Long Precision Real & psb\_spsm \\ +Long Precision Complex & psb\_spsm \\ +\hline +\end{tabular} +\end{center} +\caption{Data types\label{tab:f90spsm}} +\end{table} + + + +\begin{description} +\item[\bf On Entry] +\item[alpha] the scalar $\alpha$.\\ +Scope: {\bf global} \\ +Type: {\bf required}\\ +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}\\ +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} \\ +Specified as: a rank one or two array with the POINTER attribute +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} \\ +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} \\ +Specified as: a rank one or two array with the POINTER attribute +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}\\ +Specified as: a structured data type specified in +\S~\ref{sec:datastruct}. +\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}\\ +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}\\ +Default: $unitd = U$\\ +Specified as: a character variable. +\item[choice] specify whether a cleanup of the overlapped elements is +required on exit. +\begin{description} +\item[choice = .false.] no cleanup on exit +\item[choice = .true.] cleanup on exit.\\ +\end{description} +Scope: {\bf global} \\ +Type: {\bf optional}\\ +Default: $choice = .true.$\\ +Specified as: a logical 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. \\ +Scope: {\bf local} \\ +Type: {\bf optional}\\ +Specified as: a rank one array of the same type of $x$ with the +POINTER 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} \\ +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$.\\ +Scope: {\bf local} \\ +Type: {\bf required} \\ +An integer value that contains an error code. +\end{description} + + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/title.tex b/docs/pdf/title.tex index f4ee9e07..86e1bc05 100644 --- a/docs/pdf/title.tex +++ b/docs/pdf/title.tex @@ -1,14 +1,46 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% Contents: The title page +% $Id$ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\ifx\pdfoutput\undefined % We're not running pdftex +\else +\pdfbookmark{Title Page}{title} +\fi +\newlength{\centeroffset} +\setlength{\centeroffset}{-0.5\oddsidemargin} +\addtolength{\centeroffset}{0.5\evensidemargin} +%\addtolength{\textwidth}{-\centeroffset} \thispagestyle{empty} -\vspace{5cm} - -\begin{center} -{\Large PSBLAS V. 2.0}\\ -Userguide -\vspace{5cm} -Alfredo Buttari -Salvatore Filippone - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "userguide" -%%% End: +\vspace*{\stretch{1}} +\noindent\hspace*{\centeroffset}\makebox[0pt][l]{\begin{minipage}{\textwidth} +\flushright +{\Huge\bfseries PSBLAS-2.0 User's guide +} +\noindent\rule[-1ex]{\textwidth}{5pt}\\[2.5ex] +\hfill\emph{\Large A reference guide for the Parallel Sparse BLAS library} +\end{minipage}} + +\vspace{\stretch{1}} +\noindent\hspace*{\centeroffset}\makebox[0pt][l]{\begin{minipage}{\textwidth} +\flushright +{\bfseries +by Salvatore Filippone\\[1.5ex] +and Alfredo Buttari\\[3ex]} +``Tor Vergata'' University of Rome. +\today +\end{minipage}} + +%\addtolength{\textwidth}{\centeroffset} +\vspace{\stretch{2}} + +\endinput + +% + +% Local Variables: +% TeX-master: "userguide" +% mode: latex +% mode: flyspell +% End: + diff --git a/docs/pdf/toolsrout.tex b/docs/pdf/toolsrout.tex new file mode 100644 index 00000000..4c8459fd --- /dev/null +++ b/docs/pdf/toolsrout.tex @@ -0,0 +1,451 @@ +\section{Data management and initialization routines} +% +%% psb_alloc %% +% +\subroutine{psb\_alloc}{Allocates a dense matrix} + +\syntax{call psb\_alloc}{m, n, x, desc\_a, info, js} +\syntax*{call psb\_alloc}{m, n, x, desc\_a, info} + +\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}\\ +\item[n] The number of columns of the dense matrix to be allocated.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +\item[desc\_a] The communication descriptor.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +\item[js] The starting column.\\ +Scope: {\bf local} \\ +Type: {\bf optional}\\ +\end{description} + +\begin{description} +\item[\bf On Return] +\item[x] The dense matrix to be allocated. +Scope: {\bf local} \\ +Type: {\bf required}\\ +\item[info] Error code. +Scope: {\bf local} \\ +Type: {\bf required}\\ +\end{description} + +% +%% psb_asb %% +% +\subroutine{psb\_asb}{Assembly a dense matrix} + +\syntax{call psb\_asb}{x, desc\_a, info} + +\begin{description} +\item[\bf On Entry] +\item[desc\_a] The communication descriptor.\\ +Scope: {\bf local} \\ +Type: {\bf required}\\ +\end{description} + +\begin{description} +\item[\bf On Return] +\item[x] The dense matrix to be assembled. +Scope: {\bf local} \\ +Type: {\bf required}\\ +\item[info] Error code. +Scope: {\bf local} \\ +Type: {\bf required}\\ +\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[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + +% +%% psb_descprt %% +% +\subroutine{psb\_descprt}{Prints a descriptor} + +\syntax{call psb\_descprt}{iout, desc\_p, glob, short} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + +% +%% psb_free %% +% +\subroutine{psb\_free}{Frees a dense matrix} + +\syntax{call psb\_free}{x, desc\_a, info} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\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[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + +% +%% psb_ins %% +% +\subroutine{psb\_ins}{Insert a submatrix into a dense matrix} + +\syntax{call psb\_ins}{m, n, x, ix, jx, blck, desc\_a, info, iblck, jblck} +\syntax*{call psb\_ins}{m, x, ix, jx, blck, desc\_a, info, iblck} +\syntax*{call psb\_ins}{m, x, ix, jx, blck, desc\_a, info, iblck, insflag} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + +% +%% psb_dscall %% +% +\subroutine{psb\_dscall}{Allocates a communication descriptor} + +\syntax{call psb\_dscall}{m, n, parts, icontxt, desc\_a, info, flag} +\syntax*{call psb\_dscall}{m, v, icontxt, desc\_a, info, flag} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + +% +%% psb_dscasb %% +% +\subroutine{psb\_dscasb}{Communication descriptor assembly routine} + +\syntax{call psb\_dscasb}{desc\_a, info} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_dsccpy %% +% +\subroutine{psb\_dsccpy}{Copies a communication descriptor} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + +% +%% psb_dscfree %% +% +\subroutine{psb\_dscfree}{Frees a communication descriptor} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_dscins %% +% +\subroutine{psb\_dscins}{Comunnication descriptor insert routine} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_dscren %% +% +\subroutine{psb\_dscren}{Applies a renumeration to a communication descriptor} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_spalloc %% +% +\subroutine{psb\_spalloc}{Allocates a sparse matrix} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_spasb %% +% +\subroutine{psb\_spasb}{Sparse matrix assembly routine} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_spcnv %% +% +\subroutine{psb\_spcnv}{Converts a sparse matrix storage format} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_spfree %% +% +\subroutine{psb\_spfree}{Frees a sparse matrix} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_spins %% +% +\subroutine{psb\_spins}{Sparse matrix insertion routine} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_sprn %% +% +\subroutine{psb\_sprn}{???} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_spupdate %% +% +\subroutine{psb\_spupdate}{???} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_glob_to_loc %% +% +\subroutine{psb\_glob\_to\_loc}{Global to local indices convertion} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + + +% +%% psb_loc_to_glob %% +% +\subroutine{psb\_loc\_to\_glob}{Local to global indices conversion} + +\syntax{call }{} +\syntax*{call }{} + +\begin{description} +\item[\bf On Entry] +\item[arg] +\end{description} + +\begin{description} +\item[\bf On Return] +\item[arg] +\end{description} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "userguide" +%%% End: diff --git a/docs/pdf/userguide.tex b/docs/pdf/userguide.tex index ccafbd68..92af315a 100644 --- a/docs/pdf/userguide.tex +++ b/docs/pdf/userguide.tex @@ -1,8 +1,8 @@ -\documentclass[12pt,a4paper,twoside]{report} +\documentclass[12pt,a4paper,twoside]{article} \usepackage{pstricks} \usepackage{amsfonts} -\usepackage{minitoc} -\setcounter{minitocdepth}{2} +% \usepackage{minitoc} +% \setcounter{minitocdepth}{2} \usepackage[bookmarks=true, bookmarksnumbered=true, bookmarksopen=false, @@ -16,8 +16,8 @@ \newtheorem{theorem}{Theorem} \newtheorem{corollary}{Corollary} -\newboolean{mtc} -\setboolean{mtc}{true} +%\newboolean{mtc} +%\setboolean{mtc}{true} \pdfoutput=1 \relax @@ -30,98 +30,64 @@ /Producer ($Id$) } \pdfcatalog{ %-- Catalog dictionary of PDF output. - %/PageMode - %/UseNone - %/UseOutlines - %/UseThumbs - %/FullScreen /URI (http://ce.uniroma2.it/psblas) } -%openaction goto page 1 {/Fit} - - -%\usepackage{ucs} -%\usepackage[utf8x]{inputenc} - -%\addtolength{\hoffset}{-0.5cm} -%\addtolength{\textwidth}{1.5cm} - -\title{Parallel Sparse BLAS V. 2.0: user's guide} -\author{ -Alfredo Buttari\thanks{ -%Computer Science Engineering Dept. -Tor Vergata University, Rome, Italy}, -Salvatore Filippone\addtocounter{footnote}{-1}\footnotemark -} -\date{\today} +\newcounter{subroutine}[subsection] +\newcounter{example}[subroutine] +\newcommand{\subroutine}[2]{\clearpage% +\stepcounter{subroutine}% + \section*{\flushleft #1---#2 \endflushleft}% + \addcontentsline{toc}{subsection}{#1}% + \markright{#1}}% +\newcommand{\examplename}{Example} +\newcommand{\syntaxname}{Syntax} +\makeatletter +\def\syntax{\@ifstar{\@ssyntax}{\@syntax}}% +\def\@syntax{\section*{\syntaxname}% + \@ssyntax}% +\def\@ssyntax#1#2{% + \setbox\@tempboxa\hbox{#1\ {\em $($#2$)$}}% + \ifdim \wd\@tempboxa >\hsize + \setbox\@tempboxa\hbox{\em $($#2$)$} + \ifdim\wd\@tempboxa >\hsize + \begin{flushright}#1\ \em$($#2$)$\end{flushright}% + \else + \hbox to\hsize{#1\hfil}% + \hbox to\hsize{\hfil\box\@tempboxa}% + \fi + \else + \hbox to\hsize{\hfil\box\@tempboxa\hfil}% + \fi\par\vskip\baselineskip} +\makeatother +\newcommand{\example}{\stepcounter{example}% +\section*{\examplename~\theexample}} + +\newcommand{\precdata}{\hyperlink{precdata}{\tt psb\_prec\_data}} \begin{document} -\maketitle -\ifthenelse{\boolean{mtc}}{\dominitoc}{} - \newcommand{\ns}{\normalsize} - \newcommand{\fs}{\footnotesize} - \newcommand{\sz}{\scriptsize} - \newcommand{\sm}{\small} - \newcommand{\doublespace}{\addtolength{\baselineskip}{.5\baselineskip}} - \newcommand{\und}{\underline} - \newcommand{\bi}{\begin{itemize}} - \newcommand{\ei}{\end{itemize}} - - \newcommand{\ls}[1] - {\dimen0=\fontdimen6\the\font - \lineskip=#1\dimen0 - \advance\lineskip.5\fontdimen5\the\font - \advance\lineskip-\dimen0 - \lineskiplimit=.9\lineskip - \baselineskip=\lineskip - \advance\baselineskip\dimen0 - \normallineskip\lineskip - \normallineskiplimit\lineskiplimit - \normalbaselineskip\baselineskip - \ignorespaces} - - \newcommand{\thls}{\ls{1.35}} - \newcommand{\tabls}{\ls{1.2}} - -% \begingroup -% \renewcommand*{\thepage}{Title} -% \include{committee} -% \endgroup - -% \begingroup -% \renewcommand*{\thepage}{ack} -% \include{ack} -% \endgroup +\include{title} \begingroup \renewcommand*{\thepage}{toc} \pagenumbering{roman} % Roman numbering \setcounter{page}{1} % Abstract start on page ii - \thls \tableofcontents \endgroup -%\listoffigures -%\listoftables - \newpage \pagenumbering{arabic} % Arabic numbering \setcounter{page}{1} % Chapters start on page 1 -% HEADER and FOOTER -\pagestyle{headings} - -\renewcommand{\chaptermark}[1]% - {\markboth{\ #1 \hspace{0.3cm}Chapter \thechapter}{}} -\renewcommand{\sectionmark}[1]% - {\markright{Section \thesection.\ \hspace{0.3cm}#1}} - - - - - +\precdata +\include{intro} +\include{datastruct} +\include{psbrout} +\include{commrout} +\include{toolsrout} +\include{methods} +\include{precs} \end{document} %%% Local Variables: