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

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

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

-revision 1.19 by afe,
Mon May 10 21:39:11 2004 UTC
+revision 1.26 by molod,
Wed Jun 28 15:35:07 2006 UTC
 Line 10
  %%    o automatically inserted at \section{Reference}
- \section{exch2: Extended Cubed Sphere \mbox{Topology}}
+ \subsection{exch2: Extended Cubed Sphere \mbox{Topology}}
  \label{sec:exch2}
- \subsection{Introduction}
+ \subsubsection{Introduction}
  The \texttt{exch2} package extends the original cubed sphere topology
  configuration to allow more flexible domain decomposition and
 Line 23 
 into any number of tiles that divide eve
  dimensions of the subdomain.  Furthermore, the tiles can run on
  separate processors individually or in groups, which provides for
  manual compile-time load balancing across a relatively arbitrary
- number of processors. \\
+ number of processors.
  The exchange parameters are declared in
  \filelink{pkg/exch2/W2\_EXCH2\_TOPOLOGY.h}{pkg-exch2-W2_EXCH2_TOPOLOGY.h}
 Line 41 
 of these files with alternate topologies
  \file{utils/exch2/code-mods} along with the appropriate \file{SIZE.h}
  file for single-processor execution.
- \subsection{Invoking exch2}
+ \subsubsection{Invoking exch2}
  To use exch2 with the cubed sphere, the following conditions must be
- met: \\
+ met:
- $\bullet$ The exch2 package is included when \file{genmake2} is run.
+ \begin{itemize}
-   The easiest way to do this is to add the line \code{exch2} to the
+ \item The exch2 package is included when \file{genmake2} is run.  The
-   \file{profile.conf} file -- see Section
+   easiest way to do this is to add the line \code{exch2} to the
-   \ref{sect:buildingCode} \sectiontitle{Building the code} for general
+   \file{packages.conf} file -- see Section \ref{sect:buildingCode}
-   details. \\
+   \sectiontitle{Building the code} for general
+   details.
- $\bullet$ An example of \file{W2\_EXCH2\_TOPOLOGY.h} and
+ \item 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
+   symbolically linked by the \file{genmake2} script.  The safest place
-   put these is the directory indicated in the \code{-mods=DIR} command
+   to put these is the directory indicated in the \code{-mods=DIR}
-   line modifier (typically \file{../code}), or the build directory.
+   command line modifier (typically \file{../code}), or the build
-   The default versions of these files reside in \file{pkg/exch2} and
+   directory.  The default versions of these files reside in
-   are linked automatically if no other versions exist elsewhere in the
+   \file{pkg/exch2} and are linked automatically if no other versions
-   build path, but they should be left untouched to avoid breaking
+   exist elsewhere in the build path, but they should be left untouched
-   configurations other than the one you intend to modify.\\
+   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),
+ \item Files containing grid parameters, named \file{tile00$n$.mitgrid}
-   must be in the working directory when the MITgcm executable is run.
+   where $n$=\code{(1:6)} (one per subdomain), must be in the working
-   These files are provided in the example experiments for cubed sphere
+   directory when the MITgcm executable is run.  These files are
-   configurations with 32$\times$32 cube sides
+   provided in the example experiments for cubed sphere configurations
-   -- please contact MITgcm support if you want to generate
+   with 32$\times$32 cube sides -- please contact MITgcm support if you
-   files for other configurations. \\
+   want to generate files for other configurations.
- $\bullet$ As always when compiling MITgcm, the file \file{SIZE.h} must
+ \item As always when compiling MITgcm, the file \file{SIZE.h} must be
-   be placed where \file{genmake2} will find it.  In particular for
+   placed where \file{genmake2} will find it.  In particular for exch2,
-   exch2, the domain decomposition specified in \file{SIZE.h} must
+   the domain decomposition specified in \file{SIZE.h} must correspond
-   correspond with the particular configuration's topology specified in
+   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
+   and \ref{sec:exch2mpi} \sectiontitle{exch2, SIZE.h, and
-   general background on the subject relevant to MITgcm is presented in
+     Multiprocessing}; a more general background on the subject
-   Section \ref{sect:specifying_a_decomposition}
+   relevant to MITgcm is presented in Section
-   \sectiontitle{Specifying a decomposition}.\\
+   \ref{sect:specifying_a_decomposition}
+   \sectiontitle{Specifying a decomposition}.
+ \end{itemize}
  At the time of this writing the following examples use exch2 and may
  be used for guidance:
-Line 96 
 verification/hs94.cs-32x32x5
+Line 99 
 verification/hs94.cs-32x32x5
- \subsection{Generating Topology Files for exch2}
+ \subsubsection{Generating Topology Files for exch2}
  \label{sec:topogen}
  Alternate cubed sphere topologies may be created using the Matlab
-Line 182 
 by their tile number in the topology, se
+Line 185 
 by their tile number in the topology, se
- \subsection{exch2, SIZE.h, and Multiprocessing}
+ \subsubsection{exch2, SIZE.h, and Multiprocessing}
  \label{sec:exch2mpi}
  Once the topology configuration files are created, the Fortran
  \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
+   a decomposition} provides a general description of domain
  decomposition within MITgcm and its relation to \file{SIZE.h}. The
- current section specifies constraints that the exch2 package
+ current section specifies constraints that the exch2 package imposes
- imposes and describes how to enable parallel execution with
+ and describes how to enable parallel execution with MPI.
- MPI. \\
  As in the general case, the parameters \varlink{sNx}{sNx} and
  \varlink{sNy}{sNy} define the size of the individual tiles, and so
  must be assigned the same respective values as \code{tnx} and
- \code{tny} in \file{driver.m}.\\
+ \code{tny} in \file{driver.m}.
  The halo width parameters \varlink{OLx}{OLx} and \varlink{OLy}{OLy}
  have no special bearing on exch2 and may be assigned as in the general
  case. The same holds for \varlink{Nr}{Nr}, the number of vertical
- levels in the model.\\
+ levels in the model.
  The parameters \varlink{nSx}{nSx}, \varlink{nSy}{nSy},
  \varlink{nPx}{nPx}, and \varlink{nPy}{nPy} relate to the number of
-Line 210 
 tiles and how they are distributed on pr
+Line 212 
 tiles and how they are distributed on pr
  the tiles are stored in the $x$ dimension, and so
  \code{\varlink{nSy}{nSy}=1} in all cases.  Since the tiles as
  configured by exch2 cannot be split up accross processors without
- regenerating the topology, \code{\varlink{nPy}{nPy}=1} as well. \\
+ regenerating the topology, \code{\varlink{nPy}{nPy}=1} as well.
  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
+ processor and \varlink{nPx}{nPx} is the number of processors.  The
- number of tiles in the topology minus those listed in
+ 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
+ this restriction might entail sharing a processor with a tile that
- otherwise be excluded. \\
+ 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
+ configuration illustrated in figure \ref{fig:12tile} running on one
- one processor: \\
+ processor:
  \begin{verbatim}
        PARAMETER (
-Line 260 
 figure \ref{fig:24tile} running on six p
+Line 269 
 figure \ref{fig:24tile} running on six p
  \end{verbatim}
+ \subsubsection{Key Variables}
- \subsection{Key Variables}
  The descriptions of the variables are divided up into scalars,
  one-dimensional arrays indexed to the tile number, and two and
-Line 273 
 scalars are common to every part of the
+Line 279 
 scalars are common to every part of the
  arrays to individual tiles, and the arrays indexed by tile and
  neighbor to relationships between tiles and their neighbors. \\
- \subsubsection{Scalars}
+ Scalars:
  The number of tiles in a particular topology is set with the parameter
  \code{NTILES}, and the maximum number of neighbors of any tiles by
-Line 296 
 are stored internally in a range from \c
+Line 302 
 are stored internally in a range from \c
  $x$ axis, and the $y$ axis variable \varlink{bj}{bj} is assumed to
  equal \code{1} throughout the package. \\
- \subsubsection{Arrays indexed to tile number}
+ Arrays indexed to tile number:
  The following arrays are of length \code{NTILES} and are indexed to
  the tile number, which is indicated in the diagrams with the notation
-Line 349 
 exchange and numerical handling for the
+Line 355 
 exchange and numerical handling for the
  corners of the cube. \\
- \subsubsection{Arrays Indexed to Tile Number and Neighbor}
+ Arrays Indexed to Tile Number and Neighbor:
  The following arrays have vectors of length \code{MAX\_NEIGHBOURS} and
  \code{NTILES} and describe the orientations between the the tiles. \\
-Line 493 
 western halo region of \code{Tn}. The ra
+Line 499 
 western halo region of \code{Tn}. The ra
  width of \code{T}'s northern edge, expanded by one into the halo. \\
- \subsection{Key Routines}
+ \subsubsection{Key Routines}
  Most of the subroutines particular to exch2 handle the exchanges
  themselves and are of the same format as those described in
-Line 523 
 issue with the scalar case. These subrou
+Line 529 
 issue with the scalar case. These subrou
  \code{EXCH2\_SEND\_RX1} and \code{EXCH2\_SEND\_RX2}, which do most of
  the work using the variables discussed above. \\
+ \subsubsection{Experiments and tutorials that use exch2}
+ \label{sec:pkg:exch2:experiments}
+ \begin{itemize}
+ \item{Held Suarez tutorial, in tutorial\_held\_suarez\_cs verification directory,
+ described in section \ref{sect:eg-hs} }
+ \end{itemize}

 Legend:



Removed from v.1.19
 


changed lines


 
Added in v.1.26
 Legend:



Removed from v.1.19
 


changed lines


 
Added in v.1.26
-Removed from v.1.19
+Added in v.1.26

	ViewVC Help
Powered by ViewVC 1.1.22