31 |
\filelink{pkg/exch2/W2\_EXCH2\_TOPOLOGY.h}{pkg-exch2-W2_EXCH2_TOPOLOGY.h} |
\filelink{pkg/exch2/W2\_EXCH2\_TOPOLOGY.h}{pkg-exch2-W2_EXCH2_TOPOLOGY.h} |
32 |
and assigned in |
and assigned in |
33 |
\filelink{pkg/exch2/w2\_e2setup.F}{pkg-exch2-w2_e2setup.F}. The |
\filelink{pkg/exch2/w2\_e2setup.F}{pkg-exch2-w2_e2setup.F}. The |
34 |
validity of the cube topology depends on the \texttt{SIZE.h} file as |
validity of the cube topology depends on the \file{SIZE.h} file as |
35 |
detailed below. Both files are generated by Matlab scripts in |
detailed below. Both files are generated by Matlab scripts in |
36 |
\texttt{utils/exch2/matlab-topology-generator}; see Section |
\file{utils/exch2/matlab-topology-generator}; see Section |
37 |
\ref{sec:topogen} for details on creating alternate topologies. The |
\ref{sec:topogen} \sectiontitle{Generating Topology Files for exch2} |
38 |
default files provided in the release configure a cubed sphere |
for details on creating alternate topologies. The default files |
39 |
topology of six tiles, one per subdomain, each with 32$\times$32 grid |
provided in the release configure a cubed sphere topology of six |
40 |
points, all running on a single processor. Pregenerated examples of |
tiles, one per subdomain, each with 32$\times$32 grid points, all |
41 |
these files with alternate topologies are provided under |
running on a single processor. Pregenerated examples of these files |
42 |
\texttt{utils/exch2/code-mods} along with the appropriate |
with alternate topologies are provided under |
43 |
\texttt{SIZE.h} file for single-processor execution. |
\file{utils/exch2/code-mods} along with the appropriate \file{SIZE.h} |
44 |
|
file for single-processor execution. |
45 |
|
|
46 |
\subsection{Invoking exch2} |
\subsection{Invoking exch2} |
47 |
|
|
48 |
To use exch2 with the cubed sphere, the following conditions must be |
To use exch2 with the cubed sphere, the following conditions must be |
49 |
met: \\ |
met: \\ |
50 |
|
|
51 |
$\bullet$ The exch2 package is included when \texttt{genmake2} is run. The |
$\bullet$ The exch2 package is included when \file{genmake2} is run. |
52 |
easiest way to do this is to add the line \texttt{exch2} to the |
The easiest way to do this is to add the line \code{exch2} to the |
53 |
\texttt{profile.conf} file -- see Section \ref{sect:buildingCode} |
\file{profile.conf} file -- see Section |
54 |
for general details. \\ |
\ref{sect:buildingCode}\sectiontitle{Building the code} for general |
55 |
|
details. \\ |
56 |
$\bullet$ An example of \texttt{W2\_EXCH2\_TOPOLOGY.h} and |
|
57 |
\texttt{w2\_e2setup.F} must reside in a directory containing code |
$\bullet$ An example of \file{W2\_EXCH2\_TOPOLOGY.h} and |
58 |
linked when \texttt{genmake2} runs. The safest place to put these |
\file{w2\_e2setup.F} must reside in a directory containing code |
59 |
is the directory indicated in the \texttt{-mods=DIR} command line |
linked when \file{genmake2} runs. The safest place to put these |
60 |
modifier (typically \texttt{../code}), or the build directory. The |
is the directory indicated in the \code{-mods=DIR} command line |
61 |
default versions of these files reside in \texttt{pkg/exch2} and are |
modifier (typically \file{../code}), or the build directory. The |
62 |
|
default versions of these files reside in \file{pkg/exch2} and are |
63 |
linked automatically if no other versions exist elsewhere in the |
linked automatically if no other versions exist elsewhere in the |
64 |
link path, but they should be left untouched to avoid breaking |
link path, but they should be left untouched to avoid breaking |
65 |
configurations other than the one you intend to modify.\\ |
configurations other than the one you intend to modify.\\ |
66 |
|
|
67 |
$\bullet$ Files containing grid parameters, named |
$\bullet$ Files containing grid parameters, named |
68 |
\texttt{tile}???\texttt{.mitgrid} where ??? is \texttt{001} through |
\file{tile???.mitgrid} where \file{???} is \file{001} through |
69 |
\texttt{006} (one per subdomain), must be in the working directory |
\file{006} (one per subdomain), must be in the working directory |
70 |
when the MITgcm executable is run. These files are provided in the |
when the MITgcm executable is run. These files are provided in the |
71 |
example experiments for cubed sphere configurations with |
example experiments for cubed sphere configurations with |
72 |
32$\times$32 cube sides and are non-trivial to generate -- please |
32$\times$32 cube sides and are non-trivial to generate -- please |
73 |
contact MITgcm support if you want to generate files for other |
contact MITgcm support if you want to generate files for other |
74 |
configurations. \\ |
configurations. \\ |
75 |
|
|
76 |
$\bullet$ As always when compiling MITgcm, the file \texttt{SIZE.h} |
$\bullet$ As always when compiling MITgcm, the file \file{SIZE.h} |
77 |
must be placed where \texttt{genmake2} will find it. In particular |
must be placed where \file{genmake2} will find it. In particular |
78 |
for the exch2, the domain decompositin specified in \texttt{SIZE.h} |
for the exch2, the domain decomposition specified in \file{SIZE.h} |
79 |
must correspond with the particular configuration's topology |
must correspond with the particular configuration's topology |
80 |
specified in \texttt{W2\_EXCH2\_TOPOLOGY.h} and |
specified in \file{W2\_EXCH2\_TOPOLOGY.h} and |
81 |
\texttt{w2\_e2setup.F}. Domain decomposition issues particular to |
\file{w2\_e2setup.F}. Domain decomposition issues particular to |
82 |
exch2 are addressed in Section \ref{sec:topogen}: ``Generating |
exch2 are addressed in Section \ref{sec:topogen} \sectiontitle{Generating |
83 |
Topology Files for exch2''; a more general background on the subject |
Topology Files for exch2}; a more general background on the subject |
84 |
relvant to MITgcm is presented in Section |
relvant to MITgcm is presented in Section |
85 |
\ref{sect:specifying_a_decomposition}: ``Specifying a |
\ref{sect:specifying_a_decomposition}\sectiontitle{Specifying a |
86 |
decomposition''.\\ |
decomposition}.\\ |
87 |
|
|
88 |
As of the time of writing the following examples use exch2 and may be |
As of the time of writing the following examples use exch2 and may be |
89 |
used for guidance: |
used for guidance: |
103 |
\label{sec:topogen} |
\label{sec:topogen} |
104 |
|
|
105 |
Alternate cubed sphere topologies may be created using the Matlab |
Alternate cubed sphere topologies may be created using the Matlab |
106 |
scripts in \texttt{utils/exch2/matlab-topology-generator}. Running the |
scripts in \file{utils/exch2/matlab-topology-generator}. Running the |
107 |
m-file \texttt{driver} from the Matlab prompt (without passing any |
m-file \file{driver.m} from the Matlab prompt (there are no parameters |
108 |
function parameters) generates exch2 topology files |
to pass) generates exch2 topology files \file{W2\_EXCH2\_TOPOLOGY.h} |
109 |
\texttt{W2\_EXCH2\_TOPOLOGY.h} and \texttt{w2\_e2setup.F} in the |
and \file{w2\_e2setup.F} in the working directory and displays a |
110 |
working directory and displays via Matlab a figure of the topology. |
figure of the topology via Matlab. The other m-files in the directory |
111 |
The other m-files in the directory are subroutines of \texttt{driver} |
are subroutines of \file{driver.m} and should not be run except for |
112 |
and should not be run except for development purposes. \\ |
development purposes. \\ |
113 |
|
|
114 |
The parameters that determine the dimensions and topology of the |
The parameters that determine the dimensions and topology of the |
115 |
generated configuration are nr, nb, ng, tnx and tny, and all are |
generated configuration are \code{nr}, \code{nb}, \code{ng}, |
116 |
assigned early in the script. |
\code{tnx} and \code{tny}, and all are assigned early in the script. |
117 |
|
|
118 |
The first three determine the size of the subdomains (cube faces) and |
The first three determine the size of the subdomains (cube faces) and |
119 |
hence the size of the overall domain. Each one determines the number |
hence the size of the overall domain. Each one determines the number |
124 |
resolutions around the axes to allow (for example) greater resolution |
resolutions around the axes to allow (for example) greater resolution |
125 |
around the equator.\\ |
around the equator.\\ |
126 |
|
|
127 |
The parameters tnx and tny determine the dimensions of the tiles into |
The parameters \code{tnx} and \code{tny} determine the dimensions of |
128 |
which the subdomains are decomposed, and must evenly divide the |
the tiles into which the subdomains are decomposed, and must evenly |
129 |
integer assigned to nr, nb and ng. The result is a rectangular tiling |
divide the integer assigned to \code{nr}, \code{nb} and \code{ng}. |
130 |
of the subdomain. Figure \ref{fig:24tile} shows one possible topology |
The result is a rectangular tiling of the subdomain. Figure |
131 |
for a twenty-four tile cube, and figure \ref{fig:12tile} shows one for |
\ref{fig:24tile} shows one possible topology for a twenty-four tile |
132 |
twelve tiles. \\ |
cube, and figure \ref{fig:12tile} shows one for twelve tiles. \\ |
133 |
|
|
134 |
\begin{figure} |
\begin{figure} |
135 |
\begin{center} |
\begin{center} |
138 |
} |
} |
139 |
\end{center} |
\end{center} |
140 |
\caption{Plot of cubed sphere topology with a 32$\times$32 grid and |
\caption{Plot of cubed sphere topology with a 32$\times$32 grid and |
141 |
twenty-four tiles (tnx=16, tny=16) |
twenty-four tiles (\code{tnx=16, tny=16}) |
142 |
} \label{fig:24tile} |
} \label{fig:24tile} |
143 |
\end{figure} |
\end{figure} |
144 |
|
|
149 |
} |
} |
150 |
\end{center} |
\end{center} |
151 |
\caption{Plot of cubed sphere topology with a 32$\times$32 grid and |
\caption{Plot of cubed sphere topology with a 32$\times$32 grid and |
152 |
twelve tiles (tnx=16, tny=32) |
twelve tiles (\code{tnx=16, tny=32}) |
153 |
} \label{fig:12tile} |
} \label{fig:12tile} |
154 |
\end{figure} |
\end{figure} |
155 |
|
|
156 |
Tiles can be selected from the topology to be omitted from being |
Tiles can be selected from the topology to be omitted from being |
157 |
allocated memory and processors. This kind of tuning is useful in |
allocated memory and processors. This kind otuning is useful in |
158 |
ocean modeling for omitting tiles that fall entirely on land. The |
ocean modeling for omitting tiles that fall entirely on land. The |
159 |
tiles omitted are specified in the file \texttt{blanklist.txt} by |
tiles omitted are specified in the file \file{blanklist.txt} by |
160 |
their tile number in the topology, separated by a newline. \\ |
their tile number in the topology, separated by a newline. \\ |
161 |
|
|
162 |
|
|