--- manual/s_phys_pkgs/text/exch2.tex	2004/01/29 17:55:35	1.4
+++ manual/s_phys_pkgs/text/exch2.tex	2004/02/11 20:48:14	1.7
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/exch2.tex,v 1.4 2004/01/29 17:55:35 afe Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/exch2.tex,v 1.7 2004/02/11 20:48:14 afe Exp $
 % $Name:  $
 
 %%  * Introduction
@@ -36,10 +36,13 @@
 \subsection{Key Variables}
 
 The descriptions of the variables are divided up into scalars,
-one-dimensional arrays indexed to the tile number, and two-dimensional
+one-dimensional arrays indexed to the tile number, and two and three 
+dimensional
 arrays indexed to tile number and neighboring tile.  This division
-actually reflects  the functionality of these variables, not just the
-whim of some FORTRAN enthusiast.
+actually reflects  the functionality of these variables: the scalars
+are common to every part of the topology, the tile-indexed arrays to 
+individual tiles, and the arrays indexed to tile and neighbor to 
+relationships between tiles and their neighbors.
 
 \subsubsection{Scalars}
 
@@ -60,10 +63,10 @@
 arrays.  The tiles are internally stored in a range from {\em 1,bi} (in the
 x axis) and y-axis variable {\em bj} is generally ignored within the package.
 
-\subsubsection{One-Dimensional Arrays}
+\subsubsection{Arrays Indexed to Tile Number}
 
-The following arrays are indexed to the tile number, and the indices are
-omitted in their descriptions.
+The following arrays are of size {\em NTILES}, are indexed to the tile number, 
+and the indices are omitted in their descriptions.
 
 The arrays {\em exch2\_tnx} and {\em exch2\_tny} 
 express the x and y dimensions of each tile.  At present for each tile
@@ -72,36 +75,86 @@
 MITgcm are to allow varying tile sizes.
 
 The location of the tiles' Cartesian origin within a subdomain are determined 
-by the arrays {\em exch2\_tbasex} and {\em exch2\_tbasey}.  These
+by the arrays {\em exch2\_tbasex} and {\em exch2\_tbasey}.  These variables
+are used to relate the location of the edges of the tiles to each other.  As 
+an example, in the default six-tile topology (the degenerate case) 
+each index in these arrays are 
+set to 0.  The twenty-four, 32x32 cube face case discussed above will have
+values of 0 or 16, depending on the quadrant the tile falls within the 
+subdomain.  {\em exch2\_myFace} contains the number of the 
+cubeface/subdomain of each tile, numbered 1-6 in the case of the standard
+cube topology.  
+
+The arrays {\em exch2\_txglobalo} and {\em exch2\_txglobalo} are similar to
+{\em exch2\_tbasex} and {\em exch2\_tbasey}, but locate the tiles within
+the global address space, similar to that used by global files.  
+
+The arrays {\em exch2\_isWedge}, {\em exch2\_isEedge}, {\em exch2\_isSedge}, 
+and {\em exch2\_isNedge} are set to 1 if the indexed tile lies on the edge
+of a subdomain, 0 if not.  The values are used within the topology generator
+to determine the orientation of neighboring tiles and to indicate whether 
+a tile lies on the corner of a subdomain.  The latter case indicates 
+special exchange and numerical handling for the singularities at the eight 
+corners of the cube.  {\em exch2\_isNedge} contains a count of how many
+neighboring tiles each tile has, and is used for setting bounds for looping
+over neighboring tiles.  {\em exch2\_tProc} holds the process rank of each tile,
+and is used in interprocess communication.
+
+\subsubsection{Arrays Indexed to Tile Number and Neighbor}
+
+The following arrays are all of size {\em MAX\_NEIGHBOURS}x{\em NTILES} and
+describe the orientations between the the tiles.
+
+The array {\em exch2\_neighbourId(a,T)} holds the tile number $T_{n}$ for each tile 
+{\em T}'s neighbor tile {\em a}.  The neighbor tiles are indexed {\em 1,MAX\_NEIGHBOURS }
+in the order right to left on the north then south edges, and then top to bottom on the east 
+and west edges. maybe throw in a fig here, eh?  
+
+{\em exch2\_opposingSend\_record(a,T)} holds 
+the index c in {\em exch2\_neighbourId(b,$T_{n}$)} that holds the tile number T.
+In other words,
+
+\begin{verbatim}   
+exch2_neighbourId( exch2_opposingSend_record(a,T), 
+                           exch2_neighbourId(a,T) ) = T
+\end{verbatim}
+
+% {\em exch2\_neighbourId(exch2\_opposingSend\_record(a,T),exch2\_neighbourId(a,T))=T}.
+% alternate version
+
+This is to provide a backreference from the neighbor tiles.
+
+The arrays {\em exch2\_pi }, {\em exch2\_pj }, {\em exch2\_oi }, 
+{\em exch2\_oj }, {\em exch2\_oi\_f }, and {\em exch2\_oj\_f }  specify 
+the transformations in exchanges between the neighboring tiles.  The dimensions  
+of {\em exch2\_pi(t,N,T) } and {\em exch2\_pj(t,N,T) } are the neighbor ID 
+{ \em N } and the tile number {\em T } as explained above, plus the transformation
+vector {\em t }, of length two.  The first element of the transformation vector indicates
+the factor by which variables representing the same vector component  of a tile 
+will be multiplied, and the second element indicates the transform to the 
+variable in the other direction.  As an example, {\em exch2\_pi(1,N,T) } holds the 
+transform of the i-component of a vector variable in tile {\em T } to the i-component of 
+tile  {\em T }'s neighbor  {\em N }, and {\em exch2\_pi(2,N,T) } hold the component 
+of neighbor  {\em N }'s j-component.
+
+Under the current cube topology, one of the two elements of {\em exch2\_pi } or {\em exch2\_pj }
+for a given tile   {\em T } and  neighbor  {\em N } will be 0, reflecting the fact that
+the 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 dimension
+of the arrays for all tile neighbors on the same subdomain will be {\em [1 , 0] }, since all tiles on 
+the same subdomain are oriented identically.  Vectors that correspond to the orthogonal dimension with the 
+same index direction will have {\em [0 , 1] }, whereas those in the opposite index direction will have
+{\em [0 , -1] }.
+
 
-\subsubsection{Two-Dimensional Arrays}
 
 
 //
 
 \begin{verbatim}
-C      NTILES            :: Number of tiles in this topology 
-C      MAX_NEIGHBOURS    :: Maximum number of neighbours any tile has.
-C      exch2_domain_nxt  :: Total domain length in tiles. 
-C      exch2_domain_nyt  :: Maximum domain height in tiles. 
-C      exch2_tnx         :: Size in X for each tile.                  
-C      exch2_tny         :: Size in Y for each tile.                  
-C      exch2_tbasex      :: Tile offset in X within its sub-domain (cube face)
-C      exch2_tbasey      :: Tile offset in Y within its sub-domain (cube face)
-C      exch2_tglobalxlo  :: Tile base X index within global index space.
-C      exch2_tglobalylo  :: Tile base Y index within global index space.
-C      exch2_isWedge     :: 0 if West not at domain edge, 1 if it is.   
-C      exch2_isNedge     :: 0 if North not at domain edge, 1 if it is.   
-C      exch2_isEedge     :: 0 if East not at domain edge, 1 if it is.   
-C      exch2_isSedge     :: 0 if South not at domain edge, 1 if it is.   
-C      exch2_myFace      :: Cube face number used for I/O.               
-C      exch2_nNeighbours :: Tile neighbour entries count.               
-C      exch2_tProc       :: Rank of process owning tile                 
-C                        :: (filled at run time).                       
-C      exch2_neighbourId :: Tile number for each neighbour entry.        
-C      exch2_opposingSend_record :: Record for entry in target tile send 
-C                                :: list that has this tile and face     
-C                                :: as its target.                       
+
+
+
 C      exch2_pi          :: X index row of target to source permutation 
 C                        :: matrix for each neighbour entry.            
 C      exch2_pj          :: Y index row of target to source permutation 
