/[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.20 by edhill, Tue Oct 12 15:47:40 2004 UTC revision 1.24 by molod, Mon Jul 18 20:45:27 2005 UTC
# Line 10  Line 10 
10  %%    o automatically inserted at \section{Reference}  %%    o automatically inserted at \section{Reference}
11    
12    
13  \section{exch2: Extended Cubed Sphere \mbox{Topology}}  \subsection{exch2: Extended Cubed Sphere \mbox{Topology}}
14  \label{sec:exch2}  \label{sec:exch2}
15    
16    
17  \subsection{Introduction}  \subsubsection{Introduction}
18    
19  The \texttt{exch2} package extends the original cubed sphere topology  The \texttt{exch2} package extends the original cubed sphere topology
20  configuration to allow more flexible domain decomposition and  configuration to allow more flexible domain decomposition and
# Line 41  of these files with alternate topologies Line 41  of these files with alternate topologies
41  \file{utils/exch2/code-mods} along with the appropriate \file{SIZE.h}  \file{utils/exch2/code-mods} along with the appropriate \file{SIZE.h}
42  file for single-processor execution.  file for single-processor execution.
43    
44  \subsection{Invoking exch2}  \subsubsection{Invoking exch2}
45    
46  To use exch2 with the cubed sphere, the following conditions must be  To use exch2 with the cubed sphere, the following conditions must be
47  met:  met: \\
48    
49  \begin{itemize}  $\bullet$ The exch2 package is included when \file{genmake2} is run.
50  \item The exch2 package is included when \file{genmake2} is run.  The    The easiest way to do this is to add the line \code{exch2} to the
51    easiest way to do this is to add the line \code{exch2} to the    \file{profile.conf} file -- see Section
52    \file{profile.conf} file -- see Section \ref{sect:buildingCode}    \ref{sect:buildingCode} \sectiontitle{Building the code} for general
53    \sectiontitle{Building the code} for general details.    details. \\
54      
55  \item 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 by the \file{genmake2} script.  The safest place    symbolically linked by the \file{genmake2} script.  The safest place to
58    to put these is the directory indicated in the \code{-mods=DIR}    put these is the directory indicated in the \code{-mods=DIR} command
59    command line modifier (typically \file{../code}), or the build    line modifier (typically \file{../code}), or the build directory.
60    directory.  The default versions of these files reside in    The default versions of these files reside in \file{pkg/exch2} and
61    \file{pkg/exch2} and are linked automatically if no other versions    are linked automatically if no other versions exist elsewhere in the
62    exist elsewhere in the build path, but they should be left untouched    build path, but they should be left untouched to avoid breaking
63    to avoid breaking configurations other than the one you intend to    configurations other than the one you intend to modify.\\
64    modify.  
65      $\bullet$ Files containing grid parameters, named
66  \item Files containing grid parameters, named \file{tile00$n$.mitgrid}    \file{tile00$n$.mitgrid} where $n$=\code{(1:6)} (one per subdomain),
67    where $n$=\code{(1:6)} (one per subdomain), must be in the working    must be in the working directory when the MITgcm executable is run.
68    directory when the MITgcm executable is run.  These files are    These files are provided in the example experiments for cubed sphere
69    provided in the example experiments for cubed sphere configurations    configurations with 32$\times$32 cube sides
70    with 32$\times$32 cube sides -- please contact    -- please contact MITgcm support if you want to generate
71    \begin{rawhtml}    files for other configurations. \\
72      <A href=''mailto:mitgcm-support@dev.mitgcm.org">  
73    \end{rawhtml}  $\bullet$ As always when compiling MITgcm, the file \file{SIZE.h} must
74  \begin{verbatim}    be placed where \file{genmake2} will find it.  In particular for
75  MITgcm-support@mitgcm.org    exch2, the domain decomposition specified in \file{SIZE.h} must
76  \end{verbatim}    correspond with the particular configuration's topology specified in
   \begin{rawhtml} </A> \end{rawhtml}  
   if you want to generate files for other configurations.  
     
 \item As always when compiling MITgcm, the file \file{SIZE.h} must 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  
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    and \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and Multiprocessing}; a more
81      Multiprocessing}; a more general background on the subject    general background on the subject relevant to MITgcm is presented in
82    relevant to MITgcm is presented in Section    Section \ref{sect:specifying_a_decomposition}
83    \ref{sect:specifying_a_decomposition} \sectiontitle{Specifying a    \sectiontitle{Specifying a decomposition}.\\
     decomposition}.  
 \end{itemize}  
   
   
84    
85  At the time of this writing the following examples use exch2 and may  At the time of this writing the following examples use exch2 and may
86  be used for guidance:  be used for guidance:
# Line 107  verification/hs94.cs-32x32x5 Line 96  verification/hs94.cs-32x32x5
96    
97    
98    
99  \subsection{Generating Topology Files for exch2}  \subsubsection{Generating Topology Files for exch2}
100  \label{sec:topogen}  \label{sec:topogen}
101    
102  Alternate cubed sphere topologies may be created using the Matlab  Alternate cubed sphere topologies may be created using the Matlab
# Line 193  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}  \subsubsection{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 226  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} is the number of processors.  The total  processor and \varlink{nPx}{nPx} is the number of processors.  The
219  number of tiles in the topology minus those listed in  total number of tiles in the topology minus those listed in
220  \file{blanklist.txt} must equal \code{nSx*nPx}.  Note that in order to  \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,  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  this restriction might entail sharing a processor with a tile that
223  otherwise be excluded. \\  would otherwise be excluded because it is topographically outside of
224    the domain and therefore in \file{blanklist.txt}.  For example,
225    suppose you have five processors and a domain decomposition of
226    thirty-six tiles that allows you to exclude seven tiles.  To evenly
227    distribute the remaining twenty-nine tiles among five processors, you
228    would have to run one ``dummy'' tile to make an even six tiles per
229    processor.  Such dummy tiles are \emph{not} listed in
230    \file{blanklist.txt}.\\
231    
232    
233  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
234  configuration illustrated in figure \ref{fig:12tile} running on  configuration illustrated in figure \ref{fig:12tile} running on
# Line 274  figure \ref{fig:24tile} running on six p Line 271  figure \ref{fig:24tile} running on six p
271    
272    
273    
274  \subsection{Key Variables}  \subsubsection{Key Variables}
275    
276  The descriptions of the variables are divided up into scalars,  The descriptions of the variables are divided up into scalars,
277  one-dimensional arrays indexed to the tile number, and two and  one-dimensional arrays indexed to the tile number, and two and
# Line 284  scalars are common to every part of the Line 281  scalars are common to every part of the
281  arrays to individual tiles, and the arrays indexed by tile and  arrays to individual tiles, and the arrays indexed by tile and
282  neighbor to relationships between tiles and their neighbors. \\  neighbor to relationships between tiles and their neighbors. \\
283    
284  \subsubsection{Scalars}  Scalars:
285    
286  The number of tiles in a particular topology is set with the parameter  The number of tiles in a particular topology is set with the parameter
287  \code{NTILES}, and the maximum number of neighbors of any tiles by  \code{NTILES}, and the maximum number of neighbors of any tiles by
# Line 307  are stored internally in a range from \c Line 304  are stored internally in a range from \c
304  $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
305  equal \code{1} throughout the package. \\  equal \code{1} throughout the package. \\
306    
307  \subsubsection{Arrays indexed to tile number}  Arrays indexed to tile number:
308    
309  The following arrays are of length \code{NTILES} and are indexed to  The following arrays are of length \code{NTILES} and are indexed to
310  the tile number, which is indicated in the diagrams with the notation  the tile number, which is indicated in the diagrams with the notation
311  \code{tn}.  The indices are omitted in the descriptions. \\  \textsf{t}$n$.  The indices are omitted in the descriptions. \\
312    
313  The arrays \varlink{exch2\_tnx}{exch2_tnx} and  The arrays \varlink{exch2\_tnx}{exch2_tnx} and
314  \varlink{exch2\_tny}{exch2_tny} express the $x$ and $y$ dimensions of  \varlink{exch2\_tny}{exch2_tny} express the $x$ and $y$ dimensions of
# Line 339  files. \\ Line 336  files. \\
336    
337  The array \varlink{exch2\_myFace}{exch2_myFace} contains the number of  The array \varlink{exch2\_myFace}{exch2_myFace} contains the number of
338  the subdomain of each tile, in a range \code{(1:6)} in the case of the  the subdomain of each tile, in a range \code{(1:6)} in the case of the
339  standard cube topology and indicated by \textbf{\textsf{fn}} in  standard cube topology and indicated by \textbf{\textsf{f}}$n$ in
340  figures \ref{fig:12tile} and \ref{fig:24tile}. The  figures \ref{fig:12tile} and
341  \varlink{exch2\_nNeighbours}{exch2_nNeighbours} variable contains a  \ref{fig:24tile}. \varlink{exch2\_nNeighbours}{exch2_nNeighbours}
342  count of the neighboring tiles each tile has, and sets the bounds for  contains a count of the neighboring tiles each tile has, and sets
343  looping over neighboring tiles.  And  the bounds for looping over neighboring tiles.
344  \varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each  \varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each
345  tile, and is used in interprocess communication.  \\  tile, and is used in interprocess communication.  \\
346    
# Line 360  exchange and numerical handling for the Line 357  exchange and numerical handling for the
357  corners of the cube. \\  corners of the cube. \\
358    
359    
360  \subsubsection{Arrays Indexed to Tile Number and Neighbor}  Arrays Indexed to Tile Number and Neighbor:
361    
362  The following arrays have vectors of length \code{MAX\_NEIGHBOURS} and  The following arrays have vectors of length \code{MAX\_NEIGHBOURS} and
363  \code{NTILES} and describe the orientations between the the tiles. \\  \code{NTILES} and describe the orientations between the the tiles. \\
# Line 504  western halo region of \code{Tn}. The ra Line 501  western halo region of \code{Tn}. The ra
501  width of \code{T}'s northern edge, expanded by one into the halo. \\  width of \code{T}'s northern edge, expanded by one into the halo. \\
502    
503    
504  \subsection{Key Routines}  \subsubsection{Key Routines}
505    
506  Most of the subroutines particular to exch2 handle the exchanges  Most of the subroutines particular to exch2 handle the exchanges
507  themselves and are of the same format as those described in  themselves and are of the same format as those described in
Legend:
Removed from v.1.20  
changed lines
  Added in v.1.24
  ViewVC Help
Powered by ViewVC 1.1.22