--- manual/s_phys_pkgs/text/exch2.tex	2004/03/16 21:52:15	1.12
+++ manual/s_phys_pkgs/text/exch2.tex	2004/03/17 19:49:22	1.13
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/exch2.tex,v 1.12 2004/03/16 21:52:15 afe Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/exch2.tex,v 1.13 2004/03/17 19:49:22 afe Exp $
 % $Name:  $
 
 %%  * Introduction
@@ -21,7 +21,7 @@
 decomposition and parallelization.  Cube faces (also called
 subdomains) may be divided into any number of tiles that divide evenly
 into the grid point dimensions of the subdomain.  Furthermore, the
-individual tiles may be run on separate processors in different
+individual tiles can run on separate processors in different
 combinations, and whether exchanges between particular tiles occur
 between different processors is determined at runtime.  This
 flexibility provides for manual compile-time load balancing across a
@@ -65,15 +65,15 @@
   configurations other than the one you intend to modify.\\
 
 $\bullet$ Files containing grid parameters, named
-  \file{tile00$n$.mitgrid} where $n$=[1,6] (one per subdomain), must
-  be in the working directory when the MITgcm executable is run.
+  \file{tile00$n$.mitgrid} where $n$=\code{(1:6)} (one per subdomain),
+  must be in the working directory when the MITgcm executable is run.
   These files are provided in the example experiments for cubed sphere
   configurations with 32$\times$32 cube sides and are non-trivial to
   generate -- please contact MITgcm support if you want to generate
   files for other configurations. \\
 
 $\bullet$ As always when compiling MITgcm, the file \file{SIZE.h} must
-  be placed where \file{genmake2} will find it.  In particular for the
+  be placed where \file{genmake2} will find it.  In particular for
   exch2, the domain decomposition specified in \file{SIZE.h} must
   correspond with the particular configuration's topology specified in
   \file{W2\_EXCH2\_TOPOLOGY.h} and \file{w2\_e2setup.F}.  Domain
@@ -119,7 +119,7 @@
 The first three determine the size of the subdomains and
 hence the size of the overall domain.  Each one determines the number
 of grid points, and therefore the resolution, along the subdomain
-sides in a ``great circle'' around each axis of the cube.  At the time
+sides in a ``great circle'' around an axis of the cube.  At the time
 of this writing MITgcm requires these three parameters to be equal,
 but they provide for future releases  to accomodate different
 resolutions around the axes to allow (for example) greater resolution
@@ -129,7 +129,7 @@
 the tiles into which the subdomains are decomposed, and must evenly
 divide the integer assigned to \code{nr}, \code{nb} and \code{ng}.
 The result is a rectangular tiling of the subdomain.  Figure
-\ref{fig:24tile} shows one possible topology for a twenty-four tile
+\ref{fig:24tile} shows one possible topology for a twentyfour-tile
 cube, and figure \ref{fig:12tile} shows one for twelve tiles. \\
 
 \begin{figure}
@@ -139,9 +139,9 @@
  }
 \end{center} 
 
-\caption{Plot of cubed sphere topology with a 32$\times$192 domain
+\caption{Plot of a cubed sphere topology with a 32$\times$192 domain
 divided into six 32$\times$32 subdomains, each of which is divided into four tiles 
-(\code{tnx=16, tny=16}) for a total of twenty-four tiles.
+(\code{tnx=16, tny=16}) for a total of twentyfour tiles.
 } \label{fig:24tile}
 \end{figure}
 
@@ -151,12 +151,26 @@
   \includegraphics{part6/s12t_16x32.ps}
  }
 \end{center} 
-\caption{Plot of cubed sphere topology with a 32$\times$192 domain
+\caption{Plot of a cubed sphere topology with a 32$\times$192 domain
 divided into six 32$\times$32 subdomains of two tiles each
  (\code{tnx=16, tny=32}).
 } \label{fig:12tile}
 \end{figure}
 
+\begin{figure}
+\begin{center}
+ \resizebox{4in}{!}{
+  \includegraphics{part6/s6t_32x32.ps}
+ }
+\end{center} 
+\caption{Plot of a cubed sphere topology with a 32$\times$192 domain
+divided into six 32$\times$32 subdomains with one tile each
+(\code{tnx=32, tny=32}).  This is the default configuration.
+  }
+\label{fig:6tile}
+\end{figure}
+
+
 Tiles can be selected from the topology to be omitted from being
 allocated memory and processors.  This tuning is useful in ocean
 modeling for omitting tiles that fall entirely on land.  The tiles
@@ -171,12 +185,13 @@
 \label{sec:exch2mpi}
 
 Once the topology configuration files are created, the Fortran
-parameters in \file{SIZE.h} must be configured to match.  Section
-\ref{sect:specifying_a_decomposition} \sectiontitle{Specifying a
-decomposition} provides a general description of domain decomposition
-within MITgcm and its relation to \file{SIZE.h}. The current section
-specifies certain constraints the exch2 package imposes as well as
-describes how to enable parallel execution with MPI. \\
+\code{PARAMETER}s in \file{SIZE.h} must be configured to match.
+Section \ref{sect:specifying_a_decomposition} \sectiontitle{Specifying
+a decomposition} provides a general description of domain
+decomposition within MITgcm and its relation to \file{SIZE.h}. The
+current section specifies certain constraints the exch2 package
+imposes as well as describes how to enable parallel execution with
+MPI. \\
 
 As in the general case, the parameters \varlink{sNx}{sNx} and
 \varlink{sNy}{sNy} define the size of the individual tiles, and so
@@ -266,19 +281,19 @@
 The scalar parameters \varlink{exch2\_domain\_nxt}{exch2_domain_nxt}
 and \varlink{exch2\_domain\_nyt}{exch2_domain_nyt} express the number
 of tiles in the $x$ and $y$ global indices.  For example, the default
-setup of six tiles has \code{exch2\_domain\_nxt=6} and
+setup of six tiles (Fig. \ref{fig:6tile}) has \code{exch2\_domain\_nxt=6} and
 \code{exch2\_domain\_nyt=1}.  A topology of twenty-four square tiles,
 four per subdomain (as in figure \ref{fig:24tile}), will have
 \code{exch2\_domain\_nxt=12} and \code{exch2\_domain\_nyt=2}.  Note
 that these parameters express the tile layout to allow global data
 files that are tile-layout-neutral and have no bearing on the internal
 storage of the arrays.  The tiles are internally stored in a range
-from [1,\varlink{bi}{bi}] the $x$ axis and $y$ axis variable
+from \code{(1:\varlink{bi}{bi})} the $x$ axis, and $y$ axis variable
 \varlink{bj}{bj} is generally ignored within the package. \\
 
 \subsubsection{Arrays Indexed to Tile Number}
 
-The following arrays are of size \code{NTILES}, are indexed to the
+The following arrays are of length \code{NTILES}, are indexed to the
 tile number, and the indices are omitted in their descriptions. \\
 
 The arrays \varlink{exch2\_tnx}{exch2_tnx} and
@@ -293,21 +308,28 @@
 determined by the arrays \varlink{exch2\_tbasex}{exch2_tbasex} and
 \varlink{exch2\_tbasey}{exch2_tbasey}.  These variables are used to
 relate the location of the edges of different tiles to each other.  As
-an example, in the default six-tile topology ??  each index in these
-arrays are set to \code{0}.  The twentyfour-tile case discussed above
-will have values of \code{0} or \code{16}, depending on the quadrant
-the tile falls within the subdomain.  The array
-\varlink{exch2\_myFace}{exch2_myFace} contains the number of the
-subdomain of each tile, numbered \code{(1:6)} in the case of the
-standard cube topology and indicated by \textbf{\textsf{f}}$n$ in
-figures \ref{fig:12tile}) and \ref{fig:24tile}). \\
-
-The elements of the arrays \varlink{exch2\_txglobalo}{exch2_txglobalo}
-and \varlink{exch2\_txglobalo}{exch2_txglobalo} are similar to
+an example, in the default six-tile topology (Fig. \ref{fig:6tile})
+each index in these arrays is set to \code{0} since a tile occupies
+its entire subdomain.  The twentyfour-tile case discussed above will
+have values of \code{0} or \code{16}, depending on the quadrant the
+tile falls within the subdomain.  The elements of the arrays
+\varlink{exch2\_txglobalo}{exch2_txglobalo} and
+\varlink{exch2\_txglobalo}{exch2_txglobalo} are similar to
 \varlink{exch2\_tbasex}{exch2_tbasex} and
 \varlink{exch2\_tbasey}{exch2_tbasey}, but locate the tiles within the
 global address space, similar to that used by global files. \\
 
+The array \varlink{exch2\_myFace}{exch2_myFace} contains the number of
+the subdomain of each tile, in a range \code{(1:6)} in the case of the
+standard cube topology and indicated by \textbf{\textsf{f}}$n$ in
+figures \ref{fig:12tile} and
+\ref{fig:24tile}. \varlink{exch2\_nNeighbours}{exch2_nNeighbours}
+contains a count of how many neighboring tiles each tile has, and is
+used for setting bounds for looping over neighboring tiles.
+\varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each
+tile, and is used in interprocess communication.  \\
+
+
 The arrays \varlink{exch2\_isWedge}{exch2_isWedge},
 \varlink{exch2\_isEedge}{exch2_isEedge},
 \varlink{exch2\_isSedge}{exch2_isSedge}, and
@@ -317,11 +339,8 @@
 orientation of neighboring tiles, and to indicate whether a tile lies
 on the corner of a subdomain.  The latter case requires special
 exchange and numerical handling for the singularities at the eight
-corners of the cube.  \varlink{exch2\_nNeighbours}{exch2_nNeighbours}
-contains a count of how many neighboring tiles each tile has, and is
-used for setting bounds for looping over neighboring tiles.
-\varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each
-tile, and is used in interprocess communication.  \\
+corners of the cube. \\
+
 
 \subsubsection{Arrays Indexed to Tile Number and Neighbor}
 
@@ -336,6 +355,7 @@
 to bottom on the east and west edges.  Maybe throw in a fig here, eh?
 \\
 
+\sloppy
 The \code{exch2\_opposingSend\_record(a,T)} array holds the index
 \code{b} in \texttt{exch2\_neighbourId(b,Tn)} that holds the tile
 number \code{T}.  In other words,
@@ -345,36 +365,51 @@
 \end{verbatim}
 This provides a back-reference from the neighbor tiles. \\
 
-The arrays \varlink{exch2\_pi}{exch2_pi},
-\varlink{exch2\_pj}{exch2_pj}, \varlink{exch2\_oi}{exch2_oi},
-\varlink{exch2\_oj}{exch2_oj}, \varlink{exch2\_oi\_f}{exch2_oi_f}, and
-\varlink{exch2\_oj\_f}{exch2_oj_f} specify the transformations in
-exchanges between the neighboring tiles.  The dimensions of
-\code{exch2\_pi(t,N,T)} and \code{exch2\_pj(t,N,T)} are the neighbor
-ID \code{N} and the tile number \code{T} as explained above, plus a
-vector of length 2 containing transformation factors \code{t}.  The
-first element of the transformation vector indicates the factor
-\code{t} by which variables representing the same vector component of
-a tile \code{T} will be multiplied in exchanges with neighbor
-\code{N}, and the second element indicates the transform to the
-variable in the other direction.  As an example,
-\code{exch2\_pi(1,N,T)} holds the transform of the $i$ component of a
-vector variable in tile \code{T} to the $i$ component of tile
-\code{T}'s neighbor \code{N}, and \code{exch2\_pi(2,N,T)} hold the
-component of neighbor \code{N}'s $j$ component. \\
+The arrays \varlink{exch2\_pi}{exch2_pi} and
+\varlink{exch2\_pj}{exch2_pj} specify the transformations of variables
+in exchanges between the neighboring tiles.  These transformations are
+necessary in exchanges between subdomains because a physical vector
+component in one direction may map to one in a different direction in
+an adjacent subdomain, and may be have its indexing reversed. This
+swapping arises from the ``folding'' of two-dimensional arrays into a
+three-dimensional cube.
+
+The dimensions of \code{exch2\_pi(t,N,T)} and \code{exch2\_pj(t,N,T)}
+are the neighbor ID \code{N} and the tile number \code{T} as explained
+above, plus a vector of length 2 containing transformation factors
+\code{t}.  The first element of the transformation vector indicates
+the factor \code{t} by which variables representing the same
+\emph{physical} vector component of a tile \code{T} will be multiplied
+in exchanges with neighbor \code{N}, and the second element indicates
+the transform to the physical vector in the other direction.  To
+clarify (hopefully), \code{exch2\_pi(1,N,T)} holds the transform of
+the $i$ component of a vector variable in tile \code{T} to the $i$
+component of tile \code{T}'s neighbor \code{N}, and
+\code{exch2\_pi(2,N,T)} holds the transform of \code{T}'s $i$
+components to the neighbor \code{N}'s $j$ component. \\
  
 Under the current cube topology, one of the two elements of
 \code{exch2\_pi} or \code{exch2\_pj} for a given tile \code{T} and
 neighbor \code{N} will be \code{0}, reflecting the fact that the two
-vector components are orthogonal.  The other element will be 1 or -1,
-depending on whether the components are indexed in the same or
-opposite directions.  For example, the transform vector of the arrays
-for all tile neighbors on the same subdomain will be \code{(1,0)},
-since all tiles on the same subdomain are oriented identically.  A
-vector direction that corresponds to the orthogonal dimension with the
-same index direction in a particular tile-neighbor orientation will
-have \code{(0,1)}, whereas those in the opposite index direction will
-have \code{(0,-1)}.  This needs some diagrams.
+vector components are orthogonal.  The other element will be \code{1}
+or \code{-1}, depending on whether the components are indexed in the
+same or opposite directions.  For example, the transform vector of the
+arrays for all tile neighbors on the same subdomain will be
+\code{(1,0)}, since all tiles on the same subdomain are oriented
+identically.  A vector direction that corresponds to the orthogonal
+dimension with the same index direction in a particular tile-neighbor
+orientation will have \code{(0,1)}, whereas those in the opposite
+index direction will have \code{(0,-1)}. \\
+
+
+\varlink{exch2\_oi}{exch2_oi},
+\varlink{exch2\_oj}{exch2_oj}, \varlink{exch2\_oi\_f}{exch2_oi_f}, and
+\varlink{exch2\_oj\_f}{exch2_oj_f}
+
+
+
+
+This needs some diagrams. \\
 
 
 {\footnotesize
