Added illustration from sumo to index set documentation.

[[Imported from SVN: r238]]

doc/istl/comm/Makefile.am

@@ -9,8 +9,6 @@ SUFFIXES = .dvi .tex .pdf
 
 dist_pkgdata_DATA = communication.pdf communication.ps
 
-#communication.dvi_DEPENDENCIES = communication.tex indexset.cc reverse.hh
-
 noinst_PROGRAMS = $(MPIPROGRAMS)
 
 indexset_SOURCES = indexset.cc
@@ -38,4 +36,8 @@ indexset_LDADD = $(MPI_LDFLAGS)
 .dvi.ps:
 	$(DVIPS) $*
 
+
+communication.dvi : communication.tex buildindexset.hh reverse.hh
+
+
 CLEANFILES = *.aux *.bbl *.blg *.log *.out *.toc *.dvi *.pdf *.ps

doc/istl/comm/communication.tex

@@ -65,7 +65,7 @@
 Markus Blatt\\
 Interdisziplinäres Zentrum für Wissenschaftliches Rechnen,\\
 Universität Heidelberg, Im Neuenheimer Feld 368, D-69120 Heidelberg, \\
-email: \texttt{Markus.Blarr@iwr.uni-heidelberg.de}}
+email: \texttt{Markus.Blatt@iwr.uni-heidelberg.de}}
 
 \date{\today}
 
@@ -184,15 +184,40 @@ present on other processes there is the possiblity to mark the index
 as public.
 
 \paragraph{Usage Examples}
-Let us look at a short example on how to build an index set:
-
+Let us look at a short example on how to build an index set. The code
+in Listing \ref{lst:build_indexset} sets up an index set with 8
+components on two processes. This index set might be used to access as
+distributed field or \lstinline!std::vector! as sketched in Figure
+\ref{fig:distributed_field}. 
+
+\begin{figure}[htb]
+  \centering
+  \includegraphics{figures/darray.eps}
+  \caption{A Distributed Field}
+  \label{fig:distributed_field}
+\end{figure}
+
+The process $0$ stores in his {/em local}
+field $a_0$ the values corresponding to the global indices
+$I_0=\{0,2,6,3,5\}$, in that order, of the global field $a$ and process
+$I$ the entries corresponding to the values at the indices
+$I_1=\{0,1,7,5,4\}$.
 \lstinputlisting[caption=Build an Index Set,
 label=lst:build_indexset]{buildindexset.hh}
 
 Due to the complexity of \lstinline!operator[](TG& global)! it is
-always advisable to use iterators to access the index pairs of the
-set.
-The following example demonstrates their usage:
+always advisable to use iterators, obtained by calling
+\lstinline!begin()! and \lstinline!end()! respectively, to access the
+index pairs of the set.
+
+Listing \ref{lst:indexset_iterator} demonstrates their
+usage. First the maximum local index $i_{\mbox{max}}$ of the set is
+computed, and the 
+the local indices are renumbered. Due to the ordering the local index with
+the smallest corresponding global index becomes $i_{\mbox{max}}$ and the rest is
+numbered consecutively decreasingly with increasing global index. Let
+$n$ be the number of index pairs in the set than local index
+corresponding to the largets global index becomes $i_{\mbox{max}}-n$.
 \lstinputlisting[caption=Usage of Index Set Iterators,
 label=lst:indexset_iterator]{reverse.hh}
 

doc/istl/comm/figures/darray.eps

+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: ../eps/darray.eps
+%%Creator: fig2dev Version 3.2 Patchlevel 1
+%%CreationDate: Thu Mar  4 15:25:17 1999
+%%For: peter@speedo (Peter Bastian)
+%%Orientation: Portrait
+%%BoundingBox: 0 0 345 260
+%%Pages: 0
+%%BeginSetup
+%%EndSetup
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+-130.0 296.0 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+%%EndProlog
+
+$F2psBegin
+10 setmiterlimit
+n -1000 5689 m -1000 -1000 l 8527 -1000 l 8527 5689 l cp clip
+ 0.06299 0.06299 sc
+% Polyline
+7.500 slw
+n 5265 3105 m 7515 3105 l 7515 3780 l 5265 3780 l cp gs col0 s gr 
+% Polyline
+n 5670 3105 m 5670 3780 l gs col0 s gr 
+% Polyline
+n 6120 3105 m 6120 3780 l gs col0 s gr 
+% Polyline
+n 6570 3105 m 6570 3780 l gs col0 s gr 
+% Polyline
+n 7020 3105 m 7020 3780 l gs col0 s gr 
+/Times-Roman ff 180.00 scf sf
+5400 4050 m
+gs 1 -1 sc (0) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+6300 4050 m
+gs 1 -1 sc (2) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+6750 4050 m
+gs 1 -1 sc (3) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+7245 4050 m
+gs 1 -1 sc (4) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5850 4050 m
+gs 1 -1 sc (1) col0 sh gr
+% Polyline
+n 2340 3105 m 4590 3105 l 4590 3780 l 2340 3780 l cp gs col0 s gr 
+% Polyline
+n 2745 3105 m 2745 3780 l gs col0 s gr 
+% Polyline
+n 3195 3105 m 3195 3780 l gs col0 s gr 
+% Polyline
+n 3645 3105 m 3645 3780 l gs col0 s gr 
+% Polyline
+n 4095 3105 m 4095 3780 l gs col0 s gr 
+/Times-Roman ff 180.00 scf sf
+2475 4050 m
+gs 1 -1 sc (0) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+3375 4050 m
+gs 1 -1 sc (2) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+3825 4050 m
+gs 1 -1 sc (3) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+4320 4050 m
+gs 1 -1 sc (4) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+2925 4050 m
+gs 1 -1 sc (1) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+2970 4320 m
+gs 1 -1 sc (local indices) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+2475 4635 m
+gs 1 -1 sc (local array in processor 0) col0 sh gr
+% Polyline
+n 3150 1215 m 6750 1215 l 6750 1890 l 3150 1890 l cp gs col0 s gr 
+% Polyline
+n 4950 1215 m 4950 1890 l gs col0 s gr 
+% Polyline
+n 4050 1215 m 4050 1890 l gs col0 s gr 
+% Polyline
+n 3600 1215 m 3600 1890 l gs col0 s gr 
+% Polyline
+n 4500 1215 m 4500 1890 l gs col0 s gr 
+% Polyline
+n 5850 1215 m 5850 1890 l gs col0 s gr 
+% Polyline
+n 5400 1215 m 5400 1890 l gs col0 s gr 
+% Polyline
+n 6300 1215 m 6300 1890 l gs col0 s gr 
+% Polyline
+n 2520 3105 m 3375 1890 l gs col0 s gr 
+% Polyline
+n 2970 3105 m 4230 1890 l gs col0 s gr 
+% Polyline
+n 3375 3105 m 6030 1890 l gs col0 s gr 
+% Polyline
+n 3825 3105 m 4725 1890 l gs col0 s gr 
+% Polyline
+n 5490 3105 m 3465 1890 l gs col0 s gr 
+% Polyline
+n 5850 3105 m 3870 1890 l gs col0 s gr 
+% Polyline
+n 6345 3105 m 6525 1890 l gs col0 s gr 
+% Polyline
+n 6795 3105 m 5625 1890 l gs col0 s gr 
+% Polyline
+n 7290 3105 m 5175 1890 l gs col0 s gr 
+% Polyline
+n 4320 3105 m 5535 1890 l gs col0 s gr 
+/Times-Roman ff 180.00 scf sf
+3285 1035 m
+gs 1 -1 sc (0) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+3735 1035 m
+gs 1 -1 sc (1) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+4230 1035 m
+gs 1 -1 sc (2) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+4680 1035 m
+gs 1 -1 sc (3) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5085 1035 m
+gs 1 -1 sc (4) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5535 1035 m
+gs 1 -1 sc (5) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5985 1035 m
+gs 1 -1 sc (6) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+6435 1035 m
+gs 1 -1 sc (7) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5940 4320 m
+gs 1 -1 sc (local indices) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5490 4635 m
+gs 1 -1 sc (local array in processor 1) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+3825 720 m
+gs 1 -1 sc (global array with global indices) col0 sh gr
+/Times-Italic ff 180.00 scf sf
+2880 1665 m
+gs 1 -1 sc (a:) col0 sh gr
+/Times-Italic ff 180.00 scf sf
+2070 3555 m
+gs 1 -1 sc (a0:) col0 sh gr
+/Times-Italic ff 180.00 scf sf
+4995 3555 m
+gs 1 -1 sc (a1:) col0 sh gr
+$F2psEnd
+rs

istl/Makefile.am

@@ -12,7 +12,7 @@ istl_HEADERS = $(SOURCES)
 # which documentation files should be put into special istl-only-tarball
 DISTDOCS = istl.tex istl.bib istl.ps istl.pdf \
 	comm/communication.pdf comm/communication.ps comm/indexset.cc \
-	comm/reverse.hh comm/buildindexset.hh
+	comm/reverse.hh comm/buildindexset.hh comm/figures/darray.eps
 
 # same for tutorial
 DISTTUT = tutorial/example.cc