--- manual/s_phys_pkgs/text/exch2.tex 2004/10/12 18:16:03 1.22 +++ manual/s_phys_pkgs/text/exch2.tex 2005/06/10 19:34:09 1.23 @@ -1,4 +1,4 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/exch2.tex,v 1.22 2004/10/12 18:16:03 edhill Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/exch2.tex,v 1.23 2005/06/10 19:34:09 afe Exp $ % $Name: $ %% * Introduction @@ -12,10 +12,6 @@ \section{exch2: Extended Cubed Sphere \mbox{Topology}} \label{sec:exch2} -\label{sec:pkg:exch2} -\begin{rawhtml} - -\end{rawhtml} \subsection{Introduction} @@ -48,54 +44,43 @@ \subsection{Invoking exch2} To use exch2 with the cubed sphere, the following conditions must be -met: +met: \\ -\begin{itemize} -\item The exch2 package is included when \file{genmake2} is run. The - easiest way to do this is to add the line \code{exch2} to the - \file{profile.conf} file -- see Section \ref{sect:buildingCode} - \sectiontitle{Building the code} for general details. - -\item An example of \file{W2\_EXCH2\_TOPOLOGY.h} and +$\bullet$ The exch2 package is included when \file{genmake2} is run. + The easiest way to do this is to add the line \code{exch2} to the + \file{profile.conf} file -- see Section + \ref{sect:buildingCode} \sectiontitle{Building the code} for general + details. \\ + +$\bullet$ An example of \file{W2\_EXCH2\_TOPOLOGY.h} and \file{w2\_e2setup.F} must reside in a directory containing files - symbolically linked by the \file{genmake2} script. The safest place - to put these is the directory indicated in the \code{-mods=DIR} - command line modifier (typically \file{../code}), or the build - directory. The default versions of these files reside in - \file{pkg/exch2} and are linked automatically if no other versions - exist elsewhere in the build path, but they should be left untouched - to avoid breaking configurations other than the one you intend to - modify. - -\item Files containing grid parameters, named \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 -- please contact - \begin{rawhtml} - - \end{rawhtml} -\begin{verbatim} -MITgcm-support@mitgcm.org -\end{verbatim} - \begin{rawhtml} \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 + symbolically linked by the \file{genmake2} script. The safest place to + put these is the directory indicated in the \code{-mods=DIR} command + line modifier (typically \file{../code}), or the build directory. + The default versions of these files reside in \file{pkg/exch2} and + are linked automatically if no other versions exist elsewhere in the + build path, but they should be left untouched to avoid breaking + configurations other than the one you intend to modify.\\ + +$\bullet$ Files containing grid parameters, named + \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 + -- 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 + 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 decomposition issues particular to exch2 are addressed in Section \ref{sec:topogen} \sectiontitle{Generating Topology Files for exch2} - and \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and - Multiprocessing}; a more general background on the subject - relevant to MITgcm is presented in Section - \ref{sect:specifying_a_decomposition} \sectiontitle{Specifying a - decomposition}. -\end{itemize} - - + and \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and Multiprocessing}; a more + general background on the subject relevant to MITgcm is presented in + Section \ref{sect:specifying_a_decomposition} + \sectiontitle{Specifying a decomposition}.\\ At the time of this writing the following examples use exch2 and may be used for guidance: @@ -230,12 +215,20 @@ The number of tiles MITgcm allocates and how they are distributed between processors depends on \varlink{nPx}{nPx} and \varlink{nSx}{nSx}. \varlink{nSx}{nSx} is the number of tiles per -processor and \varlink{nPx}{nPx} is the number of processors. The total -number of tiles in the topology minus those listed in -\file{blanklist.txt} must equal \code{nSx*nPx}. Note that in order to +processor and \varlink{nPx}{nPx} is the number of processors. The +total number of tiles in the topology minus those listed in +\file{blanklist.txt} must equal \code{nSx*nPx}. Note that in order to obtain maximum usage from a given number of processors in some cases, -this restriction might entail sharing a processor with a tile that would -otherwise be excluded. \\ +this restriction might entail sharing a processor with a tile that +would otherwise be excluded because it is topographically outside of +the domain and therefore in \file{blanklist.txt}. For example, +suppose you have five processors and a domain decomposition of +thirty-six tiles that allows you to exclude seven tiles. To evenly +distribute the remaining twenty-nine tiles among five processors, you +would have to run one ``dummy'' tile to make an even six tiles per +processor. Such dummy tiles are \emph{not} listed in +\file{blanklist.txt}.\\ + The following is an example of \file{SIZE.h} for the twelve-tile configuration illustrated in figure \ref{fig:12tile} running on @@ -315,7 +308,7 @@ The following arrays are of length \code{NTILES} and are indexed to the tile number, which is indicated in the diagrams with the notation -\code{tn}. The indices are omitted in the descriptions. \\ +\textsf{t}$n$. The indices are omitted in the descriptions. \\ The arrays \varlink{exch2\_tnx}{exch2_tnx} and \varlink{exch2\_tny}{exch2_tny} express the $x$ and $y$ dimensions of @@ -343,11 +336,11 @@ 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{fn}} in -figures \ref{fig:12tile} and \ref{fig:24tile}. The -\varlink{exch2\_nNeighbours}{exch2_nNeighbours} variable contains a -count of the neighboring tiles each tile has, and sets the bounds for -looping over neighboring tiles. And +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 the neighboring tiles each tile has, and sets +the bounds for looping over neighboring tiles. \varlink{exch2\_tProc}{exch2_tProc} holds the process rank of each tile, and is used in interprocess communication. \\