/[MITgcm]/manual/s_phys_pkgs/text/exch2.tex
ViewVC logotype

Diff of /manual/s_phys_pkgs/text/exch2.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.18 by afe, Thu May 6 15:21:01 2004 UTC revision 1.19 by afe, Mon May 10 21:39:11 2004 UTC
# Line 54  $\bullet$ The exch2 package is included Line 54  $\bullet$ The exch2 package is included
54    
55  $\bullet$ An example of \file{W2\_EXCH2\_TOPOLOGY.h} and  $\bullet$ An example of \file{W2\_EXCH2\_TOPOLOGY.h} and
56    \file{w2\_e2setup.F} must reside in a directory containing files    \file{w2\_e2setup.F} must reside in a directory containing files
57    symbolically linked when \file{genmake2} runs.  The safest place to    symbolically linked by the \file{genmake2} script.  The safest place to
58    put these is the directory indicated in the \code{-mods=DIR} command    put these is the directory indicated in the \code{-mods=DIR} command
59    line modifier (typically \file{../code}), or the build directory.    line modifier (typically \file{../code}), or the build directory.
60    The default versions of these files reside in \file{pkg/exch2} and    The default versions of these files reside in \file{pkg/exch2} and
# Line 77  $\bullet$ As always when compiling MITgc Line 77  $\bullet$ As always when compiling MITgc
77    \file{W2\_EXCH2\_TOPOLOGY.h} and \file{w2\_e2setup.F}.  Domain    \file{W2\_EXCH2\_TOPOLOGY.h} and \file{w2\_e2setup.F}.  Domain
78    decomposition issues particular to exch2 are addressed in Section    decomposition issues particular to exch2 are addressed in Section
79    \ref{sec:topogen} \sectiontitle{Generating Topology Files for exch2}    \ref{sec:topogen} \sectiontitle{Generating Topology Files for exch2}
80    and \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and MPI}; a more    and \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and Multiprocessing}; a more
81    general background on the subject relevant to MITgcm is presented in    general background on the subject relevant to MITgcm is presented in
82    Section \ref{sect:specifying_a_decomposition}    Section \ref{sect:specifying_a_decomposition}
83    \sectiontitle{Specifying a decomposition}.\\    \sectiontitle{Specifying a decomposition}.\\
# Line 107  from the Matlab prompt (there are no par Line 107  from the Matlab prompt (there are no par
107  exch2 topology files \file{W2\_EXCH2\_TOPOLOGY.h} and  exch2 topology files \file{W2\_EXCH2\_TOPOLOGY.h} and
108  \file{w2\_e2setup.F} in the working directory and displays a figure of  \file{w2\_e2setup.F} in the working directory and displays a figure of
109  the topology via Matlab -- figures \ref{fig:6tile}, \ref{fig:12tile},  the topology via Matlab -- figures \ref{fig:6tile}, \ref{fig:12tile},
110  and \ref{fig:24tile} are examples.  The other m-files in the directory are  and \ref{fig:24tile} are examples of the generated diagrams.  The other
111  subroutines of \file{driver.m} and should not be run ``bare'' except  m-files in the directory are
112    subroutines called from \file{driver.m} and should not be run ``bare'' except
113  for development purposes. \\  for development purposes. \\
114    
115  The parameters that determine the dimensions and topology of the  The parameters that determine the dimensions and topology of the
116  generated configuration are \code{nr}, \code{nb}, \code{ng},  generated configuration are \code{nr}, \code{nb}, \code{ng},
117  \code{tnx} and \code{tny}, and all are assigned early in the script. \\  \code{tnx} and \code{tny}, and all are assigned early in the script. \\
118    
119  The first three determine the size of the subdomains and  The first three determine the height and width of the subdomains and
120  hence the size of the overall domain.  Each one determines the number  hence the size of the overall domain.  Each one determines the number
121  of grid points, and therefore the resolution, along the subdomain  of grid points, and therefore the resolution, along the subdomain
122  sides in a ``great circle'' around each the three spatial axes of the cube.  At the time  sides in a ``great circle'' around each the three spatial axes of the cube.  At the time
123  of this writing MITgcm requires these three parameters to be equal,  of this writing MITgcm requires these three parameters to be equal,
124  but they provide for future releases  to accomodate different  but they provide for future releases  to accomodate different
125  resolutions around the axes to allow (for example) greater resolution  resolutions around the axes to allow subdomains with differing resolutions.\\
 around the equator.\\  
126    
127  The parameters \code{tnx} and \code{tny} determine the width and height of  The parameters \code{tnx} and \code{tny} determine the width and height of
128  the tiles into which the subdomains are decomposed, and must evenly  the tiles into which the subdomains are decomposed, and must evenly
# Line 182  by their tile number in the topology, se Line 182  by their tile number in the topology, se
182    
183    
184    
185  \subsection{exch2, SIZE.h, and multiprocessing}  \subsection{exch2, SIZE.h, and Multiprocessing}
186  \label{sec:exch2mpi}  \label{sec:exch2mpi}
187    
188  Once the topology configuration files are created, the Fortran  Once the topology configuration files are created, the Fortran
# Line 190  Once the topology configuration files ar Line 190  Once the topology configuration files ar
190  Section \ref{sect:specifying_a_decomposition} \sectiontitle{Specifying  Section \ref{sect:specifying_a_decomposition} \sectiontitle{Specifying
191  a decomposition} provides a general description of domain  a decomposition} provides a general description of domain
192  decomposition within MITgcm and its relation to \file{SIZE.h}. The  decomposition within MITgcm and its relation to \file{SIZE.h}. The
193  current section specifies certain constraints the exch2 package  current section specifies constraints that the exch2 package
194  imposes as well as describes how to enable parallel execution with  imposes and describes how to enable parallel execution with
195  MPI. \\  MPI. \\
196    
197  As in the general case, the parameters \varlink{sNx}{sNx} and  As in the general case, the parameters \varlink{sNx}{sNx} and
# Line 207  levels in the model.\\ Line 207  levels in the model.\\
207  The parameters \varlink{nSx}{nSx}, \varlink{nSy}{nSy},  The parameters \varlink{nSx}{nSx}, \varlink{nSy}{nSy},
208  \varlink{nPx}{nPx}, and \varlink{nPy}{nPy} relate to the number of  \varlink{nPx}{nPx}, and \varlink{nPy}{nPy} relate to the number of
209  tiles and how they are distributed on processors.  When using exch2,  tiles and how they are distributed on processors.  When using exch2,
210  the tiles are stored in a single dimension, and so  the tiles are stored in the $x$ dimension, and so
211  \code{\varlink{nSy}{nSy}=1} in all cases.  Since the tiles as  \code{\varlink{nSy}{nSy}=1} in all cases.  Since the tiles as
212  configured by exch2 cannot be split up accross processors without  configured by exch2 cannot be split up accross processors without
213  regenerating the topology, \code{\varlink{nPy}{nPy}=1} as well. \\  regenerating the topology, \code{\varlink{nPy}{nPy}=1} as well. \\
# Line 215  regenerating the topology, \code{\varlin Line 215  regenerating the topology, \code{\varlin
215  The number of tiles MITgcm allocates and how they are distributed  The number of tiles MITgcm allocates and how they are distributed
216  between processors depends on \varlink{nPx}{nPx} and  between processors depends on \varlink{nPx}{nPx} and
217  \varlink{nSx}{nSx}.  \varlink{nSx}{nSx} is the number of tiles per  \varlink{nSx}{nSx}.  \varlink{nSx}{nSx} is the number of tiles per
218  processor and \varlink{nPx}{nPx} the number of processors.  The total  processor and \varlink{nPx}{nPx} is the number of processors.  The total
219  number of tiles in the topology minus those listed in  number of tiles in the topology minus those listed in
220  \file{blanklist.txt} must equal \code{nSx*nPx}. \\  \file{blanklist.txt} must equal \code{nSx*nPx}.  Note that in order to
221    obtain maximum usage from a given number of processors in some cases,
222    this restriction might entail sharing a processor with a tile that would
223    otherwise be excluded. \\
224    
225  The following is an example of \file{SIZE.h} for the twelve-tile  The following is an example of \file{SIZE.h} for the twelve-tile
226  configuration illustrated in figure \ref{fig:12tile} running on  configuration illustrated in figure \ref{fig:12tile} running on
# Line 287  setup of six tiles (Fig. \ref{fig:6tile} Line 290  setup of six tiles (Fig. \ref{fig:6tile}
290  topology of twenty-four square tiles, four per subdomain (as in figure  topology of twenty-four square tiles, four per subdomain (as in figure
291  \ref{fig:24tile}), will have \code{exch2\_domain\_nxt=12} and  \ref{fig:24tile}), will have \code{exch2\_domain\_nxt=12} and
292  \code{exch2\_domain\_nyt=2}.  Note that these parameters express the  \code{exch2\_domain\_nyt=2}.  Note that these parameters express the
293  tile layout to allow global data files that are tile-layout-neutral  tile layout in order to allow global data files that are tile-layout-neutral.
294  and have no bearing on the internal storage of the arrays.  The tiles  They have no bearing on the internal storage of the arrays.  The tiles
295  are stored internally in a range from \code{(1:\varlink{bi}{bi})} the  are stored internally in a range from \code{\varlink{bi}{bi}=(1:NTILES)} in the
296  $x$ axis, and the $y$ axis variable \varlink{bj}{bj} is assumed to  $x$ axis, and the $y$ axis variable \varlink{bj}{bj} is assumed to
297  equal \code{1} throughout the package. \\  equal \code{1} throughout the package. \\
298    
299  \subsubsection{Arrays Indexed to Tile Number}  \subsubsection{Arrays indexed to tile number}
300    
301  The following arrays are of length \code{NTILES} and are indexed to  The following arrays are of length \code{NTILES} and are indexed to
302  the tile number, which is indicated in the diagrams with the notation  the tile number, which is indicated in the diagrams with the notation
# Line 303  The arrays \varlink{exch2\_tnx}{exch2_tn Line 306  The arrays \varlink{exch2\_tnx}{exch2_tn
306  \varlink{exch2\_tny}{exch2_tny} express the $x$ and $y$ dimensions of  \varlink{exch2\_tny}{exch2_tny} express the $x$ and $y$ dimensions of
307  each tile.  At present for each tile \texttt{exch2\_tnx=sNx} and  each tile.  At present for each tile \texttt{exch2\_tnx=sNx} and
308  \texttt{exch2\_tny=sNy}, as assigned in \file{SIZE.h} and described in  \texttt{exch2\_tny=sNy}, as assigned in \file{SIZE.h} and described in
309  section \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and  Section \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and
310  multiprocessing}.  Future releases of MITgcm may allow varying tile  Multiprocessing}.  Future releases of MITgcm may allow varying tile
311  sizes. \\  sizes. \\
312    
313  The location of the tiles' Cartesian origin within a subdomain are  The arrays \varlink{exch2\_tbasex}{exch2_tbasex} and
314  determined by the arrays \varlink{exch2\_tbasex}{exch2_tbasex} and  \varlink{exch2\_tbasey}{exch2_tbasey} determine the tiles'
315  \varlink{exch2\_tbasey}{exch2_tbasey}.  These variables are used to  Cartesian origin within a subdomain  
316  relate the location of the edges of different tiles to each other.  As  and locate the edges of different tiles relative to each other.  As
317  an example, in the default six-tile topology (Fig. \ref{fig:6tile})  an example, in the default six-tile topology (Fig. \ref{fig:6tile})
318  each index in these arrays is set to \code{0} since a tile occupies  each index in these arrays is set to \code{0} since a tile occupies
319  its entire subdomain.  The twenty-four-tile case discussed above will  its entire subdomain.  The twenty-four-tile case discussed above will
320  have values of \code{0} or \code{16}, depending on the quadrant the  have values of \code{0} or \code{16}, depending on the quadrant of the
321  tile falls within the subdomain.  The elements of the arrays  tile within the subdomain.  The elements of the arrays
322  \varlink{exch2\_txglobalo}{exch2_txglobalo} and  \varlink{exch2\_txglobalo}{exch2_txglobalo} and
323  \varlink{exch2\_txglobalo}{exch2_txglobalo} are similar to  \varlink{exch2\_txglobalo}{exch2_txglobalo} are similar to
324  \varlink{exch2\_tbasex}{exch2_tbasex} and  \varlink{exch2\_tbasex}{exch2_tbasex} and
325  \varlink{exch2\_tbasey}{exch2_tbasey}, but locate the tiles within the  \varlink{exch2\_tbasey}{exch2_tbasey}, but locate the tile edges within the
326  global address space, similar to that used by global output and input  global address space, similar to that used by global output and input
327  files. \\  files. \\
328    
# Line 328  the subdomain of each tile, in a range \ Line 331  the subdomain of each tile, in a range \
331  standard cube topology and indicated by \textbf{\textsf{f}}$n$ in  standard cube topology and indicated by \textbf{\textsf{f}}$n$ in
332  figures \ref{fig:12tile} and  figures \ref{fig:12tile} and
333  \ref{fig:24tile}. \varlink{exch2\_nNeighbours}{exch2_nNeighbours}  \ref{fig:24tile}. \varlink{exch2\_nNeighbours}{exch2_nNeighbours}
334  contains a count of the neighboring tiles each tile has, and is used  contains a count of the neighboring tiles each tile has, and sets
335  for setting bounds for looping over neighboring tiles.  the bounds for looping over neighboring tiles.
336  \varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each  \varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each
337  tile, and is used in interprocess communication.  \\  tile, and is used in interprocess communication.  \\
338    
# Line 338  The arrays \varlink{exch2\_isWedge}{exch Line 341  The arrays \varlink{exch2\_isWedge}{exch
341  \varlink{exch2\_isEedge}{exch2_isEedge},  \varlink{exch2\_isEedge}{exch2_isEedge},
342  \varlink{exch2\_isSedge}{exch2_isSedge}, and  \varlink{exch2\_isSedge}{exch2_isSedge}, and
343  \varlink{exch2\_isNedge}{exch2_isNedge} are set to \code{1} if the  \varlink{exch2\_isNedge}{exch2_isNedge} are set to \code{1} if the
344  indexed tile lies on the respective edge of a subdomain, \code{0} if  indexed tile lies on the edge of its subdomain, \code{0} if
345  not.  The values are used within the topology generator to determine  not.  The values are used within the topology generator to determine
346  the orientation of neighboring tiles, and to indicate whether a tile  the orientation of neighboring tiles, and to indicate whether a tile
347  lies on the corner of a subdomain.  The latter case requires special  lies on the corner of a subdomain.  The latter case requires special
# Line 371  This provides a back-reference from the Line 374  This provides a back-reference from the
374  The arrays \varlink{exch2\_pi}{exch2_pi} and  The arrays \varlink{exch2\_pi}{exch2_pi} and
375  \varlink{exch2\_pj}{exch2_pj} specify the transformations of indices  \varlink{exch2\_pj}{exch2_pj} specify the transformations of indices
376  in exchanges between the neighboring tiles.  These transformations are  in exchanges between the neighboring tiles.  These transformations are
377  necessary in exchanges between subdomains because the array index in  necessary in exchanges between subdomains because a horizontal dimension
378  one dimension may map to the other index in an adjacent subdomain, and  in one subdomain
379  may be have its indexing reversed. This swapping arises from the  may map to other horizonal dimension in an adjacent subdomain, and
380    may also have its indexing reversed. This swapping arises from the
381  ``folding'' of two-dimensional arrays into a three-dimensional  ``folding'' of two-dimensional arrays into a three-dimensional
382  cube. \\  cube. \\
383    
# Line 381  The dimensions of \code{exch2\_pi(t,N,T) Line 385  The dimensions of \code{exch2\_pi(t,N,T)
385  are the neighbor ID \code{N} and the tile number \code{T} as explained  are the neighbor ID \code{N} and the tile number \code{T} as explained
386  above, plus a vector of length \code{2} containing transformation  above, plus a vector of length \code{2} containing transformation
387  factors \code{t}.  The first element of the transformation vector  factors \code{t}.  The first element of the transformation vector
388  holds the factor to multiply the index in the same axis, and the  holds the factor to multiply the index in the same dimension, and the
389  second element holds the the same for the orthogonal index.  To  second element holds the the same for the orthogonal dimension.  To
390  clarify, \code{exch2\_pi(1,N,T)} holds the mapping of the $x$ axis  clarify, \code{exch2\_pi(1,N,T)} holds the mapping of the $x$ axis
391  index of tile \code{T} to the $x$ axis of tile \code{T}'s neighbor  index of tile \code{T} to the $x$ axis of tile \code{T}'s neighbor
392  \code{N}, and \code{exch2\_pi(2,N,T)} holds the mapping of \code{T}'s  \code{N}, and \code{exch2\_pi(2,N,T)} holds the mapping of \code{T}'s
# Line 397  the arrays for all tile neighbors on the Line 401  the arrays for all tile neighbors on the
401  \code{(1,0)}, since all tiles on the same subdomain are oriented  \code{(1,0)}, since all tiles on the same subdomain are oriented
402  identically.  An axis that corresponds to the orthogonal dimension  identically.  An axis that corresponds to the orthogonal dimension
403  with the same index direction in a particular tile-neighbor  with the same index direction in a particular tile-neighbor
404  orientation will have \code{(0,1)}.  Those in the opposite index  orientation will have \code{(0,1)}.  Those with the opposite index
405  direction will have \code{(0,-1)} in order to reverse the ordering. \\  direction will have \code{(0,-1)} in order to reverse the ordering. \\
406    
407  The arrays \varlink{exch2\_oi}{exch2_oi},  The arrays \varlink{exch2\_oi}{exch2_oi},
# Line 483  the neighbor tile is \code{Tn=5}: Line 487  the neighbor tile is \code{Tn=5}:
487  \code{Tn}'s $y$ axis corresponds to \code{T}'s $x$ axis, \code{T}'s  \code{Tn}'s $y$ axis corresponds to \code{T}'s $x$ axis, \code{T}'s
488  northern edge exchanges with \code{Tn}'s western edge.  The western  northern edge exchanges with \code{Tn}'s western edge.  The western
489  edge of the tiles corresponds to the lower bound of the $x$ axis, so  edge of the tiles corresponds to the lower bound of the $x$ axis, so
490  \code{exch2\_itlo\_c} \code{exch2\_ithi\_c} are \code{0}. The range of  \code{exch2\_itlo\_c} and \code{exch2\_ithi\_c} are \code{0}, in the
491    western halo region of \code{Tn}. The range of
492  \code{exch2\_jtlo\_c} and \code{exch2\_jthi\_c} correspond to the  \code{exch2\_jtlo\_c} and \code{exch2\_jthi\_c} correspond to the
493  width of \code{T}'s northern edge, plus the halo. \\  width of \code{T}'s northern edge, expanded by one into the halo. \\
494    
495    
496  \subsection{Key Routines}  \subsection{Key Routines}
# Line 494  Most of the subroutines particular to ex Line 499  Most of the subroutines particular to ex
499  themselves and are of the same format as those described in  themselves and are of the same format as those described in
500  \ref{sect:cube_sphere_communication} \sectiontitle{Cube sphere  \ref{sect:cube_sphere_communication} \sectiontitle{Cube sphere
501  communication}.  Like the original routines, they are written as  communication}.  Like the original routines, they are written as
502  templates which the local Makefile converts from RX into RL and RS  templates which the local Makefile converts from \code{RX} into
503  forms. \\  \code{RL} and \code{RS} forms. \\
504    
505  The interfaces with the core model subroutines are  The interfaces with the core model subroutines are
506  \code{EXCH\_UV\_XY\_RX}, \code{EXCH\_UV\_XYZ\_RX} and  \code{EXCH\_UV\_XY\_RX}, \code{EXCH\_UV\_XYZ\_RX} and
# Line 510  for scalars and \code{EXCH2\_RX2\_CUBE} Line 515  for scalars and \code{EXCH2\_RX2\_CUBE}
515  the singularities at the cube corners. \\  the singularities at the cube corners. \\
516    
517  The separate scalar and vector forms of \code{EXCH2\_RX1\_CUBE} and  The separate scalar and vector forms of \code{EXCH2\_RX1\_CUBE} and
518  \code{EXCH2\_RX2\_CUBE} reflect that the vector-handling subrouine  \code{EXCH2\_RX2\_CUBE} reflect that the vector-handling subroutine
519  needs to pass both the $u$ and $v$ components of the phsical vectors.  needs to pass both the $u$ and $v$ components of the physical vectors.
520  This arises from the topological folding discussed above, where the  This swapping arises from the topological folding discussed above, where the
521  $x$ and $y$ axes get swapped in some cases.  This swapping is not an  $x$ and $y$ axes get swapped in some cases, and is not an
522  issue with the scalar version. These subroutines call  issue with the scalar case. These subroutines call
523  \code{EXCH2\_SEND\_RX1} and \code{EXCH2\_SEND\_RX2}, which do most of  \code{EXCH2\_SEND\_RX1} and \code{EXCH2\_SEND\_RX2}, which do most of
524  the work using the variables discussed above. \\  the work using the variables discussed above. \\
525    
Legend:
Removed from v.1.18  
changed lines
  Added in v.1.19
  ViewVC Help
Powered by ViewVC 1.1.22