/[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.24 by molod,
Mon Jul 18 20:45:27 2005 UTC
+revision 1.28 by jmc,
Fri Aug 27 13:15:37 2010 UTC
 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 44 
 file for single-processor execution.
  \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 106 
 m-file
+Line 109 
 m-file
  from the Matlab prompt (there are no parameters to pass) generates
  exch2 topology files \file{W2\_EXCH2\_TOPOLOGY.h} and
  \file{w2\_e2setup.F} in the working directory and displays a figure of
- the topology via Matlab -- figures \ref{fig:6tile}, \ref{fig:12tile},
+ the topology via Matlab -- figures \ref{fig:6tile}, \ref{fig:18tile},
- and \ref{fig:24tile} are examples of the generated diagrams.  The other
+ and \ref{fig:48tile} are examples of the generated diagrams.  The other
  m-files in the directory are
  subroutines called from \file{driver.m} and should not be run ``bare'' except
  for development purposes. \\
-Line 128 
 The parameters \code{tnx} and \code{tny}
+Line 131 
 The parameters \code{tnx} and \code{tny}
  the tiles into which the subdomains are decomposed, and must evenly
  divide the integer assigned to \code{nr}, \code{nb} and \code{ng}.
  The result is a rectangular tiling of the subdomain.  Figure
- \ref{fig:24tile} shows one possible topology for a twenty-four-tile
+ \ref{fig:48tile} shows one possible topology for a twenty-four-tile
- cube, and figure \ref{fig:12tile} shows one for twelve tiles. \\
+ cube, and figure \ref{fig:6tile} shows one for six tiles. \\
  \begin{figure}
  \begin{center}
-  \resizebox{4in}{!}{
+  \resizebox{6in}{!}{
-   \includegraphics{part6/s24t_16x16.ps}
+ % \includegraphics{s_phys_pkgs/figs/s24t_16x16.ps}
+   \includegraphics{s_phys_pkgs/figs/adjust_cs.ps}
   }
  \end{center}
  \caption{Plot of a cubed sphere topology with a 32$\times$192 domain
  divided into six 32$\times$32 subdomains, each of which is divided
- into four tiles of width \code{tnx=16} and height \code{tny=16} for a
+ into eight tiles of width \code{tnx=16} and height \code{tny=8} for a
- total of twenty-four tiles.  The colored borders of the subdomains
+ total of forty-eight tiles. The colored borders of the subdomains
- represent the parameters \code{nr} (red), \code{nb} (blue), and
+ represent the parameters \code{nr} (red), \code{ng} (green), and
- \code{ng} (green).  } \label{fig:24tile}
+ \code{nb} (blue).
+ This tiling is used in the example
+ verification/adjustment.cs-32x32x1/
+ with the option (blanklist.txt) to remove the land-only 4 tiles
+ (11,12,13,14) which are filled in red on the plot.
+ } \label{fig:48tile}
  \end{figure}
  \begin{figure}
  \begin{center}
-  \resizebox{4in}{!}{
+  \resizebox{6in}{!}{
-   \includegraphics{part6/s12t_16x32.ps}
+ % \includegraphics{s_phys_pkgs/figs/s12t_16x32.ps}
+   \includegraphics{s_phys_pkgs/figs/polarcap.ps}
   }
  \end{center}
- \caption{Plot of a cubed sphere topology with a 32$\times$192 domain
+ \caption{Plot of a non-square cubed sphere topology with
- divided into six 32$\times$32 subdomains of two tiles each
+subdomains of different size (nr=90,ng=360,nb=90),
-  (\code{tnx=16, tny=32}).
+ divided into one to four tiles each
- } \label{fig:12tile}
+  (\code{tnx=90, tny=90}), resulting in a total of 18 tiles.
+ } \label{fig:18tile}
  \end{figure}
  \begin{figure}
  \begin{center}
   \resizebox{4in}{!}{
-   \includegraphics{part6/s6t_32x32.ps}
+ % \includegraphics{s_phys_pkgs/figs/s6t_32x32.ps}
+   \includegraphics{s_phys_pkgs/figs/s6t_32x32.ps}
   }
  \end{center}
  \caption{Plot of a cubed sphere topology with a 32$\times$192 domain
-Line 188 
 by their tile number in the topology, se
+Line 200 
 by their tile number in the topology, se
  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 221 
 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
-Line 227 
 thirty-six tiles that allows you to excl
+Line 238 
 thirty-six tiles that allows you to excl
  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}.\\
+ \file{blanklist.txt}.
+ The following is an example of \file{SIZE.h} for the six-tile
- The following is an example of \file{SIZE.h} for the twelve-tile
+ configuration illustrated in figure \ref{fig:6tile}
- configuration illustrated in figure \ref{fig:12tile} running on
+ running on one processor:
- one processor: \\
  \begin{verbatim}
        PARAMETER (
-      &           sNx =  16,
+      &           sNx =  32,
       &           sNy =  32,
       &           OLx =   2,
       &           OLy =   2,
-      &           nSx =  12,
+      &           nSx =   6,
       &           nSy =   1,
       &           nPx =   1,
       &           nPy =   1,
-Line 249 
 one processor: \\
+Line 259 
 one processor: \\
       &           Nr  =   5)
  \end{verbatim}
- The following is an example for the twenty-four-tile topology in
+ The following is an example for the forty-eight-tile topology in
- figure \ref{fig:24tile} running on six processors:
+ figure \ref{fig:48tile} running on six processors:
  \begin{verbatim}
        PARAMETER (
       &           sNx =  16,
-      &           sNy =  16,
+      &           sNy =   8,
       &           OLx =   2,
       &           OLy =   2,
-      &           nSx =   4,
+      &           nSx =   8,
       &           nSy =   1,
       &           nPx =   6,
       &           nPy =   1,
-Line 268 
 figure \ref{fig:24tile} running on six p
+Line 278 
 figure \ref{fig:24tile} running on six p
  \end{verbatim}
  \subsubsection{Key Variables}
  The descriptions of the variables are divided up into scalars,
-Line 295 
 and \varlink{exch2\_domain\_nyt}{exch2_d
+Line 302 
 and \varlink{exch2\_domain\_nyt}{exch2_d
  of tiles in the $x$ and $y$ global indices.  For example, the default
  setup of six tiles (Fig. \ref{fig:6tile}) has
  \code{exch2\_domain\_nxt=6} and \code{exch2\_domain\_nyt=1}.  A
- topology of twenty-four square tiles, four per subdomain (as in figure
+ topology of forty-eight tiles, eight per subdomain (as in figure
- \ref{fig:24tile}), will have \code{exch2\_domain\_nxt=12} and
+ \ref{fig:48tile}), will have \code{exch2\_domain\_nxt=12} and
- \code{exch2\_domain\_nyt=2}.  Note that these parameters express the
+ \code{exch2\_domain\_nyt=4}.  Note that these parameters express the
  tile layout in order to allow global data files that are tile-layout-neutral.
  They have no bearing on the internal storage of the arrays.  The tiles
  are stored internally in a range from \code{\varlink{bi}{bi}=(1:NTILES)} in the
-Line 337 
 files. \\
+Line 344 
 files. \\
  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{f}}$n$ in
- figures \ref{fig:12tile} and
+ figures \ref{fig:6tile} and
- \ref{fig:24tile}. \varlink{exch2\_nNeighbours}{exch2_nNeighbours}
+ \ref{fig:48tile}. \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
-Line 460 
 Finally, \varlink{exch2\_itlo\_c}{exch2_
+Line 467 
 Finally, \varlink{exch2\_itlo\_c}{exch2_
  \varlink{exch2\_jthi\_c}{exch2_jthi_c} hold the location and index
  bounds of the edge segment of the neighbor tile \code{N}'s subdomain
  that gets exchanged with the local tile \code{T}.  To take the example
- of tile \code{T=2} in the twelve-tile topology
+ of tile \code{T=2} in the forty-eight-tile topology
- (Fig. \ref{fig:12tile}): \\
+ (Fig. \ref{fig:48tile}): \\
  \begin{verbatim}
         exch2_itlo_c(4,2)=17
-Line 531 
 issue with the scalar case. These subrou
+Line 538 
 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.24
 


changed lines


 
Added in v.1.28
 Legend:



Removed from v.1.24
 


changed lines


 
Added in v.1.28
-Removed from v.1.24
+Added in v.1.28

	ViewVC Help
Powered by ViewVC 1.1.22