s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.7 2004/07/26 21:09:47 afe Exp $
% $Name:  $

\bodytext{bgcolor="#FFFFFFFF"}

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

\section{A Rotating Tank in Cylindrical Coordinates}
\label{sect:eg-tank}
\label{www:tutorials}

This section illustrates an example of MITgcm simulating a laboratory
experiment on much smaller scales than those common to geophysical
fluid dynamics.

\subsection{Overview}
\label{www:tutorials}
                                                                                
                                                                                
This example experiment demonstrates using the MITgcm to simulate
a laboratory experiment with a rotating tank of water with an ice
bucket in the center. The simulation is configured for a laboratory
scale on a
$3^{\circ}$ $\times$ 20cm
cyclindrical grid with twenty-nine vertical
levels.
\\


\subsection{Equations Solved}
\label{www:tutorials}


\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}

The Laplacian dissipation coefficient, $A_{h}$, is set to $400 m s^{-1}$.
This value is chosen to yield a Munk layer width \cite{adcroft:95},

\begin{eqnarray}
\label{EQ:eg-baro-munk_layer}
M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}}
\end{eqnarray}

\noindent  of $\approx 100$km. This is greater than the model
resolution $\Delta x$, ensuring that the frictional boundary
layer is well resolved.
\\

\noindent The model is stepped forward with a 
time step $\delta t=1200$secs. With this time step the stability 
parameter to the horizontal Laplacian friction \cite{adcroft:95}


\begin{eqnarray}
\label{EQ:eg-baro-laplacian_stability}
S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2}
\end{eqnarray}

\noindent evaluates to 0.012, which is well below the 0.3 upper limit
for stability. 
\\

\noindent The numerical stability for inertial oscillations  
\cite{adcroft:95} 

\begin{eqnarray}
\label{EQ:eg-baro-inertial_stability}
S_{i} = f^{2} {\delta t}^2
\end{eqnarray}

\noindent evaluates to $0.0144$, which is well below the $0.5$ upper 
limit for stability.
\\

\noindent The advective CFL \cite{adcroft:95} for an extreme maximum 
horizontal flow speed of $ | \vec{u} | = 2 ms^{-1}$

\begin{eqnarray}
\label{EQ:eg-baro-cfl_stability}
S_{a} = \frac{| \vec{u} | \delta t}{ \Delta x}
\end{eqnarray}

\noindent evaluates to 0.12. This is approaching the stability limit
of 0.5 and limits $\delta t$ to $1200s$.

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

The model configuration for this experiment resides under the
directory {\it verification/rotatingi\_tank/}.  The experiment files
\begin{itemize}
\item {\it input/data}
\item {\it input/data.pkg}
\item {\it input/eedata},
\item {\it input/bathyPol.bin},
\item {\it input/thetaPol.bin},
\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 X, \begin{verbatim} viscAh=5.0E-6, \end{verbatim} this line sets
the Laplacian friction coefficient to $0.000006 m^2s^{-1}$, which is ususally 
low because of the small scale, presumably.... qqq

\item Line X, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the 
coriolis term, and represents a tank spinning at qqq
\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=.TRUE.,
implicitFreeSurface=.FALSE.,
\end{verbatim}

these lines do the opposite of the following: 
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 30,
\begin{verbatim}
deltaT=0.1,
\end{verbatim}
This line sets the integration timestep to $0.1s$.  This is an unsually
small value among the examples due to the small physical scale of the 
experiment.

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

\item Line qqq,
\begin{verbatim}
dXspacing=3,
\end{verbatim}
This line sets the azimuthal grid spacing between each x-coordinate line
in the discrete grid. The syntax indicates that the discrete grid
should be comprise of $120$ grid lines each separated by $3^{\circ}$.
                                                                                

\item Line qqq,
\begin{verbatim}
dYspacing=0.01,
\end{verbatim}
This line sets the radial grid spacing between each $\rho$-coordinate line
in the discrete grid to $1cm$.

\item Line 43,
\begin{verbatim}
delZ=29*0.005,
\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='bathyPol.bin',
\end{verbatim}
This line specifies the name of the file from which the domain
``bathymetry'' (tank depth) 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 an area outside of the tank
and a depth
f $-0.145m$ indicates the tank itself. 

\item Line 49,
\begin{verbatim}
hydrogThetaFile='thetaPol.bin',
\end{verbatim}
This line specifies the name of the file from which the initial values 
of $\theta$ 
are read. This file is a three-dimensional
($x,y,z$) map and is enumerated and formatted in the same manner as the 
bathymetry file. 

\item Line qqq
\begin{verbatim}
 tCyl  = 0
\end{verbatim}
This line specifies the temperature in degrees Celsius of the interior
wall of the tank -- usually a bucket of ice water.


\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/rotating_tank/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/thetaPol.bin}}
\label{www:tutorials}

The {\it input/thetaPol.bin} file specifies a three-dimensional ($x,y,z$) 
map of initial values of $\theta$ in degrees Celsius.

\subsubsection{File {\it input/bathyPol.bin}}
\label{www:tutorials}


The {\it input/bathyPol.bin} 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 outside or inside of
the tank. The file contains a raw binary stream of data that is enumerated
in the same way as standard MITgcm two-dimensional, horizontal arrays.

\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=120, \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=31, \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/rotating_tank/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.8	% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.7 2004/07/26 21:09:47 afe Exp $
2	afe	1.1	% $Name: $
3
4			\bodytext{bgcolor="#FFFFFFFF"}
5
6			%\begin{center}
7	afe	1.3	%{\Large \bf Using MITgcm to Simulate a Rotating Tank in Cylindrical
8			%Coordinates}
9	afe	1.1	%
10			%\vspace*{4mm}
11			%
12			%\vspace*{3mm}
13	afe	1.3	%{\large May 2001}
14	afe	1.1	%\end{center}
15
16	afe	1.3	\section{A Rotating Tank in Cylindrical Coordinates}
17			\label{sect:eg-tank}
18	afe	1.2	\label{www:tutorials}
19
20	afe	1.4	This section illustrates an example of MITgcm simulating a laboratory
21			experiment on much smaller scales than those common to geophysical
22			fluid dynamics.
23
24			\subsection{Overview}
25			\label{www:tutorials}
26
27
28			This example experiment demonstrates using the MITgcm to simulate
29			a laboratory experiment with a rotating tank of water with an ice
30			bucket in the center. The simulation is configured for a laboratory
31			scale on a
32			$3^{\circ}$ $\times$ 20cm
33			cyclindrical grid with twenty-nine vertical
34			levels.
35			\\
36
37
38	afe	1.2
39	afe	1.3
40
41			\subsection{Equations Solved}
42			\label{www:tutorials}
43	afe	1.1
44	afe	1.3
45			\subsection{Discrete Numerical Configuration}
46			\label{www:tutorials}
47
48			The domain is discretised with
49			a uniform grid spacing in the horizontal set to
50			$\Delta x=\Delta y=20$~km, so
51			that there are sixty grid cells in the $x$ and $y$ directions. Vertically the
52			model is configured with a single layer with depth, $\Delta z$, of $5000$~m.
53
54	afe	1.1	\subsubsection{Numerical Stability Criteria}
55			\label{www:tutorials}
56
57	afe	1.3	The Laplacian dissipation coefficient, $A_{h}$, is set to $400 m s^{-1}$.
58	afe	1.2	This value is chosen to yield a Munk layer width \cite{adcroft:95},
59	afe	1.3
60	afe	1.2	\begin{eqnarray}
61	afe	1.3	\label{EQ:eg-baro-munk_layer}
62	afe	1.2	M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}}
63			\end{eqnarray}
64
65	afe	1.3	\noindent of $\approx 100$km. This is greater than the model
66			resolution $\Delta x$, ensuring that the frictional boundary
67			layer is well resolved.
68	afe	1.2	\\
69
70			\noindent The model is stepped forward with a
71	afe	1.3	time step $\delta t=1200$secs. With this time step the stability
72	afe	1.2	parameter to the horizontal Laplacian friction \cite{adcroft:95}
73
74
75	afe	1.3
76	afe	1.2	\begin{eqnarray}
77	afe	1.3	\label{EQ:eg-baro-laplacian_stability}
78			S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2}
79	afe	1.2	\end{eqnarray}
80
81	afe	1.3	\noindent evaluates to 0.012, which is well below the 0.3 upper limit
82			for stability.
83	afe	1.2	\\
84
85	afe	1.3	\noindent The numerical stability for inertial oscillations
86	afe	1.2	\cite{adcroft:95}
87
88			\begin{eqnarray}
89	afe	1.3	\label{EQ:eg-baro-inertial_stability}
90			S_{i} = f^{2} {\delta t}^2
91	afe	1.2	\end{eqnarray}
92
93	afe	1.3	\noindent evaluates to $0.0144$, which is well below the $0.5$ upper
94			limit for stability.
95	afe	1.2	\\
96
97	afe	1.3	\noindent The advective CFL \cite{adcroft:95} for an extreme maximum
98			horizontal flow speed of $ \| \vec{u} \| = 2 ms^{-1}$
99	afe	1.2
100			\begin{eqnarray}
101	afe	1.3	\label{EQ:eg-baro-cfl_stability}
102			S_{a} = \frac{\| \vec{u} \| \delta t}{ \Delta x}
103	afe	1.2	\end{eqnarray}
104
105	afe	1.3	\noindent evaluates to 0.12. This is approaching the stability limit
106			of 0.5 and limits $\delta t$ to $1200s$.
107	afe	1.2
108	afe	1.3	\subsection{Code Configuration}
109	afe	1.1	\label{www:tutorials}
110	afe	1.3	\label{SEC:eg-baro-code_config}
111	afe	1.1
112	afe	1.5	The model configuration for this experiment resides under the
113			directory {\it verification/rotatingi\_tank/}. The experiment files
114	afe	1.1	\begin{itemize}
115			\item {\it input/data}
116			\item {\it input/data.pkg}
117			\item {\it input/eedata},
118	afe	1.5	\item {\it input/bathyPol.bin},
119			\item {\it input/thetaPol.bin},
120	afe	1.1	\item {\it code/CPP\_EEOPTIONS.h}
121			\item {\it code/CPP\_OPTIONS.h},
122	afe	1.5	\item {\it code/SIZE.h}.
123	afe	1.1	\end{itemize}
124	afe	1.5
125	afe	1.3	contain the code customizations and parameter settings for this
126	afe	1.1	experiments. Below we describe the customizations
127			to these files associated with this experiment.
128
129			\subsubsection{File {\it input/data}}
130			\label{www:tutorials}
131
132			This file, reproduced completely below, specifies the main parameters
133			for the experiment. The parameters that are significant for this configuration
134			are
135
136			\begin{itemize}
137
138	afe	1.6	\item Line X, \begin{verbatim} viscAh=5.0E-6, \end{verbatim} this line sets
139			the Laplacian friction coefficient to $0.000006 m^2s^{-1}$, which is ususally
140			low because of the small scale, presumably.... qqq
141
142			\item Line X, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the
143			coriolis term, and represents a tank spinning at qqq
144	afe	1.3	\item Line 10, \begin{verbatim} beta=1.E-11, \end{verbatim} this line sets
145			$\beta$ (the gradient of the coriolis parameter, $f$) to $10^{-11} s^{-1}m^{-1}$
146
147			\item Lines 15 and 16
148			\begin{verbatim}
149	afe	1.6	rigidLid=.TRUE.,
150			implicitFreeSurface=.FALSE.,
151	afe	1.3	\end{verbatim}
152	afe	1.6
153			these lines do the opposite of the following:
154			suppress the rigid lid formulation of the surface
155	afe	1.3	pressure inverter and activate the implicit free surface form
156			of the pressure inverter.
157	afe	1.1
158			\item Line 27,
159			\begin{verbatim}
160	afe	1.3	startTime=0,
161	afe	1.1	\end{verbatim}
162	afe	1.3	this line indicates that the experiment should start from $t=0$
163			and implicitly suppresses searching for checkpoint files associated
164			with restarting an numerical integration from a previously saved state.
165	afe	1.2
166	afe	1.1	\item Line 30,
167			\begin{verbatim}
168	afe	1.6	deltaT=0.1,
169	afe	1.1	\end{verbatim}
170	afe	1.6	This line sets the integration timestep to $0.1s$. This is an unsually
171			small value among the examples due to the small physical scale of the
172			experiment.
173	afe	1.1
174	afe	1.3	\item Line 39,
175	afe	1.1	\begin{verbatim}
176	afe	1.6	usingCylindricalGrid=.TRUE.,
177	afe	1.1	\end{verbatim}
178	afe	1.3	This line requests that the simulation be performed in a
179	afe	1.7	cylindrical coordinate system.
180	afe	1.1
181	afe	1.7	\item Line qqq,
182	afe	1.1	\begin{verbatim}
183	afe	1.7	dXspacing=3,
184	afe	1.1	\end{verbatim}
185	afe	1.7	This line sets the azimuthal grid spacing between each x-coordinate line
186	afe	1.3	in the discrete grid. The syntax indicates that the discrete grid
187	afe	1.7	should be comprise of $120$ grid lines each separated by $3^{\circ}$.
188
189
190	afe	1.1
191	afe	1.7	\item Line qqq,
192	afe	1.1	\begin{verbatim}
193	afe	1.7	dYspacing=0.01,
194	afe	1.1	\end{verbatim}
195	afe	1.7	This line sets the radial grid spacing between each $\rho$-coordinate line
196			in the discrete grid to $1cm$.
197	afe	1.1
198			\item Line 43,
199			\begin{verbatim}
200	afe	1.7	delZ=29*0.005,
201	afe	1.2	\end{verbatim}
202	afe	1.3	This line sets the vertical grid spacing between each z-coordinate line
203			in the discrete grid to $5000m$ ($5$~km).
204	afe	1.1
205			\item Line 46,
206			\begin{verbatim}
207	afe	1.7	bathyFile='bathyPol.bin',
208	afe	1.1	\end{verbatim}
209			This line specifies the name of the file from which the domain
210	afe	1.7	``bathymetry'' (tank depth) is read. This file is a two-dimensional
211			($x,y$) map of
212	afe	1.1	depths. This file is assumed to contain 64-bit binary numbers
213	afe	1.7	giving the depth of the model at each grid cell, ordered with the $x$
214	afe	1.1	coordinate varying fastest. The points are ordered from low coordinate
215	afe	1.7	to high coordinate for both axes. The units and orientation of the
216	afe	1.1	depths in this file are the same as used in the MITgcm code. In this
217	afe	1.7	experiment, a depth of $0m$ indicates an area outside of the tank
218			and a depth
219			f $-0.145m$ indicates the tank itself.
220	afe	1.1
221	afe	1.7	\item Line 49,
222			\begin{verbatim}
223			hydrogThetaFile='thetaPol.bin',
224			\end{verbatim}
225			This line specifies the name of the file from which the initial values
226			of $\theta$
227			are read. This file is a three-dimensional
228			($x,y,z$) map and is enumerated and formatted in the same manner as the
229			bathymetry file.
230	afe	1.1
231	afe	1.7	\item Line qqq
232	afe	1.1	\begin{verbatim}
233	afe	1.7	tCyl = 0
234	afe	1.1	\end{verbatim}
235	afe	1.7	This line specifies the temperature in degrees Celsius of the interior
236			wall of the tank -- usually a bucket of ice water.
237
238	afe	1.1
239			\end{itemize}
240
241			\noindent other lines in the file {\it input/data} are standard values
242			that are described in the MITgcm Getting Started and MITgcm Parameters
243			notes.
244
245	afe	1.2	\begin{small}
246	afe	1.5	\input{part3/case_studies/rotating_tank/input/data}
247	afe	1.2	\end{small}
248	afe	1.1
249			\subsubsection{File {\it input/data.pkg}}
250			\label{www:tutorials}
251
252			This file uses standard default values and does not contain
253	afe	1.3	customizations for this experiment.
254	afe	1.1
255			\subsubsection{File {\it input/eedata}}
256			\label{www:tutorials}
257
258			This file uses standard default values and does not contain
259	afe	1.3	customizations for this experiment.
260	afe	1.1
261	afe	1.6	\subsubsection{File {\it input/thetaPol.bin}}
262	afe	1.1	\label{www:tutorials}
263
264	afe	1.6	The {\it input/thetaPol.bin} file specifies a three-dimensional ($x,y,z$)
265			map of initial values of $\theta$ in degrees Celsius.
266	afe	1.1
267	afe	1.6	\subsubsection{File {\it input/bathyPol.bin}}
268	afe	1.1	\label{www:tutorials}
269
270
271	afe	1.6	The {\it input/bathyPol.bin} file specifies a two-dimensional ($x,y$)
272	afe	1.1	map of depth values. For this experiment values are either
273	afe	1.6	$0m$ or {\bf -delZ}m, corresponding respectively to outside or inside of
274			the tank. The file contains a raw binary stream of data that is enumerated
275	afe	1.1	in the same way as standard MITgcm two-dimensional, horizontal arrays.
276
277			\subsubsection{File {\it code/SIZE.h}}
278			\label{www:tutorials}
279
280			Two lines are customized in this file for the current experiment
281
282			\begin{itemize}
283
284			\item Line 39,
285	afe	1.7	\begin{verbatim} sNx=120, \end{verbatim} this line sets
286	afe	1.1	the lateral domain extent in grid points for the
287			axis aligned with the x-coordinate.
288
289			\item Line 40,
290	afe	1.7	\begin{verbatim} sNy=31, \end{verbatim} this line sets
291	afe	1.1	the lateral domain extent in grid points for the
292			axis aligned with the y-coordinate.
293
294			\end{itemize}
295
296			\begin{small}
297	afe	1.7	\input{part3/case_studies/rotating_tank/code/SIZE.h}
298	afe	1.1	\end{small}
299
300			\subsubsection{File {\it code/CPP\_OPTIONS.h}}
301			\label{www:tutorials}
302
303			This file uses standard default values and does not contain
304	afe	1.3	customizations for this experiment.
305	afe	1.1
306
307			\subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
308			\label{www:tutorials}
309
310			This file uses standard default values and does not contain
311	afe	1.3	customizations for this experiment.
312	afe	1.2