Information and diagrams for computational grid partitioning, pointing out that irregular partitions are not possible

git-svn-id: http://svn.cactuscode.org/arrangements/CactusPUGH/PUGH/trunk@370 b61c5cb5-eaca-4651-9a7a-d64986f99364

3 files changed, 240 insertions, 10 deletions

diff --git a/doc/Partitioning.eps b/doc/Partitioning.eps
new file mode 100644
index 0000000..fefe952
--- /dev/null
+++ b/doc/Partitioning.eps
@@ -0,0 +1,162 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: Partitioning.eps
+%%Creator: fig2dev Version 3.2.3 Patchlevel 
+%%CreationDate: Sat Feb 23 16:11:02 2002
+%%For: allen@gullveig.aei.mpg.de (Gab)
+%%BoundingBox: 0 0 850 239
+%%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
+newpath 0 239 moveto 0 0 lineto 850 0 lineto 850 239 lineto closepath clip newpath
+% Fill background color
+0 0 moveto 850 0 lineto 850 239 lineto 0 239 lineto
+closepath 1.00 1.00 1.00 setrgbcolor fill
+
+-34.0 299.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
+
+$F2psBegin
+%%Page: 1 1
+10 setmiterlimit
+ 0.06000 0.06000 sc
+% Polyline
+7.500 slw
+n 1200 1200 m 4800 1200 l 4800 4800 l 1200 4800 l
+ cp gs col0 s gr 
+% Polyline
+n 1200 2400 m
+ 4800 2400 l gs col0 s gr 
+% Polyline
+n 1200 3600 m
+ 4800 3600 l gs col0 s gr 
+% Polyline
+n 2400 1200 m
+ 2400 4800 l gs col0 s gr 
+% Polyline
+n 3600 1200 m
+ 3600 4800 l gs col0 s gr 
+% Polyline
+n 6000 1200 m 9600 1200 l 9600 4800 l 6000 4800 l
+ cp gs col0 s gr 
+% Polyline
+n 6000 1650 m
+ 9600 1650 l gs col0 s gr 
+% Polyline
+n 6000 2550 m
+ 9600 2550 l gs col0 s gr 
+% Polyline
+n 8175 1200 m
+ 8175 4800 l gs col0 s gr 
+% Polyline
+n 8550 1200 m
+ 8550 4800 l gs col0 s gr 
+% Polyline
+n 10950 1200 m 14550 1200 l 14550 4800 l 10950 4800 l
+ cp gs col0 s gr 
+% Polyline
+n 10950 2400 m
+ 14550 2400 l gs col0 s gr 
+% Polyline
+n 10950 3600 m
+ 14550 3600 l gs col0 s gr 
+% Polyline
+n 11700 1200 m
+ 11700 2400 l gs col0 s gr 
+% Polyline
+n 13350 1200 m
+ 13350 2400 l gs col0 s gr 
+% Polyline
+n 12450 2400 m
+ 12450 3600 l gs col0 s gr 
+% Polyline
+n 14250 2400 m
+ 14250 3600 l gs col0 s gr 
+% Polyline
+n 12150 3600 m
+ 12150 4800 l gs col0 s gr 
+% Polyline
+n 13050 3600 m
+ 13050 4800 l gs col0 s gr 
+/Times-Roman ff 450.00 scf sf
+750 1575 m
+gs 1 -1 sc (a\)) col0 sh gr
+/Times-Roman ff 450.00 scf sf
+5475 1575 m
+gs 1 -1 sc (b\)) col0 sh gr
+/Times-Roman ff 450.00 scf sf
+10500 1575 m
+gs 1 -1 sc (c\)) col0 sh gr
+$F2psEnd
+rs
diff --git a/doc/Partitioning.fig b/doc/Partitioning.fig
new file mode 100644
index 0000000..c63a9b4
--- /dev/null
+++ b/doc/Partitioning.fig
@@ -0,0 +1,50 @@
+#FIG 3.2
+Landscape
+Center
+Inches
+Letter  
+100.00
+Single
+-2
+1200 2
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 1200 1200 4800 1200 4800 4800 1200 4800 1200 1200
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 1200 2400 4800 2400
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 1200 3600 4800 3600
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 2400 1200 2400 4800
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 3600 1200 3600 4800
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 6000 1200 9600 1200 9600 4800 6000 4800 6000 1200
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 6000 1650 9600 1650
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 6000 2550 9600 2550
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 8175 1200 8175 4800
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 8550 1200 8550 4800
+2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5
+	 10950 1200 14550 1200 14550 4800 10950 4800 10950 1200
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 10950 2400 14550 2400
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 10950 3600 14550 3600
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 11700 1200 11700 2400
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 13350 1200 13350 2400
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 12450 2400 12450 3600
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 14250 2400 14250 3600
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 12150 3600 12150 4800
+2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 2
+	 13050 3600 13050 4800
+4 0 0 50 0 0 30 0.0000 4 405 345 750 1575 a)\001
+4 0 0 50 0 0 30 0.0000 4 405 360 5475 1575 b)\001
+4 0 0 50 0 0 30 0.0000 4 405 345 10500 1575 c)\001
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 73982d0..47d7926 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -147,16 +147,34 @@ driver::periodic_z = "no"
 \section{Load Balancing}
 
 By default PUGH will distribute the computational grid evenly across
-all processors. This may not be efficient if there is a different
-computational load on different processors, or for example for a simulation
-distributed across different processor speeds. 
-
-The computational grid can be manually distributed using the parameters
-{\tt partition[\_1d\_x|\_2d\_x|\_2d\_y|\_3d\_x|\_3d\_y|\_3d\_z]}. To manual specify the 
-load distribution, set {\tt pugh::partition = ``manual''} and then, 
-depending on the grid dimension, set the remaining parameters 
-to distribute the load in each direction. Note that for this you need
-to know apriori the processor decomposition. 
+all processors (as in Figure~\ref{pugh::fig2}a). This may not be
+efficient if there is a different computational load on different
+processors, or for example for a simulation distributed across
+different processor speeds.
+
+\begin{figure}[ht]
+\begin{center}
+\ifpdf
+\else
+\includegraphics[angle=0,width=12cm]{Partitioning.eps}
+\fi
+\end{center}
+\caption[]{Partitioning of the computational grid across processors, Figure~a) is the default type of partition used by {\tt PUGH}, Figure~b) can be set
+manually, and Figure~c) is not possible with {\tt PUGH}} 
+\label{pugh::fig2}
+\end{figure}
+
+The computational grid can be manually partitioned in a regularly way 
+as in Figure~\ref{pugh::fig2}b. (Note that the type of partitioning 
+shown in Figure~\ref{pugh::fig2}c is not possible with {\tt PUGH}).
+
+The computational grid can be manually distributed using the
+parameters {\tt
+partition[\_1d\_x|\_2d\_x|\_2d\_y|\_3d\_x|\_3d\_y|\_3d\_z]}. To manual
+specify the load distribution, set {\tt pugh::partition = ``manual''}
+and then, depending on the grid dimension, set the remaining
+parameters to distribute the load in each direction. Note that for
+this you need to know apriori the processor decomposition.
 
 The decomposition is easiest to explain with an example,
 to distribute a grid with $30 \times 30$ points across