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

*** empty log message ***

Browse Source
This commit is contained in:
Alfredo Buttari
2006-03-07 19:23:45 +00:00
parent e61b6501b8
commit 14e7e0d1db
6 changed files with 273 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pdf/datastruct.tex
+99 -27
View File
@@ -54,18 +54,29 @@ 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:
real entries is defined as in figure~\ref{fig:spmattype}.
\begin{figure}[h!]
\begin{Sbox}
\begin{minipage}[tl]{0.85\textwidth}
\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
type psb_dspmat_type
integer :: m, k
character :: fida(5)
character :: descra(10)
integer :: infoa(10)
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
@@ -91,8 +102,6 @@ column index are stored into \verb|apsk(j)|, \verb|ia1(j)| and
\end{description}
\subsubsection{Sparse Matrix storage formats}
\subsection{Descriptor data structure}
\label{sec:desc}
All the general matrix informations and elements to be
@@ -102,7 +111,7 @@ 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
know the internal structure of \verb|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.
@@ -167,26 +176,89 @@ 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
FORTRAN95 interface for \verb|psb_desc_type| 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
\begin{figure}[h!]
\begin{Sbox}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type psb_desc_type
integer, pointer :: matrix_data(:), halo_index(:)
integer, pointer :: overlap_elem(:), overlap_index(:)
integer, pointer :: loc_to_glob(:), glob_to_loc(:)
end type psb_desc_type
\end{verbatim}
\end{minipage}
\end{Sbox}
\setlength{\fboxsep}{8pt}
\begin{center}
\fbox{\TheSbox}
\end{center}
\caption{\label{fig:desctype}The PSBLAS defined data type that
contains the communication descriptor.}
\end{figure}
\subsection{Preconditioner data structure}
\label{sec:prec}
\hypertarget{precdata}{}
PSBLAS-2.0 offers the possibility to use many different types of
preconditioning schemes. Besides the simple well known preconditioners
like Diagonal Scaling or Block Jacobi (with ILU(0) incomplete
factorization) also more complex preconditioning methods are
implemented like the Additive Schwarz and Two-Level ones. A
preconditioner is held in the \hypertarget{precdata}{{\tt psb\_prec\_type}} data structure
which depends on the \verb|psb_base_prec| reported in
figure~\ref{fig:prectype}. The \verb|psb_base_prec|
data type may contain a simple preconditioning matrix with the
associated communication descriptor which may be different than the
system communication descriptor in the case of parallel
preconditioners like the Additive Schwarz one. Then the
\verb|psb_prec_type| may contain more than one preconditioning matrix
like in the case of Two-Level (in general Multi-Level) preconditioners.
The user can choose the type of preconditioner to be used by means of
the \verb|psb_precset| subroutine; once the type of preconditioning
method is specified, along with all the parameters that characterize
it, the preconditioner data structure can be built using the
\verb|psb_precbuild| subroutine.
This data structure wants to be flexible enough to easily allow the
implementation of new kind of preconditioners. The values contained in
the \verb|iprcparm| and \verb|dprcparm| define tha type of
preconditioner along with all the parameters related to it; thus,
\verb|iprcparm| and \verb|dprcparm| define how the other records have
to be interpreted.
\begin{figure}[h!]
\small
\begin{Sbox}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type psb_base_prec
\subsection{Building and assembling data structures}
type(psb_spmat_type), pointer :: av(:) => null()
real(kind(1.d0)), pointer :: d(:) => null()
type(psb_desc_type), pointer :: desc_data => null()
integer, pointer :: iprcparm(:) => null()
real(kind(1.d0)), pointer :: dprcparm(:) => null()
integer, pointer :: perm(:) => null()
integer, pointer :: mlia(:) => null()
integer, pointer :: invperm(:) => null()
integer, pointer :: nlaggr(:) => null()
type(psb_spmat_type), pointer :: aorig => null()
real(kind(1.d0)), pointer :: dorig(:) => null()
end type psb_base_prec
type psb_prec_type
type(psb_base_prec), pointer :: baseprecv(:) => null()
integer :: prec, base_prec
end type psb_prec_type
\end{verbatim}
\end{minipage}
\end{Sbox}
\setlength{\fboxsep}{8pt}
\begin{center}
\fbox{\TheSbox}
\end{center}
\caption{\label{fig:prectype}The PSBLAS defined data type that contains a preconditioner.}
\end{figure}
docs/pdf/intro.tex
+126
View File
@@ -1,5 +1,131 @@
\section{Introduction}
The PSBLAS library, developed with the aim to facilitate the
parallelization of computationally intensive scientific applications,
is designed to address parallel implementation of iterative solvers
for sparse linear systems through the distributed memory paradigm. It
includes routines for multiplying sparse matrices by dense matrices,
solving block diagonal systems with triangular diagonal entries,
preprocessing sparse matrices, and contains additional routines for
dense matrix operations. The current implementation of PSBLAS
addresses a distributed memory execution model operating with message
passing. However, the overall design does not preclude different
implementation paradigms, such as those based on a shared memory
model.
The PSBLAS library is internally implemented in a mixture of
Fortran~77 and Fortran~95~\cite{metcalf} programming languages. A
similar approach has been advocated by a number of authors,
e.g.~\cite{machiels}. Moreover, the Fortran~95 facilities for dynamic
memory management and interface overloading greatly enhance the usability of the PSBLAS
subroutines. In this way, the library can take care of runtime memory
requirements that are quite difficult or even impossible to predict at
implementation or compilation time. The following presentation of the
PSBLAS library follows the general structure of the proposal for
serial Sparse BLAS~\cite{sblas97}, which in its turn is based on the
proposal for BLAS on dense matrices~\cite{BLAS1,BLAS2,BLAS3}.
The applicability of sparse iterative solvers to many different areas
causes some terminology problems because the same concept may be
denoted through different names depending on the application area. The
PSBLAS features presented in this section will be discussed mainly in terms of finite
difference discretizations of Partial Differential Equations (PDEs).
However, the scope of the library is wider than that: for example, it
can be applied to finite element discretizations of PDEs, and even to
different classes of problems such as nonlinear optimization, for
example in optimal control problems.
The design of a solver for sparse linear systems is driven by many
conflicting objectives, such as limiting occupation of storage
resources, exploiting regularities in the input data, exploiting
hardware characteristics of the parallel platform. To achieve an
optimal communication to computation ratio on distributed memory
machines it is essential to keep the {\em data locality} as high as
possible; this can be done through an appropriate data allocation
strategy. The choice of the preconditioner is another very important
factor that affects efficiency of the implemented application. Optimal
data distribution requirements for a given preconditioner may conflict
with distribution requirements of the rest of the solver. Finding the
optimal trade-off may be very difficult because it is application
dependent. Possible solution to these problems and other important
inputs to the development of the PSBLAS software package has come from
an established experience in applying the PSBLAS solvers to
computational fluid dynamics applications.
\section{General overview}
\label{sec:overview}
The PSBLAS library is designed to handle the implementation of
iterative solvers for sparse linear systems on distributed memory
parallel computers. The system coefficient matrix $A$ must be square;
it may be real or complex, nonsymmetric, and its sparsity pattern
needs not to be symmetric. The serial computation parts are based on
the serial sparse BLAS, so that any extension made to the data
structures of the serial kernels is available to the parallel
version. The overall design and parallelization strategy have been
influenced by the structure of the ScaLAPACK parallel
library~\cite{scalapack}. The layered structure of the PSBLAS library
is shown in figure~\ref{fig:psblas} ; lower layers of the library
indicate an encapsulation relationship with upper layers. The ongoing
discussion focuses on the Fortran~95 layer immediately below the
application layer; two examples of iterative solvers built through the
PSBLAS routines, will be also given in Section~\ref{sec:itmethd}. The
serial parts of the computation on each process are executed through
calls to the serial sparse BLAS subroutines. In a similar way, the
inter-process message exchanges are implemented through the Basic
Linear Algebra Communication Subroutines (BLACS) library~\cite{BLACS}
that guarantees a portable and efficient communication layer. The
Message Passing Interface code is encapsulated within the BLACS
layer. However, in some cases, MPI routines are directly used either
to improve efficiency or to implement communication patterns for which
the BLACS package doesn't provide any method.
\begin{figure}[h] \begin{center}
\includegraphics[scale=0.45]{figures/psblas}
\end{center}
\caption{PSBLAS library components hierarchy.\label{fig:psblas}}
\end{figure}
The PSBLAS library consists of two classes of subroutines that is, the
{\em computational routines} and the {\em auxiliary routines}. The
computational routine set includes:
\begin{itemize}
\item Sparse matrix by dense matrix product; \item Sparse triangular
systems solution for block diagonal matrices;
\item Vector and matrix norms;
\item Dense matrix sums;
\item Dot products.
\end{itemize}
The auxiliary routine set includes:
\begin{itemize}
\item Communication descriptors allocation;
\item Dense and sparse matrix allocation;
\item Dense and sparse matrix build and update;
\item Sparse matrix and data distribution preprocessing.
\end{itemize}
The following naming scheme has been adopted for all the symbols
internally defined in the PSBLAS software package:
\begin{itemize}
\item all the symbols (i.e. subroutine names, data types...) are
prefixed by \verb|psb_|
\item all the data type names are suffixed by \verb|_type|
\item all the constant values are suffixed by \verb|_|
\item all the subroutine names follow the rule \verb|psb_xxname| where
\verb|xx| can be either:
\begin{itemize}
\item \verb|ds|: the routine is related to dense data,
\item \verb|sp|: the routine is related to sparse data,
\item \verb|cd|: the routine is related to communication descriptor (see~\ref{sec:datastruct}).
\end{itemize}
For example the \verb|psb_dsins|, \verb|psb_spins| and
\verb|psb_cdins| perform the same action (see~\ref{sec:toolsrout}) on
dense matrices, sparse matrices and communication descriptors
respectively.
Interface overloading allows the usage of the same subroutine
interfaces for both real and complex data.
\end{itemize}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
docs/pdf/psbrout.tex
+42 -42
View File
@@ -5,7 +5,7 @@
% DENSE MATRIX SUM
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_axpby}{General Dense Matrix Sum}
\subroutine{psb\_geaxpby}{General Dense Matrix Sum}
This subroutine is an interface to the computational kernel for
dense matrix sum:
@@ -16,8 +16,8 @@ where:
\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}
\syntax{call psb\_geaxpby}{alpha, x, beta, y, desc\_a, info}
\syntax*{call psb\_geaxpby}{alpha, x, beta, y, desc\_a, info, n, jx, jy}
%( calculating y <- alpha*x+beta*y )
\begin{table}[h]
@@ -103,7 +103,7 @@ An integer value that contains an error code.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_dot}{Dot Product}
\subroutine{psb\_gedot}{Dot Product}
This function computes dot product between two vectors $x$ and
$y$.\\
@@ -118,17 +118,17 @@ where:
\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}
\syntax{psb\_gedot}{x, y, desc\_a, info}
\syntax*{psb\_gedot}{x, y, desc\_a, info, jx, jy}
\begin{table}[h]
\begin{center}
\begin{tabular}{ll}
\hline
$dot$, $x$, $y$ & {\bf Function}\\
\hline
Single Precision Real & psb\_dot\\
Long Precision Real & psb\_dot \\
Long Precision Complex & psb\_dot \\
Single Precision Real & psb\_gedot\\
Long Precision Real & psb\_gedot \\
Long Precision Complex & psb\_gedot \\
\hline
\end{tabular}
\end{center}
@@ -184,7 +184,7 @@ An integer value that contains an error code.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_dot}{Generalized Dot Product}
\subroutine{psb\_gedot}{Generalized Dot Product}
This subroutine computes a series of dot products among the columns of
two dense matrices $x$ and $y$:
@@ -194,16 +194,16 @@ 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}
\syntax{psb\_gedot}{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 \\
Single Precision Real & psb\_gedot\\
Long Precision Real & psb\_gedot \\
Long Precision Complex & psb\_gedot \\
\hline
\end{tabular}
\end{center}
@@ -248,7 +248,7 @@ An integer value that contains an error code.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_amax}{Infinity-Norm of Vector}
\subroutine{psb\_geamax}{Infinity-Norm of Vector}
This function computes
the infinity-norm of a vector $x$.\\
@@ -262,8 +262,8 @@ where:
\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}
\syntax{psb\_geamax}{x, desc\_a, info}
\syntax*{psb\_geamax}{x, desc\_a, info, jx}
\begin{table}[h]
\begin{center}
@@ -271,9 +271,9 @@ where:
\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 \\
Single Precision Real&Single Precision Real & psb\_geamax\\
Long Precision Real&Long Precision Real & psb\_geamax \\
Long Precision Real&Long Precision Complex & psb\_zgeamax \\
\hline
\end{tabular}
\end{center}
@@ -317,22 +317,22 @@ An integer value that contains an error code.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_amax}{Generalized Infinity Norm}
\subroutine{psb\_geamax}{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}
\syntax{psb\_geamax}{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\\
Single Precision Real &Single Precision Real & psb\_geamax\\
Long Precision Real &Long Precision Real & psb\_geamax\\
Long Precision Real &Long Precision Complex & psb\_geamax\\
\hline
\end{tabular}
\end{center}
@@ -370,7 +370,7 @@ An integer value that contains an error code.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_asum}{1-Norm of Vector}
\subroutine{psb\_geasum}{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
@@ -383,8 +383,8 @@ where:
\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}
\syntax{psb\_geasum}{x, desc\_a, info}
\syntax*{psb\_geasum}{x, desc\_a, info, jx}
\begin{table}[h]
\begin{center}
@@ -392,9 +392,9 @@ where:
\hline
$dot$, $x$, $y$ & {\bf Function}\\
\hline
Single Precision Real & psb\_asum\\
Long Precision Real & psb\_asum \\
Long Precision Complex & psb\_asum \\
Single Precision Real & psb\_geasum\\
Long Precision Real & psb\_geasum \\
Long Precision Complex & psb\_geasum \\
\hline
\end{tabular}
\end{center}
@@ -440,7 +440,7 @@ An integer value that contains an error code.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine {psb\_nrm2}{2-Norm of Vector}
\subroutine {psb\_genrm2}{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
@@ -459,17 +459,17 @@ where:
\hline
$nrm2$, $x$ & {\bf Function}\\
\hline
Single Precision Real & psb\_nrm2\\
Long Precision Real & psb\_nrm2 \\
Long Precision Complex & psb\_nrm2 \\
Single Precision Real & psb\_genrm2\\
Long Precision Real & psb\_genrm2 \\
Long Precision Complex & psb\_genrm2 \\
\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}
\syntax{psb\_genrm2}{x, desc\_a, info}
\syntax*{psb\_genrm2}{x, desc\_a, info, jx}
\begin{description}
\item[\bf On Entry]
\item[x] the local portion of global dense matrix
@@ -509,7 +509,7 @@ An integer value that contains an error code.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subroutine{psb\_nrmi}{Infinity Norm of Sparse Matrix}
\subroutine{psb\_spnrmi}{Infinity Norm of Sparse Matrix}
This function computes the infinity-norm of a matrix $A$:\\
@@ -525,16 +525,16 @@ where:
\hline
$nrmi$, $A$ & {\bf Function}\\
\hline
Single Precision Real & psb\_nrmi\\
Long Precision Real & psb\_nrmi \\
Long Precision Complex & psb\_nrmi \\
Single Precision Real & psb\_spnrmi\\
Long Precision Real & psb\_spnrmi \\
Long Precision Complex & psb\_spnrmi \\
\hline
\end{tabular}
\end{center}
\caption{Data types\label{tab:f90nrmi}}
\end{table}
\syntax{psb\_nrmi}{A, desc\_a, info}
\syntax{psb\_spnrmi}{A, desc\_a, info}
\begin{description}
\item[\bf On Entry]
docs/pdf/title.tex
+1 -1
View File
@@ -5,7 +5,7 @@
\ifx\pdfoutput\undefined % We're not running pdftex
\else
\pdfbookmark{Title Page}{title}
\pdfbookmark{PSBLAS-v2.0 User's Guide}{title}
\fi
\newlength{\centeroffset}
\setlength{\centeroffset}{-0.5\oddsidemargin}
docs/pdf/toolsrout.tex
+1
View File
@@ -1,4 +1,5 @@
\section{Data management and initialization routines}
\label{sec:toolrout}
%
%% psb_alloc %%
%
docs/pdf/userguide.tex
+4 -4
View File
@@ -1,5 +1,6 @@
\documentclass[12pt,a4paper,twoside]{article}
\usepackage{pstricks}
\usepackage{fancybox}
\usepackage{amsfonts}
% \usepackage{minitoc}
% \setcounter{minitocdepth}{2}
@@ -63,9 +64,9 @@
\newcommand{\example}{\stepcounter{example}%
\section*{\examplename~\theexample}}
\newcommand{\precdata}{\hyperlink{precdata}{{\tt psb\_prec\_data}}}
\newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_data}}}
\newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_data}}}
\newcommand{\precdata}{\hyperlink{precdata}{{\tt psb\_prec\_type}}}
\newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}}
\newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}}
\begin{document}
\include{title}
@@ -82,7 +83,6 @@
\pagenumbering{arabic} % Arabic numbering
\setcounter{page}{1} % Chapters start on page 1
\precdata
\include{intro}
\include{datastruct}
\include{psbrout}