Added description of application structure.

19 years ago · cfb1bafee7
parent d04736cffd
commit cfb1bafee7
3 changed files with 9840 additions and 9687 deletions
--- a/docs/pdf/datastruct.tex
+++ b/docs/pdf/datastruct.tex
@ -9,128 +9,6 @@ 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}
 The \hypertarget{spdata}{{\tt psb\_spmat\_type}} data structure
 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. \\
 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 \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.\\
 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}
 FORTRAN95 interface for distributed sparse matrices containing double precision
 real entries is defined as in figure~\ref{fig:spmattype}.
 \begin{figure}[h!]
  \begin{Sbox}
    \begin{minipage}[tl]{0.85\textwidth}
 \begin{verbatim}
 type psb_dspmat_type
   integer     :: m, k
   character   :: fida(5)
   character   :: descra(10)
   integer     :: infoa(psb_ifa_size_)
   real(kind(1.d0)), pointer :: aspk(:)
   integer, pointer :: ia1(:), ia2(:), pr(:), pl(:)
 end type psb_dspmat_type
 \end{verbatim}
    \end{minipage}
  \end{Sbox}
  \setlength{\fboxsep}{8pt}
  \begin{center}
    \fbox{\TheSbox}
  \end{center}
  \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: 
 \begin{description}
 \item[fida=``CSR''] Compressed storage by 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}
 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}
 \label{sec:desc}
@ -139,7 +17,8 @@ exchanged among processes are stored within a data structure of the
 type \hypertarget{descdata}{{\tt 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.  \\ 
+exchanged among processes.  
 It is not necessary for the user to
 know the internal structure of \verb|psb_desc_type|, it is set in
 fully-transparent mode by PSBLAS-TOOLS routines when inserting a new
@ -263,6 +142,130 @@ state, which can take the following values:
 \end{description}
 \subsection{Sparse Matrix data structure}
 \label{sec:spmat}
 The \hypertarget{spdata}{{\tt psb\_spmat\_type}} data structure
 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. \\
 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 \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.\\
 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}
 FORTRAN95 interface for distributed sparse matrices containing double precision
 real entries is defined as in figure~\ref{fig:spmattype}.
 \begin{figure}[h!]
  \begin{Sbox}
    \begin{minipage}[tl]{0.85\textwidth}
 \begin{verbatim}
 type psb_dspmat_type
   integer     :: m, k
   character   :: fida(5)
   character   :: descra(10)
   integer     :: infoa(psb_ifa_size_)
   real(kind(1.d0)), pointer :: aspk(:)
   integer, pointer :: ia1(:), ia2(:), pr(:), pl(:)
 end type psb_dspmat_type
 \end{verbatim}
    \end{minipage}
  \end{Sbox}
  \setlength{\fboxsep}{8pt}
  \begin{center}
    \fbox{\TheSbox}
  \end{center}
  \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: 
 \begin{description}
 \item[fida=``CSR''] Compressed storage by 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}
 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{Preconditioner data structure}
 \label{sec:prec}
 PSBLAS-2.0 offers the possibility to use many different types of
--- a/docs/pdf/intro.tex
+++ b/docs/pdf/intro.tex
@ -133,6 +133,49 @@ are classified as:
 \item[local] Each process has its own value(s) independently.
 \end{description}
 \subsection{Application structure}
 The main underlying principle of the PSBLAS library is that the
 library objects are created and exist with reference to a discretized
 space to which there corresponds and index space and a matrix sparsity
 pattern. As an example, consider a cell-centered finite-volume
 discretization of  the Navier-Stokes equations on a simulation domain;
 the index space $1\dots n$ is isomorphic to the set of cell centers,
 whereas the pattern of the associated linear system matrix is
 isomorphic to the adjacency graph imposed on the discretization mesh
 by the discretization stencil. 
 Thus the first order of business is to establish an index space, and
 this is done with a call to  \verb|psb_cdall| in which we specify the
 size of the index space $n$ and the allocation of the elements of the
 index space to the various processes making up the MPI (virtual)
 parallel machine. 
 The index space is partitioned among processes, and this creates a
 mapping from the ``global'' numbering $1\dots n$ to a numbering
 ``local'' to each process; each process $i$ will own a certain subset
 $1\dots n_{\hbox{row}_i}$, each element of which corresponds to a certain
 element of $1\dots n$. The user does not set explicitly this mapping;
 when the application needs to indicate to which element of the index
 space a certain item is related, such as the row and column index of a
 matrix coefficient, it does so in the ``global'' numbering, and the
 library will translate into the appropriate ``local'' numbering. 
 For  a given index space $1\dots n$ there are many possible associated
 topologies, i.e. many different discretization stencils; thus the
 description of the index space is not completed until the user has
 defined a sparsity pattern, either explicitly through \verb|psb_cdins|
 or implicitly through \verb|psb_spins|. The descriptor is finalized
 with a call to \verb|psb_cdasb| and a sparse matrix with a call to
 \verb|psb_spasb|. After \verb|psb_cdasb| each process $i$ will have
 defined a set of ``halo'' (or ``ghost'') indices
 $n_{\hbox{row}_i}+1\dots n_{\hbox{col}_i}$, denoting elements of the index
 space that are \emph{not} assigned to process $i$; however the
 variables associated with them are needed to complete computations
 associated with the sparse matrix $A$, and thus they have to be
 fetched from (neighbouring) processes. The descriptor of the index
 space is built exactly for the purpose of properly sequencing the
 communication steps required to achieve this objective. 
 %%% Local Variables: 
 %%% mode: latex
--- a/docs/userguide.pdf
+++ b/docs/userguide.pdf