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

psblas2:

Browse Source 
Fixed doc makefile.
This commit is contained in:
Salvatore Filippone
2008-07-24 14:37:58 +00:00
parent 04e648b9f0
commit 8df53e6d20
13 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/Makefile
+388
View File
@@ -0,0 +1,388 @@
## $Id$
##---------------------------------------------------------------------------
## LaTeX Makefile
## Copyright (C) 1996-2001 Michael Forman Michael.Forman@Colorado.EDU
##
## This program is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License
## as published by the Free Software Foundation; either version 2
## of the License, or (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
##
## This copyright applies to this Makefile, and all perl scripts.
## The GPL does NOT apply to the actual content of the paper or thesis.
##---------------------------------------------------------------------------
## 01.Dec,1996 forman Initial Makefile
## 01.Jun,1997 forman Added support for print, preview, and bibtex
## 01.Jan,1998 stones tmp and lib directories to reduce clutter
## 05.Feb,1998 forman Added the following functions:
## .PHONY to prevent errors
## generic TEXFILE definition with following patsubst's
## vpath definitions
## gzip, gunzip, tar, ci
## search for \bibliography in tex file
## conditional ifeq omits bibtex if unnecessary
## documentation added
## 30.Nov,1998 forman Added TOPFILE and SECFILE definitions to support
## texfiles with "input" commands.
## 23.Dec,1998 marshats Added RCSFILES and ci/co capabilites for multiple files
## Now only runs makeindex if $(IDX) file exists.
## 15.Mar,1999 forman Added 'make wc' for papers with word quotas.
## 24.Aug,1999 forman Converted Makefile to use pdftex as the primary
## complier. Now generates true pdf and ps files.
## 09.Feb,2000 forman Simplified the documentation. Removed direct
## compilation of tex into DVI and PS. Conversion
## is done with PDF2PS now.
## 08.Aug,2000 forman Added define for figures directories.
## 18.Aug,2000 forman Removed the redundant code in the $(pdflatex) and
## $(pdflatex-bibtex) definitions by splitting them up
## into several smaller definitions which are called
## from a single set of "if-then" statements.
## 18.Aug,2000 forman Added support for glosstex and makeindex.
## 19.Aug,2000 forman To save space, all files in tmp are now links.
## 19.Aug,2000 forman Removed all postscript commands in favor of pdf.
##---------------------------------------------------------------------------
##
## This Makefile expects the following directory structure:
##
## Makefile This file
## *.tex Put latex files in root directory.
## RCS/ Create an RCS directory for "ci" and "co".
## doc/ Document directory. Includes gpl.txt.
## lib/ Put all cls, sty, idx, gdf, and bib files in lib.
## figures/ Put all figures in the figures directory.
## tmp/ Never put anything in tmp -- it gets cleaned out.
##
##---------------------------------------------------------------------------
##
## Normal Usage:
## make Run pdflatex
## make clean Remove all files in tmp and the pdf link in root.
## make preview Preview the compiled file
## make ci Check in the RCSFILES
## make co Check out the RCSFILES
##
## Advanced Usage:
## make gzip Recursively gzip all the files in the root directory
## make gunzip Reverse the above process
## make tar Tar and gzip the working directory
## make wc Count the number of words in your report
##
##---------------------------------------------------------------------------
## WARNING:
## If "make ci" fails, "make co" will nuke your files!
## Don't put anything in tmp, "make clean" will delete everything!
##---------------------------------------------------------------------------
#
TOPFILE = userguide.tex
HTMLFILE = userhtml.tex
SECFILE = title.tex intro.tex commrout.tex datastruct.tex psbrout.tex toolsrout.tex\
methods.tex precs.tex penv.tex error.tex util.tex
FIGDIR = figures
XPDFFLAGS =
ACROFLAGS = #-- macos
#ACROFLAGS = -geometry 1234x1168+0+0 #-- new-sydney-wide
#ACROFLAGS = -geometry 1000x1000+0+0 #-- sydney-wide
#ACROFLAGS = -geometry 750x1000+0+0 #-- sydney
#ACROFLAGS = -geometry 1200x1200+0+0 #-- home-wide
#ACROFLAGS = -geometry 900x1200+0+0 #-- home
##---------------------------------------------------------------------------
## Change nothing below here (unless you're really really good).
#----------------------------------------------------------------------------
##
## Accounting
#
START = $(shell date)
WDIR = $(notdir $(shell pwd))
DATE = $(shell date +%Y-%m-%d)
##
## Programs
#
LATEX = latex
LTX2HTML = latex2html
PDFLATEX = pdflatex
ACRO = evince
XPDF = xpdf
WC = wc
PDF2PS = pdf2ps
PDF2TEXT = pdftotext
MAKEIDX = makeindex
GLOSSTEX = glosstex
BIBTEX = bibtex
FILTER = ../bin/texfilter
FILTER = cat
CLEANIDX = ../bin/cleanidx
##
## Files
#
TEXFILES = $(TOPFILE) $(SECFILE) $(HTMLFILE)
RCSFILES = $(TEXFILES) Makefile
BASEFILE = $(patsubst %.tex,%,$(TOPFILE))
IDX = $(join $(BASEFILE),.idx)
PDF = $(join $(BASEFILE),.pdf)
PS = $(join $(BASEFILE),.ps)
GXS = $(join $(BASEFILE),.gxs)
GLX = $(join $(BASEFILE),.glx)
TARGETPDF= ../psblas-2.3.pdf
BASEHTML = $(patsubst %.tex,%,$(HTMLFILE))
HTML = $(join $(HTMLFILE),.html)
HTMLDIR = ../html
HTMLFLAGS = -noaddress
FIGURES = $(sort $(wildcard $(FIGDIR)/*))
GLOFILES:= $(sort $(wildcard lib/*.gdf))
GLOFILES:= $(patsubst lib/%,%,$(GLOFILES))
BIBFILES:= $(shell grep ^.bibliography{ $(TOPFILE)|sed "s/,/ /g"|sed "s/%.*//g")
BIBFILES:= $(patsubst \bibliography{%,%,$(BIBFILES))
BIBFILES:= $(patsubst %},%,$(BIBFILES))
BIBFILES:= $(sort $(addsuffix .bib,$(BIBFILES)))
LIBFILES = $(sort $(wildcard lib/*))
TEXLNFIL = $(addprefix $(PWD)/,$(TEXFILES))
#============================================================================
all: pdf html
pdf: $(PDF) copypdf
html: $(HTML)
$(PDF): $(TEXFILES) $(LIBFILES) $(FIGURES) Makefile
$(header)
$(initialize)
$(pdflatex-filter)
ifneq ($(BIBFILES),)
$(bibtex)
$(pdflatex-filter)
endif
ifneq ($(GLOFILES),)
$(glosstex)
$(pdflatex-filter)
endif
# $(makeindex)
$(pdflatex-filter)
$(finish)
copypdf:
/bin/cp -f $(PDF) $(TARGETPDF)
$(HTML): $(TEXFILES) $(LIBFILES) $(FIGURES) Makefile
$(header)
$(initialize)
$(latex-filter)
ifneq ($(BIBFILES),)
$(bibtex)
$(latex-filter)
endif
ifneq ($(GLOFILES),)
$(glosstex)
$(latex-filter)
endif
# $(makeindex)
$(latex-filter)
$(ltx2html-filter)
$(PS): $(PDF)
$(PDF2PS) $< $(PS)
ps: $(PS)
#============================================================================
.PHONY: clean clean-tmp preview print gzip gunzip tar ci
clean:
rm -f $(PDF) $(PS)
cd tmp ; rm -f *
clean-tmp:
cd tmp ; rm -f *
#----------------------------------------------------------------------------
preview: $(PDF)
$(ACRO) $(ACROFLAGS) $< &
xpreview: $(PDF)
$(XPDF) $(XPDFFLAGS) $< &
wc: $(PDF)
$(PDF2TEXT) $< | $(WC)
#----------------------------------------------------------------------------
ci: $(RCSFILES)
$(shell for i in $(RCSFILES) ; do ci -u $$i ; done)
co: $(RCSFILES)
$(shell for i in $(RCSFILES) ; do co -l $$i ; done)
gzip: clean-tmp
gzip -r ./
gunzip Makefile.gz
gunzip:
gunzip -r ./
tar: clean-tmp
cd .. ; \
tar cvf $(WDIR)-$(DATE).tar $(WDIR) ; \
gzip $(WDIR)-$(DATE).tar
info:
$(header)
#============================================================================
define header
@echo
@echo "#---------------------------------------------------------------------"
@echo "MAKEFILE = LaTeX PDF Makefile"
@echo "AUTHOR = Alfredo Buttari"
@echo 'ID = $$Id$ '
@echo "#---------------------------------------------------------------------"
@echo
@echo "ACRO = $(ACRO) $(ACROFLAGS) $(PDF)"
@echo "XPDF = $(XPDF) $(XPDFFLAGS) $(PDF)"
@echo "GV = $(GV) $(GVFLAGS) $(PS)"
@echo "LPR = $(LPR) $(LPRFLAGS) $(PS)"
@echo
@echo "WDIR = $(WDIR)"
@echo "DATE = $(DATE)"
@echo
@echo "TOPFILE = $(TOPFILE)"
@echo "SECFILE = $(SECFILE)"
@echo "TEXFILES = $(TEXFILES)"
@echo "PDF = $(PDF)"
@echo "PS = $(PS)"
@echo "BIBFILES = $(BIBFILES)"
@echo "GLOFILES = $(GLOFILES)"
@echo "IDXFILES = $(IDXFILES)"
@echo
endef
# @echo "FIGURES = $(FIGURES)"
#----------------------------------------------------------------------------
define initialize
@if test ! -d tmp; then mkdir tmp; fi
@ln -sf $(TEXLNFIL) tmp
@ln -sf $(PWD)/lib/* tmp
@ln -sf $(PWD)/$(FIGDIR) tmp
endef
#----------------------------------------------------------------------------
define pdflatex
@echo
@echo "----- pdflatex -------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; $(PDFLATEX) $(TOPFILE)
endef
define latex
@echo
@echo "----- latex -------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; $(LATEX) $(HTMLFILE)
endef
#----------------------------------------------------------------------------
define pdflatex-filter
@echo
@echo "----- pdflatex -------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; ($(PDFLATEX) $(TOPFILE) 2>&1) | $(FILTER)
endef
define latex-filter
@echo
@echo "----- latex -------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; ($(LATEX) $(HTMLFILE) 2>&1) | $(FILTER)
endef
define ltx2html-filter
@echo
@echo "----- latex -------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; ($(LTX2HTML) $(HTMLFLAGS) -dir ../$(HTMLDIR) $(HTMLFILE) 2>&1) | $(FILTER)
endef
#----------------------------------------------------------------------------
define bibtex
@echo
@echo "----- bibtex ---------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; $(BIBTEX) $(BASEFILE)
endef
#----------------------------------------------------------------------------
define glosstex
@echo
@echo "----- glosstex -------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; $(GLOSSTEX) $(BASEFILE) $(GLOFILES)
cd tmp; $(MAKEIDX) $(GXS) -o $(GLX) -s glosstex.ist
endef
#----------------------------------------------------------------------------
define makeindex
@echo
@echo "----- makeindex ------------------------------------------------------"
@echo -n "Starting: "; date
@echo
cd tmp; mv $(IDX) $(IDX)-; $(CLEANIDX) < $(IDX)- > $(IDX)
cd tmp; $(MAKEIDX) $(IDX)
endef
#----------------------------------------------------------------------------
define finish
@ln -sf tmp/$@ .
@echo
@echo "----- finish ---------------------------------------------------------"
@echo -n "Start: "$(START); echo
@echo -n "Finish: "; date
@echo -n "Output: "; ls -l -o tmp/$@
@echo -n "Target: "
endef
define ltx2html-finish
@ln -sf tmp/$@ .
@echo
@echo "----- finish ---------------------------------------------------------"
@echo -n "Start: "$(START); echo
@echo -n "Finish: "; date
@echo -n "Output: "; ls -l -o tmp/$@
@echo -n "Target: "
endef
docs/src/commrout.tex
+553
View File
@@ -0,0 +1,553 @@
\section{Communication routines}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% HALO DATA COMMUNICATION
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The routines in this chapter implement various global communication operators
on vectors associated with a discretization mesh. For auxiliary communication
routines not tied to a discretization space see~\ref{sec:toolsrout}.
\clearpage\subsection*{psb\_halo --- Halo Data Communication}
\addcontentsline{toc}{subsection}{psb\_halo}
These subroutines gathers the values of 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
Integer & psb\_halo \\
Short Precision Real & psb\_halo \\
Long Precision Real & psb\_halo \\
Short Precision Complex & psb\_halo \\
Long Precision Complex & psb\_halo \\
\hline
\end{tabular}
\end{center}
\caption{Data types\label{tab:f90halo}}
\end{table}
\begin{verbatim}
call psb_halo(x, desc_a, info)
call psb_halo(x, desc_a, info, alpha, work, data)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[x] global dense matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf inout}.\\
Specified as: a rank one or two array with the TARGET attribute
containing numbers of type specified in
Table~\ref{tab:f90halo}.
\item[desc\_a] contains data structures for communications.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[alpha] the scalar $\alpha$.\\
Scope: {\bf global} \\
Type: {\bf optional} \\
Intent: {\bf in}.\\
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}\\
Intent: {\bf inout}.\\
Specified as: a rank one array of the same type of $x$ with the
POINTER attribute.
\item[data] index list selector.\\
Scope: {\bf global} \\
Type: {\bf optional} \\
Specified as: an integer. Values:\verb|psb_comm_halo_|,\verb|psb_comm_mov_|,
\verb|psb_comm_ext_|, default: \verb|psb_comm_halo_|. Chooses the
index list on which to base the data exchange.
\item[\bf On Return]
\item[x] global dense result matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf inout}.\\
Returned as: a rank one or two array
containing numbers of type specified in
Table~\ref{tab:f90halo}.
\item[info] the local portion of result submatrix $y$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value that contains an error code.
\end{description}
\begin{figure}[h] \begin{center}
\rotatebox{-90}{\includegraphics[scale=0.45]{figures/try8x8}}
\end{center}
\caption{Sample discretization mesh.\label{fig:try8x8}}
\end{figure}
{\par\noindent\large\bfseries Usage Example}
Consider the discretization mesh depicted in fig.~\ref{fig:try8x8},
partitioned among two processes as shown by the dashed line; the data
distribution is such that each process will own 32 entries in the
index space, with a halo made of 8 entries placed at local indices 33
through 40. If process 0 assigns an initial value of 1 to its entries
in the $x$ vector, and process 1 assigns a value of 2, then after a
call to \verb|psb_halo| the contents of the local vectors will be the
following:
\begin{table}
\begin{center}
\small\begin{tabular}{rrr@{\hspace{6\tabcolsep}}rrr}
\multicolumn{3}{c}{Process 0}&
\multicolumn{3}{c}{Process 1}\\
I & GLOB(I) & X(I) & I & GLOB(I) & X(I) \\
1 & 1 & 1.0 & 1 & 33 & 2.0 \\
2 & 2 & 1.0 & 2 & 34 & 2.0 \\
3 & 3 & 1.0 & 3 & 35 & 2.0 \\
4 & 4 & 1.0 & 4 & 36 & 2.0 \\
5 & 5 & 1.0 & 5 & 37 & 2.0 \\
6 & 6 & 1.0 & 6 & 38 & 2.0 \\
7 & 7 & 1.0 & 7 & 39 & 2.0 \\
8 & 8 & 1.0 & 8 & 40 & 2.0 \\
9 & 9 & 1.0 & 9 & 41 & 2.0 \\
10 & 10 & 1.0 & 10 & 42 & 2.0 \\
11 & 11 & 1.0 & 11 & 43 & 2.0 \\
12 & 12 & 1.0 & 12 & 44 & 2.0 \\
13 & 13 & 1.0 & 13 & 45 & 2.0 \\
14 & 14 & 1.0 & 14 & 46 & 2.0 \\
15 & 15 & 1.0 & 15 & 47 & 2.0 \\
16 & 16 & 1.0 & 16 & 48 & 2.0 \\
17 & 17 & 1.0 & 17 & 49 & 2.0 \\
18 & 18 & 1.0 & 18 & 50 & 2.0 \\
19 & 19 & 1.0 & 19 & 51 & 2.0 \\
20 & 20 & 1.0 & 20 & 52 & 2.0 \\
21 & 21 & 1.0 & 21 & 53 & 2.0 \\
22 & 22 & 1.0 & 22 & 54 & 2.0 \\
23 & 23 & 1.0 & 23 & 55 & 2.0 \\
24 & 24 & 1.0 & 24 & 56 & 2.0 \\
25 & 25 & 1.0 & 25 & 57 & 2.0 \\
26 & 26 & 1.0 & 26 & 58 & 2.0 \\
27 & 27 & 1.0 & 27 & 59 & 2.0 \\
28 & 28 & 1.0 & 28 & 60 & 2.0 \\
29 & 29 & 1.0 & 29 & 61 & 2.0 \\
30 & 30 & 1.0 & 30 & 62 & 2.0 \\
31 & 31 & 1.0 & 31 & 63 & 2.0 \\
32 & 32 & 1.0 & 32 & 64 & 2.0 \\
33 & 33 & 2.0 & 33 & 25 & 1.0 \\
34 & 34 & 2.0 & 34 & 26 & 1.0 \\
35 & 35 & 2.0 & 35 & 27 & 1.0 \\
36 & 36 & 2.0 & 36 & 28 & 1.0 \\
37 & 37 & 2.0 & 37 & 29 & 1.0 \\
38 & 38 & 2.0 & 38 & 30 & 1.0 \\
39 & 39 & 2.0 & 39 & 31 & 1.0 \\
40 & 40 & 2.0 & 40 & 32 & 1.0 \\
\end{tabular}
\end{center}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% OVERLAP UPDATE
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage\subsection*{psb\_ovrl --- Overlap Update}
\addcontentsline{toc}{subsection}{psb\_ovrl}
These subroutines applies an overlap operator to the input vector:
\[ 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
Short Precision Real & psb\_ovrl \\
Long Precision Real & psb\_ovrl \\
Short Precision Complex & psb\_ovrl \\
Long Precision Complex & psb\_ovrl \\
\hline
\end{tabular}
\end{center}
\caption{Data types\label{tab:f90ovrl}}
\end{table}
\begin{verbatim}
call psb_ovrl(x, desc_a, info)
call psb_ovrl(x, desc_a, info, update=update_type, work=work)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[x] global dense matrix $x$.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf inout}.\\
Specified as: a rank one or two array
containing numbers of type specified in
Table~\ref{tab:f90ovrl}.
\item[desc\_a] contains data structures for communications.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[update] Update operator. \\
\begin{description}
\item[update = psb\_none\_] Do nothing;
\item[update = psb\_add\_] Sum overlap entries, i.e. apply $P^T$;
\item[update = psb\_avg\_] Average overlap entries, i.e. apply $P_aP^T$;
%% \item[update = psb\_square\_root\_] square root update $\sqrt{P_a}$;
\end{description}
Scope: {\bf global} \\
Intent: {\bf in}.\\
Default: $update\_type = psb\_avg\_ $\\
Scope: {\bf global} \\
Specified as: a integer variable.
\item[work] the work array. \\
Scope: {\bf local} \\
Type: {\bf optional}\\
Intent: {\bf inout}.\\
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} \\
Intent: {\bf inout}.\\
Specified as: an array of rank one or two
containing numbers of type specified in
Table~\ref{tab:f90ovrl}.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item If there is no overlap in the data distribution associated with
the descriptor, no operations are performed;
\item The operator $P^{T}$ performs the reduction sum of overlap
elements; it is a ``prolongation'' operator $P^T$ 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}
\begin{figure}[h] \begin{center}
\rotatebox{-90}{\includegraphics[scale=0.65]{figures/try8x8_ov}}
\end{center}
\caption{Sample discretization mesh.\label{fig:try8x8_ov}}
\end{figure}
{\par\noindent\large\bfseries Example of use}
Consider the discretization mesh depicted in fig.~\ref{fig:try8x8_ov},
partitioned among two processes as shown by the dashed lines, with an
overlap of 1 extra layer with respect to the partition of
fig.~\ref{fig:try8x8}; the data
distribution is such that each process will own 40 entries in the
index space, with an overlap of 16 entries placed at local indices 25
through 40; the halo will run from local index 41 through local index 48.. If process 0 assigns an initial value of 1 to its entries
in the $x$ vector, and process 1 assigns a value of 2, then after a
call to \verb|psb_ovrl| with \verb|psb_avg_| and a call to
\verb|psb_halo_| the contents of the local vectors will be the
following (showing a transition among the two subdomains)
\begin{table}
\begin{center}
\footnotesize
\begin{tabular}{rrr@{\hspace{6\tabcolsep}}rrr}
\multicolumn{3}{c}{Process 0}&
\multicolumn{3}{c}{Process 1}\\
I & GLOB(I) & X(I) & I & GLOB(I) & X(I) \\
1 & 1 & 1.0 & 1 & 33 & 1.5 \\
2 & 2 & 1.0 & 2 & 34 & 1.5 \\
3 & 3 & 1.0 & 3 & 35 & 1.5 \\
4 & 4 & 1.0 & 4 & 36 & 1.5 \\
5 & 5 & 1.0 & 5 & 37 & 1.5 \\
6 & 6 & 1.0 & 6 & 38 & 1.5 \\
7 & 7 & 1.0 & 7 & 39 & 1.5 \\
8 & 8 & 1.0 & 8 & 40 & 1.5 \\
9 & 9 & 1.0 & 9 & 41 & 2.0 \\
10 & 10 & 1.0 & 10 & 42 & 2.0 \\
11 & 11 & 1.0 & 11 & 43 & 2.0 \\
12 & 12 & 1.0 & 12 & 44 & 2.0 \\
13 & 13 & 1.0 & 13 & 45 & 2.0 \\
14 & 14 & 1.0 & 14 & 46 & 2.0 \\
15 & 15 & 1.0 & 15 & 47 & 2.0 \\
16 & 16 & 1.0 & 16 & 48 & 2.0 \\
17 & 17 & 1.0 & 17 & 49 & 2.0 \\
18 & 18 & 1.0 & 18 & 50 & 2.0 \\
19 & 19 & 1.0 & 19 & 51 & 2.0 \\
20 & 20 & 1.0 & 20 & 52 & 2.0 \\
21 & 21 & 1.0 & 21 & 53 & 2.0 \\
22 & 22 & 1.0 & 22 & 54 & 2.0 \\
23 & 23 & 1.0 & 23 & 55 & 2.0 \\
24 & 24 & 1.0 & 24 & 56 & 2.0 \\
25 & 25 & 1.5 & 25 & 57 & 2.0 \\
26 & 26 & 1.5 & 26 & 58 & 2.0 \\
27 & 27 & 1.5 & 27 & 59 & 2.0 \\
28 & 28 & 1.5 & 28 & 60 & 2.0 \\
29 & 29 & 1.5 & 29 & 61 & 2.0 \\
30 & 30 & 1.5 & 30 & 62 & 2.0 \\
31 & 31 & 1.5 & 31 & 63 & 2.0 \\
32 & 32 & 1.5 & 32 & 64 & 2.0 \\
33 & 33 & 1.5 & 33 & 25 & 1.5 \\
34 & 34 & 1.5 & 34 & 26 & 1.5 \\
35 & 35 & 1.5 & 35 & 27 & 1.5 \\
36 & 36 & 1.5 & 36 & 28 & 1.5 \\
37 & 37 & 1.5 & 37 & 29 & 1.5 \\
38 & 38 & 1.5 & 38 & 30 & 1.5 \\
39 & 39 & 1.5 & 39 & 31 & 1.5 \\
40 & 40 & 1.5 & 40 & 32 & 1.5 \\
41 & 41 & 2.0 & 41 & 17 & 1.0 \\
42 & 42 & 2.0 & 42 & 18 & 1.0 \\
43 & 43 & 2.0 & 43 & 19 & 1.0 \\
44 & 44 & 2.0 & 44 & 20 & 1.0 \\
45 & 45 & 2.0 & 45 & 21 & 1.0 \\
46 & 46 & 2.0 & 46 & 22 & 1.0 \\
47 & 47 & 2.0 & 47 & 23 & 1.0 \\
48 & 48 & 2.0 & 48 & 24 & 1.0 \\
\end{tabular}
\end{center}
\end{table}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% GATHER GLOBAL DENSE MATRIX
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage\subsection*{psb\_gather --- Gather Global Dense Matrix}
\addcontentsline{toc}{subsection}{psb\_gather}
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_{1:m,1:n}$
\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
Integer & psb\_gather \\
Short Precision Real & psb\_gather \\
Long Precision Real & psb\_gather \\
Short Precision Complex & psb\_gather \\
Long Precision Complex & psb\_gather \\
\hline
\end{tabular}
\end{center}
\caption{Data types\label{tab:gather}}
\end{table}
\begin{verbatim}
call psb_gather(glob_x, loc_x, desc_a, info, root)
call psb_gather(glob_x, loc_x, desc_a, info, root)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[loc\_x] the local portion of global dense matrix
$glob\_x$. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
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}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\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}\\
Intent: {\bf in}.\\
Specified as: an integer variable $-1\le root\le np-1$, default $-1$.
%% \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}\\
Intent: {\bf out}.\\
Specified as: a rank one or two array.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
\end{description}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% SCATTER GLOBAL DENSE MATRIX
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage\subsection*{psb\_scatter --- Scatter Global Dense Matrix}
\addcontentsline{toc}{subsection}{psb\_scatter}
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) \]
where:
\begin{description}
\item[$glob\_x$] is the global matrix $glob\_x_{1:m,1:n}$
\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
Integer & psb\_scatter \\
Short Precision Real & psb\_scatter \\
Long Precision Real & psb\_scatter \\
Short Precision Complex & psb\_scatter \\
Long Precision Complex & psb\_scatter \\
\hline
\end{tabular}
\end{center}
\caption{Data types\label{tab:scatter}}
\end{table}
\begin{verbatim}
call psb_scatter(glob_x, loc_x, desc_a, info, root)
call psb_scatter(glob_x, loc_x, desc_a, info, root)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[glob\_x] The array that must be scattered into local pieces.\\
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a rank one or two array.
\item[desc\_a] contains data structures for communications.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[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}\\
Intent: {\bf in}.\\
Specified as: an integer variable $-1\le root\le np-1$, default $-1$.
%% \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}\\
Intent: {\bf out}.\\
Specified as: a rank one or two array containing numbers of the type
indicated in Table~\ref{tab:scatter}.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
\end{description}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/datastruct.tex
+690
View File
@@ -0,0 +1,690 @@
\section{Data Structures}
\label{sec:datastruct}
%\ifthenelse{\boolean{mtc}}{\minitoc}{}
In this chapter we illustrate the data structures used for definition of
routines interfaces. They include data structures for sparse matrices,
communication descriptors and preconditioners.%% These data structures
%% are used for calling PSBLAS routines in Fortran~90 language and will
%% be used to next chapters containing these callings.
All the data types and the basic subroutine interfaces are defined in
the module \verb|psb_base_mod|; this will have to be included by every
user subroutine that makes use of the library.
Real and complex data types are parametrized with a kind type defined
in the library as follows:
\begin{description}
\item[psb\_spk\_] Kind parameter for short precision real and complex
data; corresponds to a \verb|REAL| declaration and is
normally 4 bytes.
\item[psb\_dpk\_] Kind parameter for long precision real and complex
data; corresponds to a \verb|DOUBLE PRECISION| declaration and is
normally 8 bytes.
\end{description}
\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 \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.
It is not necessary for the user to know the internal structure of
\verb|psb_desc_type|, it is set in a transparent mode by the tools
routines of Sec.~\ref{sec:toolsrout}, and its fields may be accessed
if necessary via the routines of sec.~\ref{sec:dataquery};
nevertheless we include a description for the curious
reader:
\begin{description}
\item[{\bf matrix\_data}] includes general information about matrix and
process grid, such as the communication context, the size of the
global matrix, the size of the portion of matrix stored on the current
process, and so on. %% 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
%% associated with the processes comprised in the virtual parallel
%% machine (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: an allocatable integer array of dimension \verb|psb_mdata_size_|.
\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: an allocatable integer array of rank one.
\item[{\bf ext\_index}] A list of element indices to be exchanged to
implement the mapping between a base descriptor and a descriptor
with overlap.
\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: an allocatable integer array of rank one.
\item [{\bf ovr\_mst\_idx}] A list to retrieve the value of each
overlap element from the respective master process.\\
Specified as: an allocatable integer array of rank one.
\item [{\bf ovrlap\_elem}] For all overlap points belonging to th
ecurrent process:
\begin{enumerate}
\item Overlap point index;
\item Number of processes sharing that overlap points;
\item Index of a ``master'' process:
\end{enumerate}
Specified as: an allocatable integer array of rank two.
\item[{\bf loc\_to\_glob}] each element $i$ of this array contains
global identifier of the local variable $i$.\\
Specified as: an allocatable integer array of rank one.
\item[{\bf glob\_to\_loc, glb\_lc, hashv}] Contain a mapping from
global to local indices.
\end{description}
The Fortran~95 definition for \verb|psb_desc_type| structures is
as follows:
\begin{figure}[h!]
\begin{Sbox}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type psb_desc_type
integer, allocatable :: matrix_data(:), halo_index(:)
integer, allocatable :: ext_index(:)
integer, allocatable :: ovrlap_elem(:,:)
integer, allocatable :: ovrlap_index(:)
integer, allocatable :: ovr_mst_idx(:)
integer, allocatable :: loc_to_glob(:), glob_to_loc(:)
integer, allocatable :: hashv(:), glb_lc(:,:)
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}
A communication descriptor associated with a sparse matrix has a
state, which can take the following values:
\begin{description}
\item[Build:] State entered after the first allocation, and before the
first assembly; in this state it is possible to add communication
requirements among different processes.
\item[Assembled:] State entered after the assembly; computations using
the associated sparse matrix, such as matrix-vector products, are
only possible in this state.
\end{description}
The global to local index mapping may be stored in two different
formats: the first is simpler but more expensive, as it requires on
each process an amount of memory proportional to the global size of
the index space; the second is more complex, but only requires memory
proportional to the local index space size. The choice is made at the
time of the initialization according to a threshold; this threshold
may be queried and set using the functions in
sec.~\ref{sec:dataquery}.
\subsubsection{Named Constants}
\label{sec:cd_constants}
\begin{description}
\item[psb\_none\_] Generic no-op;
\item[psb\_nohalo\_] Do not fetch halo elements;
\item[psb\_halo\_] Fetch halo elements from neighbouring processes;
\item[psb\_sum\_] Sum overlapped elements
\item[psb\_avg\_] Average overlapped elements
\item[psb\_comm\_halo\_] Exchange data based on the \verb|halo_index|
list;
\item[psb\_comm\_ext\_] Exchange data based on the \verb|ext_index|
list;
\item[psb\_comm\_ovr\_] Exchange data based on the \verb|ovrlap_index|
list;
\item[psb\_comm\_mov\_] Exchange data based on the \verb|ovr_mst_idx|
list;
%% \item[psb\_square\_root\_] Update with the square root of the average
%% of overlapped elements;
%% \item[psb\_dec\_type\_] Entry holding decomposition type (in \verb|desc_a%matrix_data|)
%% \item[psb\_m\_] Entry holding total number of rows
%% \item[psb\_n\_] Entry holding total number of columns
%% \item[ psb\_n\_row\_] Entry holding the number of rows stored in the
%% current process
%% \item[psb\_n\_col\_] Entry holding the number of columns stored in the
%% current process
%% \item[psb\_ctxt\_] Entry holding a copy of the BLACS communication context
%% \item[psb\_desc\_asb\_] State of the descriptor: assembled,
%% i.e. suitable for computational tasks.
%% \item[psb\_desc\_bld\_] State of the descriptor: build, must be
%% assembled before computational use.
\end{description}
\subsection{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. Most of these fields are set by the tools
routines when inserting a new sparse matrix; the user needs only
choose, if he/she so whishes, a specific matrix storage mode. \\
\begin{description}
\item[{\bf aspk}] Contains values of the local distributed sparse
matrix.\\
Specified as: an allocatable 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: an allocatable 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: an allocatable 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: an 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: an allocatable 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: an allocatable 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}
The Fortran~95 interface for distributed sparse matrices containing
double precision real entries is defined as shown in
figure~\ref{fig:spmattype}. The definitions for single precision and
complex data are identical except for the \verb|real| declaration and
for the kind type parameter.
\begin{figure}[h!]
\begin{Sbox}
\begin{minipage}[tl]{0.85\textwidth}
\begin{verbatim}
type psb_sspmat_type
integer :: m, k
character :: fida(5)
character :: descra(10)
integer :: infoa(psb_ifa_size_)
real(psb_spk_), allocatable :: aspk(:)
integer, allocatable :: ia1(:), ia2(:)
integer, allocatable :: pr(:), pl(:)
end type psb_sspmat_type
type psb_dspmat_type
integer :: m, k
character :: fida(5)
character :: descra(10)
integer :: infoa(psb_ifa_size_)
real(psb_dpk_), allocatable :: aspk(:)
integer, allocatable :: ia1(:), ia2(:)
integer, allocatable :: pr(:), pl(:)
end type psb_dspmat_type
type psb_cspmat_type
integer :: m, k
character :: fida(5)
character :: descra(10)
integer :: infoa(psb_ifa_size_)
complex(psb_spk_), allocatable :: aspk(:)
integer, allocatable :: ia1(:), ia2(:)
integer, allocatable :: pr(:), pl(:)
end type psb_cspmat_type
type psb_zspmat_type
integer :: m, k
character :: fida(5)
character :: descra(10)
integer :: infoa(psb_ifa_size_)
complex(psb_dpk_), allocatable :: aspk(:)
integer, allocatable :: ia1(:), ia2(:)
integer, allocatable :: pr(:), pl(:)
end type psb_zspmat_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}
Our base library offers support for simple well known preconditioners
like Diagonal Scaling or Block Jacobi with incomplete
factorization ILU(0).
A preconditioner is held in the \hypertarget{precdata}{{\tt
psb\_prec\_type}} data structure reported in
figure~\ref{fig:prectype}. The \verb|psb_prec_type|
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_precbld| subroutine.
%% This data structure wants to be flexible enough to easily allow the
%% implementation of new kind of preconditioners.
The values contained in
the \verb|iprcparm| and \verb|rprcparm| define tha type of
preconditioner along with all the parameters related to it; thus,
\verb|iprcparm| and \verb|rprcparm| define how the other records have
to be interpreted. This data structure is the basis of more complex
preconditioning strategies, which are the subject of further
research.
\begin{figure}[h!]
\small
\begin{Sbox}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type psb_sprec_type
type(psb_sspmat_type), allocatable :: av(:)
real(psb_spk_), allocatable :: d(:)
type(psb_desc_type) :: desc_data
integer, allocatable :: iprcparm(:)
real(psb_spk_), allocatable :: rprcparm(:)
integer, allocatable :: perm(:), invperm(:)
integer :: prec, base_prec
end type psb_sprec_type
type psb_dprec_type
type(psb_dspmat_type), allocatable :: av(:)
real(psb_dpk_), allocatable :: d(:)
type(psb_desc_type) :: desc_data
integer, allocatable :: iprcparm(:)
real(psb_dpk_), allocatable :: rprcparm(:)
integer, allocatable :: perm(:), invperm(:)
integer :: prec, base_prec
end type psb_dprec_type
type psb_cprec_type
type(psb_cspmat_type), allocatable :: av(:)
complex(psb_spk_), allocatable :: d(:)
type(psb_desc_type) :: desc_data
integer, allocatable :: iprcparm(:)
real(psb_spk_), allocatable :: rprcparm(:)
integer, allocatable :: perm(:), invperm(:)
integer :: prec, base_prec
end type psb_cprec_type
type psb_zprec_type
type(psb_zspmat_type), allocatable :: av(:)
complex(psb_dpk_), allocatable :: d(:)
type(psb_desc_type) :: desc_data
integer, allocatable :: iprcparm(:)
real(psb_dpk_), allocatable :: rprcparm(:)
integer, allocatable :: perm(:), invperm(:)
integer :: prec, base_prec
end type psb_zprec_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}
%% \subsection{Named Constants}
%% \label{sec:prec_constants}
%% \begin{description}
%% \item[f\_ilu\_n\_] Incomplete LU factorization with $n$ levels of
%% fill-in; currently only $n=0$ is implemented;
%% \item[f\_slu\_] Sparse factorization using SuperLU;
%% \item[f\_umf\_] Sparse factorization using UMFPACK;
%% \item[add\_ml\_prec\_] Additive multilevel correction;
%% \item[mult\_ml\_prec\_] Multiplicative multilevel correction;
%% \item[pre\_smooth\_] Pre-smoothing in applying multiplicative
%% multilevel corrections;
%% \item[post\_smooth\_] Post-smoothing in applying multiplicative
%% multilevel corrections;
%% \item[smooth\_both\_] Two-sided (i.e. symmetric) smoothing in applying multiplicative
%% multilevel corrections;
%% \item[mat\_distr\_] Coarse matrix distributed among processes
%% \item[mat\_repl\_] Coarse matrix replicated among processes
%% \end{description}
\subsection{Data structure query routines}
\label{sec:dataquery}
\subsubsection*{psb\_cd\_get\_local\_rows --- Get number of local rows}
\addcontentsline{toc}{subsubsection}{psb\_cd\_get\_local\_rows }
\begin{verbatim}
nr = psb_cd_get_local_rows(desc)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[desc] the communication descriptor.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of local rows, i.e. the number of
rows owned by the current process; as explained in~\ref{sec:intro},
it is equal to $|{\cal I}_i| + |{\cal B}_i|$. The returned value is
specific to the calling process.
\end{description}
\subsubsection*{psb\_cd\_get\_local\_cols --- Get number of local cols}
\addcontentsline{toc}{subsubsection}{psb\_cd\_get\_local\_cols }
\begin{verbatim}
nc = psb_cd_get_local_cols(desc)
\end{verbatim}
\begin{description}
\item[\bf On Entry]
\item[Type:] Asynchronous.
\item[desc] the communication descriptor.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of local cols, i.e. the number of
indices used by the current process, including both local and halo
indices; as explained in~\ref{sec:intro},
it is equal to $|{\cal I}_i| + |{\cal B}_i| +|{\cal H}_i|$. The
returned value is specific to the calling process.
\end{description}
\subsubsection*{psb\_cd\_get\_global\_rows --- Get number of global rows}
\addcontentsline{toc}{subsubsection}{psb\_cd\_get\_global\_rows }
\begin{verbatim}
nr = psb_cd_get_global_rows(desc)
\end{verbatim}
\begin{description}
\item[\bf On Entry]
\item[Type:] Asynchronous.
\item[desc] the communication descriptor.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of global rows in the mesh
\end{description}
\subsubsection*{psb\_cd\_get\_global\_cols --- Get number of global cols}
\addcontentsline{toc}{subsubsection}{psb\_cd\_get\_global\_cols }
\begin{verbatim}
nr = psb_cd_get_global_cols(desc)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[desc] the communication descriptor.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of global cols in the mesh
\end{description}
\subsubroutine{psb\_cd\_get\_context}{Get communication context}
\begin{verbatim}
ictxt = psb_cd_get_context(desc)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[desc] the communication descriptor.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The communication context.
\end{description}
\subsubsection*{psb\_cd\_get\_large\_threshold --- Get threshold for
index mapping switch}
\addcontentsline{toc}{subsubsection}{psb\_cd\_get\_large\_threshold}
\begin{verbatim}
ith = psb_cd_get_large_threshold()
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Return]
\item[Function value] The current value for the size threshold.
\end{description}
\subsubsection*{psb\_cd\_set\_large\_threshold --- Set threshold for
index mapping switch}
\addcontentsline{toc}{subsubsection}{psb\_cd\_set\_large\_threshold}
\begin{verbatim}
call psb_cd_set_large_threshold(ith)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[ith] the new threshold for communication descriptors.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value greater than zero.
\end{description}
Note: the threshold value is only queried by the library at the time a
call to \verb|psb_cdall| is executed, therefore changing the threshold
has no effect on communication descriptors that have already been initialized.
\subsubsection*{psb\_sp\_get\_nrows --- Get number of rows in a sparse
matrix}
\addcontentsline{toc}{subsubsection}{ psb\_sp\_get\_nrows}
\begin{verbatim}
nr = psb_sp_get_nrows(a)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[a] the sparse matrix\\
Scope: {\bf local}\\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of rows of sparse matrix \verb|a|.
\end{description}
\subsubsection*{psb\_sp\_get\_ncols --- Get number of columns in a
sparse matrix}
\addcontentsline{toc}{subsubsection}{psb\_sp\_get\_ncols}
\begin{verbatim}
nr = psb_sp_get_ncols(a)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[a] the sparse matrix\\
Scope: {\bf local}\\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of columns of sparse matrix \verb|a|.
\end{description}
\subsubsection*{psb\_sp\_get\_nnzeros --- Get number of nonzero elements
in a sparse matrix}
\addcontentsline{toc}{subsubsection}{psb\_sp\_get\_nnzeros}
\begin{verbatim}
nr = psb_sp_get_nnzeros(a)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[a] the sparse matrix\\
Scope: {\bf local}\\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\end{description}
\begin{description}
\item[\bf On Return]
\item[Function value] The number of nonzero elements stored in sparse matrix \verb|a|.
\end{description}
{\par\noindent\bfseries Notes}
\begin{enumerate}
\item The function value is specific to the storage format of matrix
\verb|a|; some storage formats employ padding, thus the returned
value for the same matrix may be different for different storage choices.
\end{enumerate}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/error.tex
+237
View File
@@ -0,0 +1,237 @@
\section{Error handling}
The PSBLAS library error handling policy has been completely rewritten
in version 2.0. The idea behind the design of this new error handling
strategy is to keep error messages on a stack allowing the user to
trace back up to the point where the first error message has been
generated. Every routine in the PSBLAS-2.0 library has, as last
non-optional argument, an integer \verb|info| variable; whenever,
inside the routine, an error is detected, this variable is set to a
value corresponding to a specific error code. Then this error code is
also pushed on the error stack and then either control is returned to
the caller routine or the execution is aborted, depending on the users
choice. At the time when the execution is aborted, an error message is
printed on standard output with a level of verbosity than can be
chosen by the user. If the execution is not aborted, then, the caller
routine checks the value returned in the \verb|info| variable and, if
not zero, an error condition is raised. This process continues on all the
levels of nested calls until the level where the user decides to abort
the program execution.
Figure~\ref{fig:routerr} shows the layout of a generic \verb|psb_foo|
routine with respect to the PSBLAS-2.0 error handling policy. It is
possible to see how, whenever an error condition is detected, the
\verb|info| variable is set to the corresponding error code which is,
then, pushed on top of the stack by means of the
\verb|psb_errpush|. An error condition may be directly detected inside
a routine or indirectly checking the error code returned returned by a
called routine. Whenever an error is encountered, after it has been
pushed on stack, the program execution skips to a point where the
error condition is handled; the error condition is handled either by
returning control to the caller routine or by calling the
\verb|psb\_error| routine which prints the content of the error stack
and aborts the program execution, according to the choice made by the
user with \verb|psb_set_erraction|. The default is to print the error
and terminate the program, but the user may choose to handle the error
explicitly.
\begin{figure}[h!]
\begin{Sbox}
\begin{minipage}[tl]{0.95\textwidth}
\small
\begin{verbatim}
subroutine psb_foo(some args, info)
...
if(error detected) then
info=errcode1
call psb_errpush('psb_foo', errcode1)
goto 9999
end if
...
call psb_bar(some args, info)
if(info .ne. zero) then
info=errcode2
call psb_errpush('psb_foo', errcode2)
goto 9999
end if
...
9999 continue
if (err_act .eq. act_abort) then
call psb_error(icontxt)
return
else
return
end if
end subroutine psb_foo
\end{verbatim}
\end{minipage}
\end{Sbox}
\setlength{\fboxsep}{8pt}
\begin{center}
\fbox{\TheSbox}
\end{center}
\caption{\label{fig:routerr}The layout of a generic \texttt{psb\_foo}
routine with respect to PSBLAS-2.0 error handling policy.}
\end{figure}
Figure~\ref{fig:errormsg} reports a sample error message generated by
the PSBLAS-2.0 library. This error has been generated by the fact that
the user has chosen the invalid ``FOO'' storage format to represent
the sparse matrix. From this error message it is possible to see that
the error has been detected inside the \verb|psb_cest| subroutine
called by \verb|psb_spasb| ... by process 0 (i.e. the root process).
\begin{figure}[h!]
\begin{Sbox}
\begin{minipage}[tl]{0.95\textwidth}
\begin{verbatim}
==========================================================
Process: 0. PSBLAS Error (4010) in subroutine: df_sample
Error from call to subroutine mat dist
==========================================================
Process: 0. PSBLAS Error (4010) in subroutine: mat_distv
Error from call to subroutine psb_spasb
==========================================================
Process: 0. PSBLAS Error (4010) in subroutine: psb_spasb
Error from call to subroutine psb_cest
==========================================================
Process: 0. PSBLAS Error (136) in subroutine: psb_cest
Format FOO is unknown
==========================================================
Aborting...
\end{verbatim}
\end{minipage}
\end{Sbox}
\setlength{\fboxsep}{8pt}
\begin{center}
\fbox{\TheSbox}
\end{center}
\caption{\label{fig:errormsg}A sample PSBLAS-2.0 error
message. Process 0 detected an error condition inside the {\textrm
psb\_cest} subroutine}
\end{figure}
\clearpage\subsection*{psb\_errpush --- Pushes an error code onto the error
stack}
\addcontentsline{toc}{subsection}{psb\_errpush}
\begin{verbatim}
call psb_errpush(err_c, r_name, i_err, a_err)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[err\_c] the error code\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer.
\item[r\_name] the soutine where the error has been caught.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a string.\\
\item[i\_err] addional info for error code\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Specified as: an integer array\\
\item[a\_err] addional info for error code\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Specified as: a string.\\
\end{description}
\clearpage\subsection*{psb\_error --- Prints the error stack content and aborts
execution}
\addcontentsline{toc}{subsection}{psb\_error}
\begin{verbatim}
call psb_error(icontxt)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[icontxt] the communication context.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: an integer.
\end{description}
\clearpage\subsection*{psb\_set\_errverbosity --- Sets the verbosity of error
messages.}
\addcontentsline{toc}{subsection}{psb\_set\_errverbosity}
\begin{verbatim}
call psb_set_errverbosity(v)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[v] the verbosity level\\
Scope: {\bf global}\\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer.
\end{description}
\clearpage\subsection*{psb\_set\_erraction --- Set the type of action to be
taken upon error condition.}
\addcontentsline{toc}{subsection}{psb\_set\_erraction}
\begin{verbatim}
call psb_set_erraction(err_act)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[err\_act] the type of action.\\
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer. Possible values: \verb|psb_act_ret|,
\verb|psb_act_abort|.
\end{description}
%% \clearpage\subsection*{psb\_errcomm --- Error communication routine}
%\addcontentsline{toc}{subsection}{psb\_errcomm}
\begin{verbatim}
call psb_errcomm(icontxt, err)
\end{verbatim}
%% \begin{description}
%% \item[\bf On Entry]
%% \item[icontxt] the communication context.\\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Intent: {\bf in}.\\
%% Specified as: an integer.
%% \item[err] the error code to be communicated\\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Intent: {\bf inout}.\\
%% Specified as: an integer.\\
%% \end{description}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/intro.tex
+428
View File
@@ -0,0 +1,428 @@
\section{Introduction}\label{sec:intro}
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.
The PSBLAS library is internally implemented in
the Fortran~95~\cite{metcalf} programming language, with reuse and/or
adaptation of some existing Fortran~77 software, and a handful of C
routines.
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.
In the current release we rely on the availability of the so-called
allocatable extensions, specified in TR~15581. Strictly speaking they
are outside the Fortran~95 standard; however they have been included
in the Fortran~2003 language standard, and are available in
practically all Fortran~95 compilers on the market, including the GNU
Fortran compiler from the Free Software Foundation (as of version 4.2).
The presentation of the
PSBLAS library follows the general structure of the proposal for
serial Sparse BLAS~\cite{sblas97,sblas02}, 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 document will be discussed referring
to a finite difference discretization of a Partial Differential
Equation (PDE). 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 solutions to these problems and other important
inputs to the development of the PSBLAS software package have 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. 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.
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.
In any case we provide wrappers around the BLACS routines so that the
user does not need to delve into their details (see Sec.~\ref{sec:parenv}).
%% We assume that the user program has initialized a BLACS process grid
%% with one column and as many rows as there are processes; the PSBLAS
%% initialization routines will take the communication context for this
%% grid and store internally for further use.
\begin{figure}[h] \begin{center}
\rotatebox{-90}{\includegraphics[scale=0.65]{figures/psblas}}
\end{center}
\caption{PSBLAS library components hierarchy.\label{fig:psblas}}
\end{figure}
The type of linear system matrices that we address typically arise in the
numerical solution of PDEs; in such a context,
it is necessary to pay special attention to the
structure of the problem from which the application originates.
The nonzero pattern of a matrix arising from the
discretization of a PDE is influenced by various factors, such as the
shape of the domain, the discretization strategy, and
the equation/unknown ordering. The matrix itself can be interpreted as
the adjacency matrix of the graph associated with the discretization
mesh.
The distribution of the coefficient matrix for the linear system is
based on the ``owner computes'' rule:
the variable associated to each mesh point is assigned to a process
that will own the corresponding row in the coefficient matrix and
will carry out all related computations. This allocation strategy
is equivalent to a partition of the discretization mesh into {\em
sub-domains}.
Our library supports any distribution that keeps together
the coefficients of each matrix row; there are no other constraints on
the variable assignment.
This choice is consistent with data distributions commonly used in
ScaLAPACK such as \verb|CYCLIC(N)| and \verb|BLOCK|,
as well as completely arbitrary assignments of
equation indices to processes. In particular it is consistent with the
usage of graph partitioning tools commonly available in the
literature, e.g. METIS~\cite{METIS}.
Dense vectors conform to sparse
matrices, that is, the entries of a vector follow the same distribution
of the matrix rows.
We assume that the sparse matrix is built in parallel, where each
process generates its own portion. We never require that the entire
matrix be available on a single node. However, it is possible
to hold the entire matrix in one process and distribute it
explicitly\footnote{In our prototype implementation we provide
sample scatter/gather routines.}, even though the resulting
bottleneck would make this option unattractive in most cases.
\subsection{Basic Nomenclature}
Our computational model implies that the data allocation on the
parallel distributed memory machine is guided by the structure of the
physical model, and specifically by the discretization mesh of the
PDE.
Each point of the discretization mesh will have (at least) one
associated equation/variable, and therefore one index. We say that
point $i$ {\em depends\/} on point $j$ if the equation for a
variable associated with $i$ contains a term in $j$, or equivalently
if $a_{ij} \ne0$.
After the partition of the discretization mesh into {\em sub-domains\/}
assigned to the parallel processes,
we classify the points of a given sub-domain as following.
\begin{description}
\item[Internal.] An internal point of
a given domain {\em depends} only on points of the
same domain.
If all points of a domain are assigned to one
process, then a computational step (e.g., a
matrix-vector product) of the
equations associated with the internal points requires no data
items from other domains and no communications.
\item[Boundary.] A point of
a given domain is a boundary point if it {\em depends} on points
belonging to other domains.
\item[Halo.] A halo point for a given domain is a point belonging to
another domain such that there is a boundary point which {\em depends\/}
on it. Whenever performing a computational step, such as a
matrix-vector product, the values associated with halo points are
requested from other domains. A boundary point of a given
domain is usually a halo point for some other domain\footnote{This is
the normal situation when the pattern of the sparse matrix is
symmetric, which is equivalent to say that the interaction between
two variables is reciprocal. If the matrix pattern is non-symmetric
we may have one-way interactions, and these could cause a situation
in which a boundary point is not a halo point for its neighbour.}; therefore
the cardinality of the boundary points set denotes the amount of data
sent to other domains.
\item[Overlap.] An overlap point is a boundary point assigned to
multiple domains. Any operation that involves an overlap point
has to be replicated for each assignment.
\end{description}
Overlap points do not usually exist in the basic data
distributions; however they are a feature of Domain Decomposition
Schwarz preconditioners which are the subject of related research
work~\cite{2007c,2007d}.
We denote the sets of internal, boundary and halo points for a given
subdomain by $\cal I$, $\cal B$ and $\cal H$.
Each subdomain is assigned to one process; each process usually
owns one subdomain, although the user may choose to assign more than
one subdomain to a process. If each process $i$ owns one
subdomain, the number of rows in the local sparse matrix is
$|{\cal I}_i| + |{\cal B}_i|$, and the number of local columns
(i.e. those for which there exists at least one non-zero entry in the
local rows) is $|{\cal I}_i| + |{\cal B}_i| +|{\cal H}_i|$.
\begin{figure}[h]
\begin{center}
\rotatebox{-90}{\includegraphics[scale=0.65]{figures/points}}
\end{center}
\caption{Point classfication.\label{fig:points}}
\end{figure}
This classification of mesh points guides the naming scheme that we
adopted in the library internals and in the data structures. We
explicitly note that ``Halo'' points are also often called ``ghost''
points in the literature.
\subsection{Library contents}
The PSBLAS library consists of various classes of subroutines:
\begin{description}
\item[Computational routines] comprising:
\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}
\item[Communication routines] handling halo and overlap
communications;
\item[Data management and auxiliary routines] including:
\begin{itemize}
\item Parallel environment management
\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}
\item[Preconditioner routines]
\item[Iterative methods] a subset of Krylov subspace iterative
methods
\end{description}
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|ge|: 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_geins|, \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}
In the description of the subroutines, arguments or argument entries
are classified as:
\begin{description}
\item[global] For input arguments, the value must be the same on all processes
participating in the subroutine call; for output arguments the value
is guaranteed to be the same.
\item[local] Each process has its own value(s) independently.
\end{description}
\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 an 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.
A simple application structure will walk through the index space
allocation, matrix/vector creation and linear system solution as
follows:
\begin{enumerate}
\item Initialize parallel environment with \verb|psb_init|
\item Initialize index space with \verb|psb_cdall|
\item Allocate sparse matrix and dense vectors with \verb|psb_spall|
and \verb|psb_geall|
\item Loop over all local rows, generate matrix and vector entries,
and insert them with \verb|psb_spins| and \verb|psb_geins|
\item Assemble the various entities:
\begin{enumerate}
\item \verb|psb_cdasb|
\item \verb|psb_spasb|
\item \verb|psb_geasb|
\end{enumerate}
\item Choose the preconditioner to be used with \verb|psb_precset| and
build it with \verb|psb_precbld|
\item Call the iterative method of choice, e.g. \verb|psb_bicgstab|
\end{enumerate}
This is the structure of the sample program
\verb|test/pargen/ppde90.f90|.
For a simulation in which the same discretization mesh is used over
multiple time steps, the following structure may be more appropriate:
\begin{enumerate}
\item Initialize parallel environment with \verb|psb_init|
\item Initialize index space with \verb|psb_cdall|
\item Loop over the topology of the discretization mesh and build the
descriptor with \verb|psb_cdins|
\item Assemble the descriptor with \verb|psb_cdasb|
\item Allocate the sparse matrices and dense vectors with
\verb|psb_spall| and \verb|psb_geall|
\item Loop over the time steps:
\begin{enumerate}
\item If after first time step,
reinitialize the sparse matrix with \verb|psb_sprn|; also zero out
the dense vectors;
\item Loop over the mesh, generate the coefficients and insert/update
them with \verb|psb_spins| and \verb|psb_geins|
\item Assemble with \verb|psb_spasb| and \verb|psb_geasb|
\item Choose and build preconditioner with \verb|psb_precset| and
\verb|psb_precbld|
\item Call the iterative method of choice, e.g. \verb|psb_bicgstab|
\end{enumerate}
\end{enumerate}
The insertion routines will be called as many times as needed;
they only need to be called on the data that is actually
allocated to the current process, i.e. each process generates its own
data.
In principle there is no specific order in the calls to
\verb|psb_spins|, nor is there a requirement to build a matrix row in
its entirety before calling the routine; this allows the application
programmer to walk through the discretization mesh element by element,
generating the main part of a given matrix row but also contributions
to the rows corresponding to neighbouring elements.
From a functional point of view it is even possible to execute one
call for each nonzero coefficient; however this would have a
substantial computational overhead. It is therefore advisable to pack
a certain amount of data into each call to the insertion routine, say
touching on a few tens of rows; the best performng value would depend
on both the architecture of the computer being used and on the problem
structure.
At the opposite extreme, it would be possible to generate the entire
part of a coefficient matrix residing on a process and pass it in a
single call to \verb|psb_spins|; this, however, would entail a
doubling of memory occupation, and thus would be almost always far
from optimal.
\subsection{Programming model}
The PSBLAS librarary is based on the Single Program Multiple Data
(SPMD) programming model: each process participating in the
computation performs the same actions on a chunk of data. Parallelism
is thus data-driven.
Because of this structure, many subroutines coordinate their action
across the various processes, thus providing an implicit
synchronization point, and therefore \emph{must} be
called simultaneously by all processes participating in the
computation. This is certainly true for the data allocation and
assembly routines, for all the computational routines and for some of
the tools routines.
However there are many cases where no synchronization, and indeed no
communication among processes, is implied; for instance, all the routines in
sec.~\ref{sec:dataquery} are only acting on the local data structures,
and thus may be called independently. The most important case is that
of the coefficient insertion routines: since the number of
coefficients in the sparse and dense matrices varies among the
processors, and since the user is free to choose an arbitrary order in
builiding the matrix entries, these routines cannot imply a
synchronization.
Throughout this user's guide each subroutine will be clearly indicated
as:
\begin{description}
\item[Synchronous:] must be called simultaneously by all the
processes in the relevant communication context;
\item[Asynchronous:] may be called in a totally independent manner.
\end{description}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/methods.tex
+138
View File
@@ -0,0 +1,138 @@
\section{Iterative Methods}
\label{sec:methods}
In this chapter we provide routines for preconditioners and iterative
methods. The interfaces for Krylov subspace methods are available in
the module \verb|psb_krylov_mod|.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Krylov Methods driver routine
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage\subsection*{psb\_krylov \label{krylov} --- Krylov Methods Driver
Routine}
\addcontentsline{toc}{subsection}{krylov}
This subroutine is a driver that provides a general interface for all
the Krylov-Subspace family methods implemented in PSBLAS version 2.
The stopping criterion is the normwise backward error, in the infinity
norm, i.e. the iteration is stopped when
\[ err = \frac{\|r_i\|}{(\|A\|\|x_i\|+\|b\|)} < eps \]
or the 2-norm residual reduction
\[ err = \frac{\|r_i\|}{\|b\|_2} < eps \]
according to the value passed through the istop argument (see
later). In the above formulae, $x_i$ is the tentative solution and
$r_i=b-Ax_i$ the corresponding residual at the $i$-th iteration.
\begin{verbatim}
call psb_krylov(method,a,prec,b,x,eps,desc_a,info,&
& itmax,iter,err,itrace,irst,istop,cond)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[method] a string that defines the iterative method to be
used. Supported values are:
\begin{description}
\item[CG:] the Conjugate Gradient method;
\item[CGS:] the Conjugate Gradient Stabilized method;
\item[BICG:] the Bi-Conjugate Gradient method;
\item[BICGSTAB:] the Bi-Conjugate Gradient Stabilized method;
\item[BICGSTABL:] the Bi-Conjugate Gradient Stabilized method with restarting;
\item[RGMRES:] the Generalized Minimal Residual method with restarting.
\end{description}
\item[a] the local portion of global sparse matrix
$A$. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \spdata.
\item[prec] The data structure containing the preconditioner.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \precdata.
\item[b] The RHS vector. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a rank one array.
\item[x] The initial guess. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one array.
\item[eps] The stopping tolerance. \\
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a real number.
\item[desc\_a] contains data structures for communications.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a structured data of type \descdata.
\item[itmax] The maximum number of iterations to perform.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Default: $itmax = 1000$.\\
Specified as: an integer variable $itmax \ge 1$.
\item[itrace] If $>0$ print out an informational message about
convergence every $itrace$ iterations.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
\item[irst] An integer specifying the restart parameter.\\
Scope: {\bf global} \\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Values: $irst>0$. This is employed for the BiCGSTABL or RGMRES
methods, otherwise it is ignored.
\item[istop] An integer specifying the stopping criterion.\\
Scope: {\bf global} \\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Values: 1: use the normwise backward error, 2: use the scaled 2-norm
of the residual. Default: 2.
\item[\bf On Return]
\item[x] The computed solution. \\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a rank one array.
\item[iter] The number of iterations performed.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Returned as: an integer variable.
\item[err] The convergence estimate on exit.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Returned as: a real number.
\item[cond] An estimate of the condition number of matrix $A$; only
available with the $CG$ method.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf out}.\\
Returned as: a real number.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
\end{description}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/penv.tex
+676
View File
@@ -0,0 +1,676 @@
\section{Parallel environment routines}
\label{sec:parenv}
\clearpage\subsection*{psb\_init --- Initializes PSBLAS parallel environment}
\addcontentsline{toc}{subsection}{psb\_init}
\begin{verbatim}
call psb_init(icontxt, np)
\end{verbatim}
This subroutine initializes the PSBLAS parallel environment, defining
a virtual parallel machine.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[np] Number of processes in the PSBLAS virtual parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value. \
Default: use all available processes provided by the underlying
parallel environment.
\end{description}
\begin{description}
\item[\bf On Return]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
Specified as: an integer variable.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item A call to this routine must precede any other PSBLAS call.
\item It is an error to specify a value for $np$ greater than the
number of processes available in the underlying parallel execution
environment.
\end{enumerate}
\clearpage\subsection*{psb\_info --- Return information about PSBLAS parallel
environment}
\addcontentsline{toc}{subsection}{psb\_info}
\begin{verbatim}
call psb_info(icontxt, iam, np)
\end{verbatim}
This subroutine returns information about the PSBLAS parallel environment, defining
a virtual parallel machine.
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}
\begin{description}
\item[\bf On Return]
\item[iam] Identifier of current process in the PSBLAS virtual parallel machine.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
Specified as: an integer value. $-1 \le iam \le np-1$\
\item[np] Number of processes in the PSBLAS virtual parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
Specified as: an integer variable. \
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item For processes in the virtual parallel machine the identifier
will satisfy $0 \le iam \le np-1$;
\item If the user has requested on \verb|psb_init| a number of
processes less than the total available in the parallel execution
environment, the remaining processes will have on return $iam=-1$;
the only call involving \verb|icontxt| that any such process may
execute is to \verb|psb_exit|.
\end{enumerate}
\clearpage\subsection*{psb\_exit --- Exit from PSBLAS parallel environment}
\addcontentsline{toc}{subsection}{psb\_exit}
\begin{verbatim}
call psb_exit(icontxt)
call psb_exit(icontxt,close)
\end{verbatim}
This subroutine exits from the PSBLAS parallel virtual machine.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[close] Whether to close all data structures related to the
virtual parallel machine, besides those associated with icontxt.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: a logical variable, default value: true.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item This routine may be called even if a previous call to
\verb|psb_info| has returned with $iam=-1$; indeed, it it is the only
routine that may be called with argument \verb|icontxt| in this
situation.
\item A call to this routine with \verb|close=.true.| implies a call
to \verb|MPI_Finalize|, after which no parallel routine may be called.
\item If the user whishes to use multiple communication contexts in the
same program, or to enter and exit multiple times into the parallel
environment, this routine may be called to
selectively close the contexts with \verb|close=.false.|, while on
the last call it should be called with \verb|close=.true.| to
shutdown in a clean way the entire parallel environment.
\end{enumerate}
\clearpage\subsection*{psb\_get\_mpicomm --- Get the MPI communicator}
\addcontentsline{toc}{subsection}{psb\_get\_mpicomm}
\begin{verbatim}
call psb_get_mpicomm(icontxt, icomm)
\end{verbatim}
This subroutine returns the MPI communicator associated with a PSBLAS context
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}
\begin{description}
\item[\bf On Return]
\item[icomm] The MPI communicator associated with the PSBLAS virtual parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
\end{description}
\clearpage\subsection*{psb\_get\_rank --- Get the MPI rank}
\addcontentsline{toc}{subsection}{psb\_get\_rank}
\begin{verbatim}
call psb_get_rank(rank, icontxt, id)
\end{verbatim}
This subroutine returns the MPI rank of the PSBLAS process $id$
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[id] Identifier of a process in the PSBLAS virtual parallel machine.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value. $0 \le id \le np-1$\
\end{description}
\begin{description}
\item[\bf On Return]
\item[rank] The MPI rank associated with the PSBLAS process $id$.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf out}.\\
\end{description}
\clearpage\subsection*{psb\_wtime --- Wall clock timing}
\addcontentsline{toc}{subsection}{psb\_wtime}
\begin{verbatim}
time = psb_wtime()
\end{verbatim}
This function returns a wall clock timer. The resolution of the timer
is dependent on the underlying parallel environment implementation.
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Exit ]
\item[Function value] the elapsed time in seconds.\\
Returned as: a \verb|real(psb_dpk_)| variable.
\end{description}
\clearpage\subsection*{psb\_barrier --- Sinchronization point parallel
environment}
\addcontentsline{toc}{subsection}{psb\_barrier}
\begin{verbatim}
call psb_barrier(icontxt)
\end{verbatim}
This subroutine acts as an explicit synchronization point for the PSBLAS
parallel virtual machine.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}
\clearpage\subsection*{psb\_abort --- Abort a computation}
\addcontentsline{toc}{subsection}{psb\_abort}
\begin{verbatim}
call psb_abort(icontxt)
\end{verbatim}
This subroutine aborts computation on the parallel virtual machine.
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\end{description}
\clearpage\subsection*{psb\_bcast --- Broadcast data}
\addcontentsline{toc}{subsection}{psb\_bcast}
\begin{verbatim}
call psb_bcast(icontxt, dat, root)
\end{verbatim}
This subroutine implements a broadcast operation based on the
underlying communication library.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] On the root process, the data to be broadcast.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical variable,
which may be a scalar or rank 1 array. \
Type, kind, rank and size must agree on all processes.
\item[root] Root process holding data to be broadcast.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= root <= np-1$, default 0 \
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] On processes other than root, the data to be broadcast.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
Type, kind, rank and size must agree on all processes.
\end{description}
\clearpage\subsection*{psb\_sum --- Global sum}
\addcontentsline{toc}{subsection}{psb\_sum}
\begin{verbatim}
call psb_sum(icontxt, dat, root)
\end{verbatim}
This subroutine implements a sum reduction operation based on the
underlying communication library.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global sum.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\item[root] Process to hold the final sum, or $-1$ to make it available
on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $-1<= root <= np-1$, default -1. \
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] On destination process(es), the result of the sum operation.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. \\
Type, kind, rank and size must agree on all processes.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
value may be changed even on processes different from the final
result destination.
\end{enumerate}
\clearpage\subsection*{psb\_max --- Global maximum}
\addcontentsline{toc}{subsection}{psb\_max}
\begin{verbatim}
call psb_max(icontxt, dat, root)
\end{verbatim}
This subroutine implements a maximum valuereduction
operation based on the underlying communication library.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global maximum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer or real variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\item[root] Process to hold the final maximum, or $-1$ to make it available
on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $-1<= root <= np-1$, default -1. \\
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] On destination process(es), the result of the maximum operation.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer or real variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
value may be changed even on processes different from the final
result destination.
\end{enumerate}
\clearpage\subsection*{psb\_min --- Global minimum}
\addcontentsline{toc}{subsection}{psb\_min}
\begin{verbatim}
call psb_min(icontxt, dat, root)
\end{verbatim}
This subroutine implements a minimum value reduction
operation based on the underlying communication library.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global minimum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer or real variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\item[root] Process to hold the final value, or $-1$ to make it available
on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $-1<= root <= np-1$, default -1. \\
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] On destination process(es), the result of the minimum operation.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer or real variable, which may be a
scalar, or a rank 1 or 2 array. \\
Type, kind, rank and size must agree on all processes.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
value may be changed even on processes different from the final
result destination.
\end{enumerate}
\clearpage\subsection*{psb\_amx --- Global maximum absolute value}
\addcontentsline{toc}{subsection}{psb\_amx}
\begin{verbatim}
call psb_amx(icontxt, dat, root)
\end{verbatim}
This subroutine implements a maximum absolute value reduction
operation based on the underlying communication library.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global maximum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\item[root] Process to hold the final value, or $-1$ to make it available
on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $-1<= root <= np-1$, default -1. \\
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] On destination process(es), the result of the maximum operation.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
value may be changed even on processes different from the final
result destination.
\end{enumerate}
\clearpage\subsection*{psb\_amn --- Global minimum absolute value}
\addcontentsline{toc}{subsection}{psb\_amn}
\begin{verbatim}
call psb_amn(icontxt, dat, root)
\end{verbatim}
This subroutine implements a minimum absolute value reduction
operation based on the underlying communication library.
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The local contribution to the global minimum.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. \
Type, kind, rank and size must agree on all processes.
\item[root] Process to hold the final value, or $-1$ to make it available
on all processes.\\
Scope: {\bf global}.\\
Type: {\bf optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $-1<= root <= np-1$, default -1. \\
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] On destination process(es), the result of the minimum operation.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array. \\
Type, kind, rank and size must agree on all processes.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item The \verb|dat| argument is both input and output, and its
value may be changed even on processes different from the final
result destination.
\end{enumerate}
\clearpage\subsection*{psb\_snd --- Send data}
\addcontentsline{toc}{subsection}{psb\_snd}
\begin{verbatim}
call psb_snd(icontxt, dat, dst, m)
\end{verbatim}
This subroutine sends a packet of data to a destination.
\begin{description}
\item[Type:] Synchronous: see usage notes.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[dat] The data to be sent.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
Type, kind and rank must agree on sender and receiver process; if $m$ is
not specified, size must agree as well.
\item[dst] Destination process.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= dst <= np-1$. \\
\item[m] Number of rows.\\
Scope: {\bf global}.\\
Type: {\bf Optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= m <= size(dat,1)$. \\
When $dat$ is a rank 2 array, specifies the number of rows to be sent
independently of the leading dimension $size(dat,1)$; must have the
same value on sending and receiving processes.
\end{description}
\begin{description}
\item[\bf On Return]
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item This subroutine implies a synchronization, but only between the
calling process and the destination process $dst$.
\end{enumerate}
\clearpage\subsection*{psb\_rcv --- Receive data}
\addcontentsline{toc}{subsection}{psb\_rcv}
\begin{verbatim}
call psb_rcv(icontxt, dat, src, m)
\end{verbatim}
This subroutine receives a packet of data to a destination.
\begin{description}
\item[Type:] Synchronous: see usage notes.
\item[\bf On Entry ]
\item[icontxt] the communication context identifying the virtual
parallel machine.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer variable.
\item[src] Source process.\\
Scope: {\bf global}.\\
Type: {\bf required}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= src <= np-1$. \\
\item[m] Number of rows.\\
Scope: {\bf global}.\\
Type: {\bf Optional}.\\
Intent: {\bf in}.\\
Specified as: an integer value $0<= m <= size(dat,1)$. \\
When $dat$ is a rank 2 array, specifies the number of rows to be sent
independently of the leading dimension $size(dat,1)$; must have the
same value on sending and receiving processes.
\end{description}
\begin{description}
\item[\bf On Return]
\item[dat] The data to be received.\\
Scope: {\bf local}.\\
Type: {\bf required}.\\
Intent: {\bf inout}.\\
Specified as: an integer, real or complex variable, which may be a
scalar, or a rank 1 or 2 array, or a character or logical scalar. \
Type, kind and rank must agree on sender and receiver process; if $m$ is
not specified, size must agree as well.
\end{description}
{\par\noindent\large\bfseries Notes}
\begin{enumerate}
\item This subroutine implies a synchronization, but only between the
calling process and the source process $src$.
\end{enumerate}
docs/src/precs.tex
+215
View File
@@ -0,0 +1,215 @@
\section{Preconditioner routines}
\label{sec:precs}
% \section{Preconditioners}
\label{sec:psprecs}
The base PSBLAS library contains the implementation of two simple
preconditioning techniques:
\begin{itemize}
\item Diagonal Scaling
\item Block Jacobi with ILU(0) factorization
%% \item Additive Schwarz with the Restricted Additive Schwarz and
%% Additive Schwarz with Harmonic extensions;
\end{itemize}
The supporting data type and subroutine interfaces are defined in the
module \verb|psb_prec_mod|.
%% We also provide a companion package of multi-level Additive
%% Schwarz preconditioners called MD2P4; this is actually a family of
%% preconditioners since there is the possibility to choose between
%% many variants, and is currently in an experimental stateIts
%% documentation is planned to appear after stabilization of the
%% package, which will characterize release 2.1 of our library.
\clearpage\subsection*{psb\_precinit --- Initialize a preconditioner}
\addcontentsline{toc}{subsection}{psb\_precinit}
\begin{verbatim}
call psb_precinit(prec, ptype, info)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[ptype] the type of preconditioner.
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a character string, see usage notes.
%% \item[iv] integer parameters for the precondtioner.
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: an integer array, see usage notes.
%% \item[rs]
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Specified as: a long precision real number.
\item[\bf On Exit]
\item[prec]
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a preconditioner data structure \precdata.
\item[info]
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf out}.\\
Error code: if no error, 0 is returned.
\end{description}
{\par\noindent\large\bfseries Notes}
%% The PSBLAS 2.0 contains a number of preconditioners, ranging from a
%% simple diagonal scaling to 2-level domain decomposition. These
%% preconditioners may use the SuperLU or the UMFPACK software, if
%% installed; see~\cite{SUPERLU,UMFPACK}.
Legal inputs to this subroutine are interpreted depending on the
$ptype$ string as follows\footnote{The string is case-insensitive}:
\begin{description}
\item[NONE] No preconditioning, i.e. the preconditioner is just a copy
operator.
\item[DIAG] Diagonal scaling; each entry of the input vector is
multiplied by the reciprocal of the sum of the absolute values of
the coefficients in the corresponding row of matrix $A$;
\item[BJAC] Precondition by a factorization of the
block-diagonal of matrix $A$, where block boundaries are determined
by the data allocation boundaries for each process; requires no
communication. Only the incomplete factorization $ILU(0)$ is
currently implemented.
\end{description}
\clearpage\subsection*{psb\_precbld --- Builds a preconditioner}
\addcontentsline{toc}{subsection}{psb\_precbld}
\begin{verbatim}
call psb_precbld(a, desc_a, prec, info)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[a] the system sparse matrix.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}, target.\\
Specified as: a sparse matrix data structure \spdata.
\item[prec] the preconditioner.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: an already initialized precondtioner data structure \precdata\\
\item[desc\_a] the problem communication descriptor.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}, target.\\
Specified as: a communication descriptor data structure \descdata.
%% \item[upd]
%% Scope: {\bf global} \\
%% Type: {\bf optional}\\
%% Intent: {\bf in}.\\
%% Specified as: a character.
\end{description}
\begin{description}
\item[\bf On Return]
\item[prec] the preconditioner.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a precondtioner data structure \precdata\\
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
\end{description}
\clearpage\subsection*{psb\_precaply --- Preconditioner application routine}
\addcontentsline{toc}{subsection}{psb\_precaply}
\begin{verbatim}
call psb_precaply(prec,x,y,desc_a,info,trans,work)
call psb_precaply(prec,x,desc_a,info,trans)
\end{verbatim}
\begin{description}
\item[Type:] Synchronous.
\item[\bf On Entry]
\item[prec] the preconditioner.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a preconditioner data structure \precdata.
\item[x] the source vector.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a double precision array.
\item[desc\_a] the problem communication descriptor.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a communication data structure \descdata.
\item[trans]
Scope: {\bf } \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: a character.
\item[work] an optional work space
Scope: {\bf local} \\
Type: {\bf optional}\\
Intent: {\bf inout}.\\
Specified as: a double precision array.
\end{description}
\begin{description}
\item[\bf On Return]
\item[y] the destination vector.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf inout}.\\
Specified as: a double precision array.
\item[info] Error code.\\
Scope: {\bf local} \\
Type: {\bf required} \\
Intent: {\bf out}.\\
An integer value; 0 means no error has been detected.
\end{description}
\clearpage\subsection*{psb\_precdescr --- Prints a description of current
preconditioner}
\addcontentsline{toc}{subsection}{psb\_precdescr}
\begin{verbatim}
call psb_precdescr(prec)
call psb_precdescr(prec, iout)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[prec] the preconditioner.
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a preconditioner data structure \precdata.
\item[iout] output unit.
Scope: {\bf local} \\
Type: {\bf optiona}\\
Intent: {\bf in}.\\
Specified as: an integer number.
\end{description}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/psbrout.tex
+1093
View File
File diff suppressed because it is too large Load Diff
docs/src/toolsrout.tex
+1678
View File
File diff suppressed because it is too large Load Diff
docs/src/userguide.tex
+290
View File
@@ -0,0 +1,290 @@
\documentclass[10pt,a4paper,twoside]{article}
\usepackage{pstricks}
\usepackage{fancybox}
\usepackage{amsfonts}
% \usepackage{minitoc}
% \setcounter{minitocdepth}{2}
\usepackage[bookmarks=true,
bookmarksnumbered=true,
bookmarksopen=false,
plainpages=false,
pdfpagelabels,
colorlinks,
citecolor=red,
linkcolor=blue]{hyperref}
\usepackage{ifthen}
\usepackage{graphicx}
\newtheorem{theorem}{Theorem}
\newtheorem{corollary}{Corollary}
%\newboolean{mtc}
%\setboolean{mtc}{true}
\pdfoutput=1
\relax
\pdfcompresslevel=0 %-- 0 = none, 9 = best
\pdfinfo{ %-- Info dictionary of PDF output /Author (Alfredo Buttari)
/Title (Parallel Sparse BLAS V. 2.2)
/Subject (Parallel Sparse Basic Linear Algebra Subroutines)
/Keywords (Computer Science Linear Algebra Fluid Dynamics Parallel Linux MPI PSBLAS Iterative Solvers Preconditioners)
/Creator (pdfLaTeX)
/Producer ($Id$)
}
\pdfcatalog{ %-- Catalog dictionary of PDF output.
/URI (http://ce.uniroma2.it/psblas)
}
\newcounter{subroutine}[subsection]
\newcounter{example}[subroutine]
\makeatletter
\def\subroutine{\@ifstar{\@subroutine}{\clearpage\@subroutine}}%
\def\@subroutine#1#2{%
\stepcounter{subroutine}%
\section*{\flushleft #1---#2 \endflushleft}%
\addcontentsline{toc}{subsection}{#1}%
\markright{#1}}%
\newcommand{\subsubroutine}[2]{%
\stepcounter{subroutine}%
\subsection*{\flushleft #1---#2 \endflushleft}%
\addcontentsline{toc}{subsubsection}{#1}%
\markright{#1}}%
\newcommand{\examplename}{Example}
\newcommand{\syntaxname}{Syntax}
\def\syntax{\@ifstar{\@ssyntax}{\@syntax}}%
\def\@syntax{\nobreak\section*{\syntaxname}%
\@ssyntax}%
\def\@ssyntax#1#2{%
\nobreak
\setbox\@tempboxa\hbox{#1\ {\em $($#2$)$}}%
\ifdim \wd\@tempboxa >\hsize
\setbox\@tempboxa\hbox{\em $($#2$)$}
\ifdim\wd\@tempboxa >\hsize
\flushright#1\ \em$($#2$)$\endflushright%
\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\_type}}}
\newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}}
\newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}}
\begin{document}
\pdfbookmark{PSBLAS-v2.3 User's Guide}{title}
\newlength{\centeroffset}
\setlength{\centeroffset}{-0.5\oddsidemargin}
\addtolength{\centeroffset}{0.5\evensidemargin}
%\addtolength{\textwidth}{-\centeroffset}
\thispagestyle{empty}
\vspace*{\stretch{1}}
\noindent\hspace*{\centeroffset}\makebox[0pt][l]{\begin{minipage}{\textwidth}
\flushright
{\Huge\bfseries PSBLAS 2.3 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\\
and Alfredo Buttari}\\
University of Rome ``Tor Vergata''.\\[3ex]
\today
\end{minipage}}
%\addtolength{\textwidth}{\centeroffset}
\vspace{\stretch{2}}
\cleardoublepage
\begingroup
\renewcommand*{\thepage}{toc}
\pagenumbering{roman} % Roman numbering
\setcounter{page}{1} % Abstract start on page ii
\tableofcontents
\endgroup
\cleardoublepage
\pagenumbering{arabic} % Arabic numbering
\setcounter{page}{1} % Chapters start on page 1
\include{intro}
\include{datastruct}
\include{psbrout}
\include{commrout}
\include{toolsrout}
\include{penv}
\include{error}
\include{util}
\include{precs}
\include{methods}
\cleardoublepage
\begin{thebibliography}{99}
\bibitem{PARA04FOREST}
G.~Bella, S.~Filippone, A.~De Maio and M.~Testa,
{\em A Simulation Model for Forest Fires},
in J.~Dongarra, K.~Madsen, J.~Wasniewski, editors,
Proceedings of PARA~04 Workshop on State of the Art
in Scientific Computing, pp.~546--553, Lecture Notes in Computer Science,
Springer, 2005.
\bibitem{2007d} A. Buttari, D. di Serafino, P. D'Ambra, S. Filippone,\newblock
2LEV-D2P4: a package of high-performance preconditioners,\newblock
Applicable Algebra in Engineering, Communications and Computing,
Volume 18, Number 3, May, 2007, pp. 223-239
%Published online: 13 February 2007, {\tt http://dx.doi.org/10.1007/s00200-007-0035-z}
%
\bibitem{2007c} P. D'Ambra, S. Filippone, D. Di Serafino\newblock
On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners
\newblock
Applied Numerical Mathematics, Elsevier Science,
Volume 57, Issues 11-12, November-December 2007, Pages 1181-1196.
%published online 3 February 2007, {\tt
% http://dx.doi.org/10.1016/j.apnum.2007.01.006}
\bibitem{BLAS2}
Dongarra, J. J., DuCroz, J., Hammarling, S. and Hanson, R.,
An Extended Set of {F}ortran {B}asic {L}inear {A}lgebra {S}ubprograms,
{ACM Trans. Math. Softw.} vol.~{14}, 1--17, 1988.
\bibitem{BLAS3}
Dongarra, J., DuCroz, J., Hammarling, S. and Duff, I.,
A Set of level 3 Basic Linear Algebra Subprograms,
{ACM Trans. Math. Softw.} vol.~{16}, 1--17, 1990.
%% \bibitem{DOUGLAS}
%% R.E.~Bank and C.C.~Douglas,
%% {\em SMMP: Sparse Matrix Multiplication Package},
%% Advances in Computational Mathematics, 1993, 1, 127-137.
%% (See also {\tt http://www.mgnet.org/~douglas/ccd-codes.html})
%
%
%% \bibitem{PARA04}
%% A.~Buttari, P.~D'Ambra, D.~di Serafino and S.~Filippone,
%% {\em Extending PSBLAS to Build Parallel Schwarz Preconditioners},
%% in , J.~Dongarra, K.~Madsen, J.~Wasniewski, editors,
%% Proceedings of PARA~04 Workshop on State of the Art
%% in Scientific Computing, pp.~593--602, Lecture Notes in Computer Science,
%% Springer, 2005.
%
%% \bibitem{CAI_SAAD}
%% X.~C.~Cai and Y.~Saad,
%% {\em Overlapping Domain Decomposition Algorithms for General Sparse Matrices},
%% Numerical Linear Algebra with Applications, 3(3), pp.~221--237, 1996.
%% %
%% \bibitem{CAI_SARKIS}
%% X.C.~Cai and M.~Sarkis,
%% {\em A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems},
%% SIAM Journal on Scientific Computing, 21(2), pp.~792--797, 1999.
%
%% \bibitem{CAI_WIDLUND}
%% X.C.~Cai and O.~B.~Widlund,
%% {\em Domain Decomposition Algorithms for Indefinite Elliptic Problems},
%% SIAM Journal on Scientific and Statistical Computing, 13(1), pp.~243--258, 1992.
%
%% \bibitem{DD1}
%% T.~Chan and T.~Mathew,
%% {\em Domain Decomposition Algorithms},
%% in A.~Iserles, editor, Acta Numerica 1994, pp.~61--143, 1994.
%% Cambridge University Press.
%% %
%% \bibitem{APNUM06}
%% P.~D'Ambra, D.~di Serafino and S.~Filippone,
%% On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners,
%% Applied Numerical Mathematics, to appear, 2007.
%
%% \bibitem{UMFPACK}
%% T.A.~Davis,
%% {\em Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal
%% Method with a Column Pre-ordering Strategy},
%% ACM Transactions on Mathematical Software, 30, pp.~196--199, 2004.
%% (See also {\tt http://www.cise.ufl.edu/~davis/})
%% %
%% \bibitem{SUPERLU}
%% J.W.~Demmel, S.C.~Eisenstat, J.R.~Gilbert, X.S.~Li and J.W.H.~Liu,
%% A supernodal approach to sparse partial pivoting,
%% SIAM Journal on Matrix Analysis and Applications, 20(3), pp.~720--755, 1999.
%
\bibitem{BLACS}
J.~J.~Dongarra and R.~C.~Whaley,
{\em A User's Guide to the BLACS v.~1.1},
Lapack Working Note 94, Tech.\ Rep.\ UT-CS-95-281, University of
Tennessee, March 1995 (updated May 1997).
%
\bibitem{sblas97}
I.~Duff, M.~Marrone, G.~Radicati and C.~Vittoli,
{\em Level 3 Basic Linear Algebra Subprograms for Sparse Matrices:
a User Level Interface},
ACM Transactions on Mathematical Software, 23(3), pp.~379--401, 1997.
%
\bibitem{sblas02}
I.~Duff, M.~Heroux and R.~Pozo,
{\em An Overview of the Sparse Basic Linear
Algebra Subprograms: the New Standard from the BLAS Technical Forum},
ACM Transactions on Mathematical Software, 28(2), pp.~239--267, 2002.
\bibitem{PSBLAS}
S.~Filippone and M.~Colajanni,
{\em PSBLAS: A Library for Parallel Linear Algebra
Computation on Sparse Matrices},
\newblock
ACM Transactions on Mathematical Software, 26(4), pp.~527--550, 2000.
%
\bibitem{KIVA3PSBLAS}
S.~Filippone, P.~D'Ambra, M.~Colajanni,
{\em Using a Parallel Library of Sparse Linear Algebra in a Fluid Dynamics
Applications Code on Linux Clusters},
in G.~Joubert, A.~Murli, F.~Peters, M.~Vanneschi, editors,
Parallel Computing - Advances \& Current Issues,
pp.~441--448, Imperial College Press, 2002.
%
\bibitem{METIS}
Karypis, G. and Kumar, V.,
{\em {METIS}: Unstructured Graph Partitioning and Sparse Matrix
Ordering System}.
Minneapolis, MN 55455: University of Minnesota, Department of
Computer Science, 1995.
Internet Address: {\verb|http://www.cs.umn.edu/~karypis|}.
\bibitem{BLAS1}
Lawson, C., Hanson, R., Kincaid, D. and Krogh, F.,
Basic {L}inear {A}lgebra {S}ubprograms for {F}ortran usage,
{ACM Trans. Math. Softw.} vol.~{5}, 38--329, 1979.
\bibitem{machiels}
{Machiels, L. and Deville, M.}
{\em Fortran 90: An entry to object-oriented programming for the solution
of partial differential equations.}
{ACM Trans. Math. Softw.} vol.~{23}, 32--49.
\bibitem{metcalf}
{Metcalf, M., Reid, J. and Cohen, M.}
{\em Fortran 95/2003 explained.}
{Oxford University Press}, 2004.
%
%% \bibitem{DD2}
%% B.~Smith, P.~Bjorstad and W.~Gropp,
%% {\em Domain Decomposition: Parallel Multilevel Methods for Elliptic
%% Partial Differential Equations},
%% Cambridge University Press, 1996.
%
\bibitem{MPI1}
M.~Snir, S.~Otto, S.~Huss-Lederman, D.~Walker and J.~Dongarra,
{\em MPI: The Complete Reference. Volume 1 - The MPI Core}, second edition,
MIT Press, 1998.
%
\end{thebibliography}
\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: 'userguide'
%%% End:
docs/src/userhtml.tex
+270
View File
@@ -0,0 +1,270 @@
\documentclass[10pt,a4paper,twoside]{article}
\usepackage{pstricks}
\usepackage{fancybox}
\usepackage{amsfonts}
% \usepackage{minitoc}
% \setcounter{minitocdepth}{2}
\usepackage[bookmarks=true,
bookmarksnumbered=true,
bookmarksopen=false,
plainpages=false,
pdfpagelabels,
colorlinks,
linkcolor=blue]{hyperref}
\usepackage{ifthen}
\usepackage{graphicx}
\newtheorem{theorem}{Theorem}
\newtheorem{corollary}{Corollary}
%\newboolean{mtc}
%\setboolean{mtc}{true}
\pdfoutput=0
% \relax
% \pdfcompresslevel=0 %-- 0 = none, 9 = best
% \pdfinfo{ %-- Info dictionary of PDF output /Author (Alfredo Buttari)
% /Title (Parallel Sparse BLAS V. 2.2)
% /Subject (Parallel Sparse Basic Linear Algebra Subroutines)
% /Keywords (Computer Science Linear Algebra Fluid Dynamics Parallel Linux MPI PSBLAS Iterative Solvers Preconditioners)
% /Creator (pdfLaTeX)
% /Producer ($Id: userguide.tex 1978 2007-10-19 14:51:12Z sfilippo $)
% }
% \pdfcatalog{ %-- Catalog dictionary of PDF output.
% /URI (http://ce.uniroma2.it/psblas)
% }
\newcounter{subroutine}[subsection]
\newcounter{example}[subroutine]
\makeatletter
\def\subroutine{\@ifstar{\@subroutine}{\clearpage\@subroutine}}%
\def\@subroutine#1#2{%
\stepcounter{subroutine}%
\section*{\flushleft #1---#2 \endflushleft}%
\addcontentsline{toc}{subsection}{#1}%
\markright{#1}}%
\newcommand{\subsubroutine}[2]{%
\stepcounter{subroutine}%
\subsection*{\flushleft #1---#2 \endflushleft}%
\addcontentsline{toc}{subsubsection}{#1}%
\markright{#1}}%
\newcommand{\examplename}{Example}
\newcommand{\syntaxname}{Syntax}
\def\syntax{\@ifstar{\@ssyntax}{\@syntax}}%
\def\@syntax{\nobreak\section*{\syntaxname}%
\@ssyntax}%
\def\@ssyntax#1#2{%
\nobreak
\setbox\@tempboxa\hbox{#1\ {\em $($#2$)$}}%
\ifdim \wd\@tempboxa >\hsize
\setbox\@tempboxa\hbox{\em $($#2$)$}
\ifdim\wd\@tempboxa >\hsize
\flushright#1\ \em$($#2$)$\endflushright%
\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\_type}}}
\newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}}
\newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}}
\begin{document}
{\LARGE\bfseries PSBLAS\\[.8ex] User's and Reference
Guide}\\[\baselineskip]
\emph{\large A reference guide for the Parallel Sparse BLAS library}\\[3ex]
{\bfseries Salvatore Filippone\\
Alfredo Buttari } \\
University of Rome ``Tor Vergata'', Italy\\[2ex]
%\\[10ex]
%\today
Software version: 2.3\\
%\today
July 24, 2008
\cleardoublepage
\begingroup
\renewcommand*{\thepage}{toc}
\pagenumbering{roman} % Roman numbering
\setcounter{page}{1} % Abstract start on page ii
\tableofcontents
\endgroup
\cleardoublepage
\pagenumbering{arabic} % Arabic numbering
\setcounter{page}{1} % Chapters start on page 1
\include{intro}
\include{datastruct}
\include{psbrout}
\include{commrout}
\include{toolsrout}
\include{penv}
\include{error}
\include{util}
\include{precs}
\include{methods}
\cleardoublepage
\begin{thebibliography}{99}
\bibitem{PARA04FOREST}
G.~Bella, S.~Filippone, A.~De Maio and M.~Testa,
{\em A Simulation Model for Forest Fires},
in J.~Dongarra, K.~Madsen, J.~Wasniewski, editors,
Proceedings of PARA~04 Workshop on State of the Art
in Scientific Computing, pp.~546--553, Lecture Notes in Computer Science,
Springer, 2005.
\bibitem{2007d} A. Buttari, D. di Serafino, P. D'Ambra, S. Filippone,\newblock
2LEV-D2P4: a package of high-performance preconditioners,\newblock
Applicable Algebra in Engineering, Communications and Computing,
Volume 18, Number 3, May, 2007, pp. 223-239
%Published online: 13 February 2007, {\tt http://dx.doi.org/10.1007/s00200-007-0035-z}
%
\bibitem{2007c} P. D'Ambra, S. Filippone, D. Di Serafino\newblock
On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners
\newblock
Applied Numerical Mathematics, Elsevier Science,
Volume 57, Issues 11-12, November-December 2007, Pages 1181-1196.
%published online 3 February 2007, {\tt
% http://dx.doi.org/10.1016/j.apnum.2007.01.006}
\bibitem{BLAS2}
Dongarra, J. J., DuCroz, J., Hammarling, S. and Hanson, R.,
An Extended Set of {F}ortran {B}asic {L}inear {A}lgebra {S}ubprograms,
{ACM Trans. Math. Softw.} vol.~{14}, 1--17, 1988.
\bibitem{BLAS3}
Dongarra, J., DuCroz, J., Hammarling, S. and Duff, I.,
A Set of level 3 Basic Linear Algebra Subprograms,
{ACM Trans. Math. Softw.} vol.~{16}, 1--17, 1990.
%% \bibitem{DOUGLAS}
%% R.E.~Bank and C.C.~Douglas,
%% {\em SMMP: Sparse Matrix Multiplication Package},
%% Advances in Computational Mathematics, 1993, 1, 127-137.
%% (See also {\tt http://www.mgnet.org/~douglas/ccd-codes.html})
%
%
%% \bibitem{PARA04}
%% A.~Buttari, P.~D'Ambra, D.~di Serafino and S.~Filippone,
%% {\em Extending PSBLAS to Build Parallel Schwarz Preconditioners},
%% in , J.~Dongarra, K.~Madsen, J.~Wasniewski, editors,
%% Proceedings of PARA~04 Workshop on State of the Art
%% in Scientific Computing, pp.~593--602, Lecture Notes in Computer Science,
%% Springer, 2005.
%
%% \bibitem{CAI_SAAD}
%% X.~C.~Cai and Y.~Saad,
%% {\em Overlapping Domain Decomposition Algorithms for General Sparse Matrices},
%% Numerical Linear Algebra with Applications, 3(3), pp.~221--237, 1996.
%% %
%% \bibitem{CAI_SARKIS}
%% X.C.~Cai and M.~Sarkis,
%% {\em A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems},
%% SIAM Journal on Scientific Computing, 21(2), pp.~792--797, 1999.
%
%% \bibitem{CAI_WIDLUND}
%% X.C.~Cai and O.~B.~Widlund,
%% {\em Domain Decomposition Algorithms for Indefinite Elliptic Problems},
%% SIAM Journal on Scientific and Statistical Computing, 13(1), pp.~243--258, 1992.
%
%% \bibitem{DD1}
%% T.~Chan and T.~Mathew,
%% {\em Domain Decomposition Algorithms},
%% in A.~Iserles, editor, Acta Numerica 1994, pp.~61--143, 1994.
%% Cambridge University Press.
%% %
%% \bibitem{APNUM06}
%% P.~D'Ambra, D.~di Serafino and S.~Filippone,
%% On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners,
%% Applied Numerical Mathematics, to appear, 2007.
%
%% \bibitem{UMFPACK}
%% T.A.~Davis,
%% {\em Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal
%% Method with a Column Pre-ordering Strategy},
%% ACM Transactions on Mathematical Software, 30, pp.~196--199, 2004.
%% (See also {\tt http://www.cise.ufl.edu/~davis/})
%% %
%% \bibitem{SUPERLU}
%% J.W.~Demmel, S.C.~Eisenstat, J.R.~Gilbert, X.S.~Li and J.W.H.~Liu,
%% A supernodal approach to sparse partial pivoting,
%% SIAM Journal on Matrix Analysis and Applications, 20(3), pp.~720--755, 1999.
%
\bibitem{BLACS}
J.~J.~Dongarra and R.~C.~Whaley,
{\em A User's Guide to the BLACS v.~1.1},
Lapack Working Note 94, Tech.\ Rep.\ UT-CS-95-281, University of
Tennessee, March 1995 (updated May 1997).
%
\bibitem{sblas97}
I.~Duff, M.~Marrone, G.~Radicati and C.~Vittoli,
{\em Level 3 Basic Linear Algebra Subprograms for Sparse Matrices:
a User Level Interface},
ACM Transactions on Mathematical Software, 23(3), pp.~379--401, 1997.
%
\bibitem{sblas02}
I.~Duff, M.~Heroux and R.~Pozo,
{\em An Overview of the Sparse Basic Linear
Algebra Subprograms: the New Standard from the BLAS Technical Forum},
ACM Transactions on Mathematical Software, 28(2), pp.~239--267, 2002.
\bibitem{PSBLAS}
S.~Filippone and M.~Colajanni,
{\em PSBLAS: A Library for Parallel Linear Algebra
Computation on Sparse Matrices},
\newblock
ACM Transactions on Mathematical Software, 26(4), pp.~527--550, 2000.
%
\bibitem{KIVA3PSBLAS}
S.~Filippone, P.~D'Ambra, M.~Colajanni,
{\em Using a Parallel Library of Sparse Linear Algebra in a Fluid Dynamics
Applications Code on Linux Clusters},
in G.~Joubert, A.~Murli, F.~Peters, M.~Vanneschi, editors,
Parallel Computing - Advances \& Current Issues,
pp.~441--448, Imperial College Press, 2002.
%
\bibitem{METIS}
Karypis, G. and Kumar, V.,
{\em {METIS}: Unstructured Graph Partitioning and Sparse Matrix
Ordering System}.
Minneapolis, MN 55455: University of Minnesota, Department of
Computer Science, 1995.
Internet Address: {\verb|http://www.cs.umn.edu/~karypis|}.
\bibitem{BLAS1}
Lawson, C., Hanson, R., Kincaid, D. and Krogh, F.,
Basic {L}inear {A}lgebra {S}ubprograms for {F}ortran usage,
{ACM Trans. Math. Softw.} vol.~{5}, 38--329, 1979.
\bibitem{machiels}
{Machiels, L. and Deville, M.}
{\em Fortran 90: An entry to object-oriented programming for the solution
of partial differential equations.}
{ACM Trans. Math. Softw.} vol.~{23}, 32--49.
\bibitem{metcalf}
{Metcalf, M., Reid, J. and Cohen, M.}
{\em Fortran 95/2003 explained.}
{Oxford University Press}, 2004.
%
%% \bibitem{DD2}
%% B.~Smith, P.~Bjorstad and W.~Gropp,
%% {\em Domain Decomposition: Parallel Multilevel Methods for Elliptic
%% Partial Differential Equations},
%% Cambridge University Press, 1996.
%
\bibitem{MPI1}
M.~Snir, S.~Otto, S.~Huss-Lederman, D.~Walker and J.~Dongarra,
{\em MPI: The Complete Reference. Volume 1 - The MPI Core}, second edition,
MIT Press, 1998.
%
\end{thebibliography}
\end{document}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: 'userguide'
%%% End:
docs/src/util.tex
+211
View File
@@ -0,0 +1,211 @@
\section{Utilities}
\label{sec:util}
We have some utitlities available for input and output of
sparsematrices; the interfaces to these routines are available in the
module \verb|psb_util_mod|.
%\subroutine{PSB\_HBIO\_MOD}{Input/Output in Harwell-Boeing format}
\clearpage\subsection*{hb\_read --- Read a sparse matrix from a file in the
Harwell--Boeing format}
\addcontentsline{toc}{subsubsection}{hb\_read}
\begin{verbatim}
call hb_read(a, iret, iunit, filename, b, mtitle)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[filename] The name of the file to be read.\\
Type:{\bf optional}.\\
Specified as: a character variable containing a valid file name, or
\verb|-|, in which case the default input unit 5 (i.e. standard input
in Unix jargon) is used. Default: \verb|-|.
\item[iunit] The Fortran file unit number.\\
Type:{\bf optional}.\\
Specified as: an integer value. Only meaningful if filename is not \verb|-|.
\end{description}
\begin{description}
\item[\bf On Return]
\item[a] the sparse matrix read from file.\\
Type:{\bf required}.\\
Specified as: a structured data of type \spdata.
\item[b] Rigth hand side(s).\\
Type: {\bf Optional} \\
An array of type real or complex, rank 2 and having the ALLOCATABLE
attribute; will be allocated and filled in if the input file contains
a right hand side, otherwise will be left in the UNALLOCATED state.
\item[mtitle] Matrix title.\\
Type: {\bf Optional} \\
A charachter variable of length 72 holding a copy of the
matrix title as specified by the Harwell-Boeing format and contained
in the input file.
\item[iret] Error code.\\
Type: {\bf required} \\
An integer value; 0 means no error has been detected.
\end{description}
\clearpage\subsection*{hb\_write --- Write a sparse matrix to a file
in the Harwell--Boeing format}
\addcontentsline{toc}{subsubsection}{hb\_write}
\begin{verbatim}
call hb_write(a, iret, iunit, filename, key, rhs, mtitle)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[a] the sparse matrix to be written.\\
Type:{\bf required}.\\
Specified as: a structured data of type \spdata.
\item[b] Rigth hand side.\\
Type: {\bf Optional} \\
An array of type real or complex, rank 1 and having the ALLOCATABLE
attribute; will be allocated and filled in if the input file contains
a right hand side.
\item[filename] The name of the file to be written to.\\
Type:{\bf optional}.\\
Specified as: a character variable containing a valid file name, or
\verb|-|, in which case the default output unit 6 (i.e. standard output
in Unix jargon) is used. Default: \verb|-|.
\item[iunit] The Fortran file unit number.\\
Type:{\bf optional}.\\
Specified as: an integer value. Only meaningful if filename is not \verb|-|.
\item[key] Matrix key.\\
Type: {\bf Optional} \\
A charachter variable of length 8 holding the
matrix key as specified by the Harwell-Boeing format and to be
written to file.
\item[mtitle] Matrix title.\\
Type: {\bf Optional} \\
A charachter variable of length 72 holding the
matrix title as specified by the Harwell-Boeing format and to be
written to file.
\end{description}
\begin{description}
\item[\bf On Return]
\item[iret] Error code.\\
Type: {\bf required} \\
An integer value; 0 means no error has been detected.
\end{description}
%\subroutine{PSB\_MMIO\_MOD}{Input/Output in MatrixMarket format}
\clearpage\subsection*{mm\_mat\_read --- Read a sparse matrix from a
file in the MatrixMarket format}
\addcontentsline{toc}{subsubsection}{mm\_mat\_read}
\begin{verbatim}
call mm_mat_read(a, iret, iunit, filename)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[filename] The name of the file to be read.\\
Type:{\bf optional}.\\
Specified as: a character variable containing a valid file name, or
\verb|-|, in which case the default input unit 5 (i.e. standard input
in Unix jargon) is used. Default: \verb|-|.
\item[iunit] The Fortran file unit number.\\
Type:{\bf optional}.\\
Specified as: an integer value. Only meaningful if filename is not \verb|-|.
\end{description}
\begin{description}
\item[\bf On Return]
\item[a] the sparse matrix read from file.\\
Type:{\bf required}.\\
Specified as: a structured data of type \spdata.
\item[iret] Error code.\\
Type: {\bf required} \\
An integer value; 0 means no error has been detected.
\end{description}
\clearpage\subsection*{mm\_vet\_read --- Read a dense vector from a
file in the MatrixMarket format}
\addcontentsline{toc}{subsubsection}{mm\_vet\_read }
\begin{verbatim}
call mm_vet_read(b, iret, iunit, filename)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[filename] The name of the file to be read.\\
Type:{\bf optional}.\\
Specified as: a character variable containing a valid file name, or
\verb|-|, in which case the default input unit 5 (i.e. standard input
in Unix jargon) is used. Default: \verb|-|.
\item[iunit] The Fortran file unit number.\\
Type:{\bf optional}.\\
Specified as: an integer value. Only meaningful if filename is not \verb|-|.
\end{description}
\begin{description}
\item[\bf On Return]
\item[b] Rigth hand side(s).\\
Type: {\bf required} \\
An array of type real or complex, rank 2 and having the ALLOCATABLE
attribute; will be allocated and filled in if the input file contains
a right hand side, otherwise will be left in the UNALLOCATED state.
\item[iret] Error code.\\
Type: {\bf required} \\
An integer value; 0 means no error has been detected.
\end{description}
\clearpage\subsection*{mm\_mat\_write --- Write a sparse matrix to a
file in the MatrixMarket format}
\addcontentsline{toc}{subsubsection}{mm\_mat\_write}
\begin{verbatim}
call mm_mat_write(a, mtitle, iret, iunit, filename)
\end{verbatim}
\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry ]
\item[a] the sparse matrix to be written.\\
Type:{\bf required}.\\
Specified as: a structured data of type \spdata.
\item[mtitle] Matrix title.\\
Type: {\bf required} \\
A charachter variable holding a descriptive title for the matrix to be
written to file.
\item[filename] The name of the file to be written to.\\
Type:{\bf optional}.\\
Specified as: a character variable containing a valid file name, or
\verb|-|, in which case the default output unit 6 (i.e. standard output
in Unix jargon) is used. Default: \verb|-|.
\item[iunit] The Fortran file unit number.\\
Type:{\bf optional}.\\
Specified as: an integer value. Only meaningful if filename is not \verb|-|.
\end{description}
\begin{description}
\item[\bf On Return]
\item[iret] Error code.\\
Type: {\bf required} \\
An integer value; 0 means no error has been detected.
\end{description}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: