s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/part3/case_studies/barotropic_gyre/baro.tex,v 1.10 2004/01/29 15:11:39 edhill Exp $
% $Name:  $

\bodytext{bgcolor="#FFFFFFFF"}

%\begin{center} 
%{\Large \bf Using MITgcm to Simulate a Rotating Tank in Cylindrical 
%Coordinates}
%
%\vspace*{4mm}
%
%\vspace*{3mm}
%{\large June 2004}
%\end{center}

This is the first in a series of tutorials describing
example MITgcm numerical experiments. The example experiments 
include both straightforward examples of idealized geophysical 
fluid simulations and more involved cases encompassing
large scale modeling and
automatic differentiation. Both hydrostatic and non-hydrostatic 
experiments are presented, as well as experiments employing
Cartesian, spherical-polar and cube-sphere coordinate systems.
These ``case study'' documents include information describing
the experimental configuration and detailed information on how to
configure the MITgcm code and input files for each experiment.

\section{Barotropic Ocean Gyre In Cartesian Coordinates}
\label{sect:eg-baro}
\label{www:tutorials}


\subsection{Equations Solved}
\label{www:tutorials}
The model is configured in hydrostatic form. The implicit free surface form of the


\subsection{Discrete Numerical Configuration}
\label{www:tutorials}

 The domain is discretised with 
a uniform grid spacing in the horizontal set to
 $\Delta x=\Delta y=20$~km, so 
that there are sixty grid cells in the $x$ and $y$ directions. Vertically the 
model is configured with a single layer with depth, $\Delta z$, of $5000$~m. 

\subsubsection{Numerical Stability Criteria}
\label{www:tutorials}


\subsection{Code Configuration}
\label{www:tutorials}
\label{SEC:eg-baro-code_config}

The model configuration for this experiment resides under the 
directory {\it verification/exp0/}.  The experiment files 
\begin{itemize}
\item {\it input/data}
\item {\it input/data.pkg}
\item {\it input/eedata},
\item {\it input/windx.sin\_y},
\item {\it input/topog.box},
\item {\it code/CPP\_EEOPTIONS.h}
\item {\it code/CPP\_OPTIONS.h},
\item {\it code/SIZE.h}. 
\end{itemize}
contain the code customizations and parameter settings for this 
experiments. Below we describe the customizations
to these files associated with this experiment.

\subsubsection{File {\it input/data}}
\label{www:tutorials}

This file, reproduced completely below, specifies the main parameters 
for the experiment. The parameters that are significant for this configuration
are

\begin{itemize}

\item Line 7, \begin{verbatim} viscAh=4.E2, \end{verbatim} this line sets
the Laplacian friction coefficient to $400 m^2s^{-1}$
\item Line 10, \begin{verbatim} beta=1.E-11, \end{verbatim} this line sets
$\beta$ (the gradient of the coriolis parameter, $f$) to $10^{-11} s^{-1}m^{-1}$

\item Lines 15 and 16
\begin{verbatim}
rigidLid=.FALSE.,
implicitFreeSurface=.TRUE.,
\end{verbatim}
these lines suppress the rigid lid formulation of the surface
pressure inverter and activate the implicit free surface form
of the pressure inverter.

\item Line 27,
\begin{verbatim}
startTime=0,
\end{verbatim}
this line indicates that the experiment should start from $t=0$
and implicitly suppresses searching for checkpoint files associated
with restarting an numerical integration from a previously saved state.

\item Line 29,
\begin{verbatim}
endTime=12000,
\end{verbatim}
this line indicates that the experiment should start finish at $t=12000s$.
A restart file will be written at this time that will enable the
simulation to be continued from this point.

\item Line 30,
\begin{verbatim}
deltaTmom=1200,
\end{verbatim}
This line sets the momentum equation timestep to $1200s$.

\item Line 39,
\begin{verbatim}
usingCartesianGrid=.TRUE.,
\end{verbatim}
This line requests that the simulation be performed in a 
Cartesian coordinate system.

\item Line 41,
\begin{verbatim}
delX=60*20E3,
\end{verbatim}
This line sets the horizontal grid spacing between each x-coordinate line
in the discrete grid. The syntax indicates that the discrete grid
should be comprise of $60$ grid lines each separated by $20 \times 10^{3}m$
($20$~km).

\item Line 42,
\begin{verbatim}
delY=60*20E3,
\end{verbatim}
This line sets the horizontal grid spacing between each y-coordinate line
in the discrete grid to $20 \times 10^{3}m$ ($20$~km).

\item Line 43,
\begin{verbatim}
delZ=5000,
\end{verbatim}
This line sets the vertical grid spacing between each z-coordinate line
in the discrete grid to $5000m$ ($5$~km).

\item Line 46,
\begin{verbatim}
bathyFile='topog.box'
\end{verbatim}
This line specifies the name of the file from which the domain
bathymetry is read. This file is a two-dimensional ($x,y$) map of
depths. This file is assumed to contain 64-bit binary numbers 
giving the depth of the model at each grid cell, ordered with the x 
coordinate varying fastest. The points are ordered from low coordinate
to high coordinate for both axes. The units and orientation of the
depths in this file are the same as used in the MITgcm code. In this
experiment, a depth of $0m$ indicates a solid wall and a depth
of $-5000m$ indicates open ocean. The matlab program
{\it input/gendata.m} shows an example of how to generate a
bathymetry file.


\item Line 49,
\begin{verbatim}
zonalWindFile='windx.sin_y'
\end{verbatim}
This line specifies the name of the file from which the x-direction
surface wind stress is read. This file is also a two-dimensional
($x,y$) map and is enumerated and formatted in the same manner as the 
bathymetry file. The matlab program {\it input/gendata.m} includes example 
code to generate a valid {\bf zonalWindFile} file.  

\end{itemize}

\noindent other lines in the file {\it input/data} are standard values
that are described in the MITgcm Getting Started and MITgcm Parameters
notes.

%%\begin{small}
%%\input{part3/case_studies/barotropic_gyre/input/data}
%%\end{small}

\subsubsection{File {\it input/data.pkg}}
\label{www:tutorials}

This file uses standard default values and does not contain
customizations for this experiment.

\subsubsection{File {\it input/eedata}}
\label{www:tutorials}

This file uses standard default values and does not contain
customizations for this experiment.

\subsubsection{File {\it input/windx.sin\_y}}
\label{www:tutorials}

The {\it input/windx.sin\_y} file specifies a two-dimensional ($x,y$) 
map of wind stress ,$\tau_{x}$, values. The units used are $Nm^{-2}$.
Although $\tau_{x}$ is only a function of $y$n in this experiment
this file must still define a complete two-dimensional map in order
to be compatible with the standard code for loading forcing fields 
in MITgcm. The included matlab program {\it input/gendata.m} gives a complete
code for creating the {\it input/windx.sin\_y} file.

\subsubsection{File {\it input/topog.box}}
\label{www:tutorials}


The {\it input/topog.box} file specifies a two-dimensional ($x,y$) 
map of depth values. For this experiment values are either
$0m$ or {\bf -delZ}m, corresponding respectively to a wall or to deep
ocean. The file contains a raw binary stream of data that is enumerated
in the same way as standard MITgcm two-dimensional, horizontal arrays.
The included matlab program {\it input/gendata.m} gives a complete
code for creating the {\it input/topog.box} file.

\subsubsection{File {\it code/SIZE.h}}
\label{www:tutorials}

Two lines are customized in this file for the current experiment

\begin{itemize}

\item Line 39, 
\begin{verbatim} sNx=60, \end{verbatim} this line sets
the lateral domain extent in grid points for the
axis aligned with the x-coordinate.

\item Line 40, 
\begin{verbatim} sNy=60, \end{verbatim} this line sets
the lateral domain extent in grid points for the
axis aligned with the y-coordinate.

\end{itemize}

\begin{small}
\input{part3/case_studies/barotropic_gyre/code/SIZE.h}
\end{small}

\subsubsection{File {\it code/CPP\_OPTIONS.h}}
\label{www:tutorials}

This file uses standard default values and does not contain
customizations for this experiment.


\subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
\label{www:tutorials}

This file uses standard default values and does not contain
customizations for this experiment.

1	afe	1.1	% $Header: /u/gcmpack/manual/part3/case_studies/barotropic_gyre/baro.tex,v 1.10 2004/01/29 15:11:39 edhill Exp $
2			% $Name: $
3
4			\bodytext{bgcolor="#FFFFFFFF"}
5
6			%\begin{center}
7			%{\Large \bf Using MITgcm to Simulate a Rotating Tank in Cylindrical
8			%Coordinates}
9			%
10			%\vspace*{4mm}
11			%
12			%\vspace*{3mm}
13			%{\large June 2004}
14			%\end{center}
15
16			This is the first in a series of tutorials describing
17			example MITgcm numerical experiments. The example experiments
18			include both straightforward examples of idealized geophysical
19			fluid simulations and more involved cases encompassing
20			large scale modeling and
21			automatic differentiation. Both hydrostatic and non-hydrostatic
22			experiments are presented, as well as experiments employing
23			Cartesian, spherical-polar and cube-sphere coordinate systems.
24			These ``case study'' documents include information describing
25			the experimental configuration and detailed information on how to
26			configure the MITgcm code and input files for each experiment.
27
28			\section{Barotropic Ocean Gyre In Cartesian Coordinates}
29			\label{sect:eg-baro}
30			\label{www:tutorials}
31
32
33
34			\subsection{Equations Solved}
35			\label{www:tutorials}
36			The model is configured in hydrostatic form. The implicit free surface form of the
37
38
39			\subsection{Discrete Numerical Configuration}
40			\label{www:tutorials}
41
42			The domain is discretised with
43			a uniform grid spacing in the horizontal set to
44			$\Delta x=\Delta y=20$~km, so
45			that there are sixty grid cells in the $x$ and $y$ directions. Vertically the
46			model is configured with a single layer with depth, $\Delta z$, of $5000$~m.
47
48			\subsubsection{Numerical Stability Criteria}
49			\label{www:tutorials}
50
51
52			\subsection{Code Configuration}
53			\label{www:tutorials}
54			\label{SEC:eg-baro-code_config}
55
56			The model configuration for this experiment resides under the
57			directory {\it verification/exp0/}. The experiment files
58			\begin{itemize}
59			\item {\it input/data}
60			\item {\it input/data.pkg}
61			\item {\it input/eedata},
62			\item {\it input/windx.sin\_y},
63			\item {\it input/topog.box},
64			\item {\it code/CPP\_EEOPTIONS.h}
65			\item {\it code/CPP\_OPTIONS.h},
66			\item {\it code/SIZE.h}.
67			\end{itemize}
68			contain the code customizations and parameter settings for this
69			experiments. Below we describe the customizations
70			to these files associated with this experiment.
71
72			\subsubsection{File {\it input/data}}
73			\label{www:tutorials}
74
75			This file, reproduced completely below, specifies the main parameters
76			for the experiment. The parameters that are significant for this configuration
77			are
78
79			\begin{itemize}
80
81			\item Line 7, \begin{verbatim} viscAh=4.E2, \end{verbatim} this line sets
82			the Laplacian friction coefficient to $400 m^2s^{-1}$
83			\item Line 10, \begin{verbatim} beta=1.E-11, \end{verbatim} this line sets
84			$\beta$ (the gradient of the coriolis parameter, $f$) to $10^{-11} s^{-1}m^{-1}$
85
86			\item Lines 15 and 16
87			\begin{verbatim}
88			rigidLid=.FALSE.,
89			implicitFreeSurface=.TRUE.,
90			\end{verbatim}
91			these lines suppress the rigid lid formulation of the surface
92			pressure inverter and activate the implicit free surface form
93			of the pressure inverter.
94
95			\item Line 27,
96			\begin{verbatim}
97			startTime=0,
98			\end{verbatim}
99			this line indicates that the experiment should start from $t=0$
100			and implicitly suppresses searching for checkpoint files associated
101			with restarting an numerical integration from a previously saved state.
102
103			\item Line 29,
104			\begin{verbatim}
105			endTime=12000,
106			\end{verbatim}
107			this line indicates that the experiment should start finish at $t=12000s$.
108			A restart file will be written at this time that will enable the
109			simulation to be continued from this point.
110
111			\item Line 30,
112			\begin{verbatim}
113			deltaTmom=1200,
114			\end{verbatim}
115			This line sets the momentum equation timestep to $1200s$.
116
117			\item Line 39,
118			\begin{verbatim}
119			usingCartesianGrid=.TRUE.,
120			\end{verbatim}
121			This line requests that the simulation be performed in a
122			Cartesian coordinate system.
123
124			\item Line 41,
125			\begin{verbatim}
126			delX=60*20E3,
127			\end{verbatim}
128			This line sets the horizontal grid spacing between each x-coordinate line
129			in the discrete grid. The syntax indicates that the discrete grid
130			should be comprise of $60$ grid lines each separated by $20 \times 10^{3}m$
131			($20$~km).
132
133			\item Line 42,
134			\begin{verbatim}
135			delY=60*20E3,
136			\end{verbatim}
137			This line sets the horizontal grid spacing between each y-coordinate line
138			in the discrete grid to $20 \times 10^{3}m$ ($20$~km).
139
140			\item Line 43,
141			\begin{verbatim}
142			delZ=5000,
143			\end{verbatim}
144			This line sets the vertical grid spacing between each z-coordinate line
145			in the discrete grid to $5000m$ ($5$~km).
146
147			\item Line 46,
148			\begin{verbatim}
149			bathyFile='topog.box'
150			\end{verbatim}
151			This line specifies the name of the file from which the domain
152			bathymetry is read. This file is a two-dimensional ($x,y$) map of
153			depths. This file is assumed to contain 64-bit binary numbers
154			giving the depth of the model at each grid cell, ordered with the x
155			coordinate varying fastest. The points are ordered from low coordinate
156			to high coordinate for both axes. The units and orientation of the
157			depths in this file are the same as used in the MITgcm code. In this
158			experiment, a depth of $0m$ indicates a solid wall and a depth
159			of $-5000m$ indicates open ocean. The matlab program
160			{\it input/gendata.m} shows an example of how to generate a
161			bathymetry file.
162
163
164			\item Line 49,
165			\begin{verbatim}
166			zonalWindFile='windx.sin_y'
167			\end{verbatim}
168			This line specifies the name of the file from which the x-direction
169			surface wind stress is read. This file is also a two-dimensional
170			($x,y$) map and is enumerated and formatted in the same manner as the
171			bathymetry file. The matlab program {\it input/gendata.m} includes example
172			code to generate a valid {\bf zonalWindFile} file.
173
174			\end{itemize}
175
176			\noindent other lines in the file {\it input/data} are standard values
177			that are described in the MITgcm Getting Started and MITgcm Parameters
178			notes.
179
180			%%\begin{small}
181			%%\input{part3/case_studies/barotropic_gyre/input/data}
182			%%\end{small}
183
184			\subsubsection{File {\it input/data.pkg}}
185			\label{www:tutorials}
186
187			This file uses standard default values and does not contain
188			customizations for this experiment.
189
190			\subsubsection{File {\it input/eedata}}
191			\label{www:tutorials}
192
193			This file uses standard default values and does not contain
194			customizations for this experiment.
195
196			\subsubsection{File {\it input/windx.sin\_y}}
197			\label{www:tutorials}
198
199			The {\it input/windx.sin\_y} file specifies a two-dimensional ($x,y$)
200			map of wind stress ,$\tau_{x}$, values. The units used are $Nm^{-2}$.
201			Although $\tau_{x}$ is only a function of $y$n in this experiment
202			this file must still define a complete two-dimensional map in order
203			to be compatible with the standard code for loading forcing fields
204			in MITgcm. The included matlab program {\it input/gendata.m} gives a complete
205			code for creating the {\it input/windx.sin\_y} file.
206
207			\subsubsection{File {\it input/topog.box}}
208			\label{www:tutorials}
209
210
211			The {\it input/topog.box} file specifies a two-dimensional ($x,y$)
212			map of depth values. For this experiment values are either
213			$0m$ or {\bf -delZ}m, corresponding respectively to a wall or to deep
214			ocean. The file contains a raw binary stream of data that is enumerated
215			in the same way as standard MITgcm two-dimensional, horizontal arrays.
216			The included matlab program {\it input/gendata.m} gives a complete
217			code for creating the {\it input/topog.box} file.
218
219			\subsubsection{File {\it code/SIZE.h}}
220			\label{www:tutorials}
221
222			Two lines are customized in this file for the current experiment
223
224			\begin{itemize}
225
226			\item Line 39,
227			\begin{verbatim} sNx=60, \end{verbatim} this line sets
228			the lateral domain extent in grid points for the
229			axis aligned with the x-coordinate.
230
231			\item Line 40,
232			\begin{verbatim} sNy=60, \end{verbatim} this line sets
233			the lateral domain extent in grid points for the
234			axis aligned with the y-coordinate.
235
236			\end{itemize}
237
238			\begin{small}
239			\input{part3/case_studies/barotropic_gyre/code/SIZE.h}
240			\end{small}
241
242			\subsubsection{File {\it code/CPP\_OPTIONS.h}}
243			\label{www:tutorials}
244
245			This file uses standard default values and does not contain
246			customizations for this experiment.
247
248
249			\subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
250			\label{www:tutorials}
251
252			This file uses standard default values and does not contain
253			customizations for this experiment.
254