s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.12 2005/06/14 20:09:04 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}
\begin{rawhtml}
<!-- CMIREDIR:eg-tank: -->
\end{rawhtml}

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

\subsection{Overview}
\label{www:tutorials}
                                                                          
This example configuration demonstrates using the MITgcm to simulate a
laboratory demonstration using a differentially heated rotating
annulus of water.  The simulation is configured for a laboratory scale
on a $3^{\circ}$ $\times$ 1cm cyclindrical grid with twenty-nine
vertical levels of 0.5cm each.  This is a typical laboratory setup for
illustration principles of GFD, as well as for a laboratory data
assimilation project.
\\

example illustration from GFD lab here
\\


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


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

 The domain is discretised with a uniform cylindrical grid spacing in
the horizontal set to $\Delta a=1$~cm and $\Delta \phi=3^{\circ}$, so
that there are 120 grid cells in the azimuthal direction and
thirty-one grid cells in the radial, representing a tank 62cm in
diameter.  The bathymetry file sets the depth=0 in the nine lowest
radial rows to represent the central of the annulus.  Vertically the
model is configured with twenty-nine layers of uniform 0.5cm
thickness.
\\
something about heat flux

\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 Lines 9-10, \begin{verbatim} 
viscAh=5.0E-6, 
viscAz=5.0E-6,
\end{verbatim} 


These lines set the Laplacian friction coefficient in the horizontal
and vertical, respectively.  Note that they are several orders of
magnitude smaller than the other examples due to the small scale of
this example.

\item Lines 13-16, \begin{verbatim} 
 diffKhT=2.5E-6,
 diffKzT=2.5E-6,
 diffKhS=1.0E-6,
 diffKzS=1.0E-6,

\end{verbatim} 


These lines set horizontal and vertical diffusion coefficients for
temperature and salinity.  Similarly to the friction coefficients, the
values are a couple of orders of magnitude less than most
 configurations.


\item Line 17, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the 
coriolis term, and represents a tank spinning at about 2.4 rpm.

\item Lines 23 and 24
\begin{verbatim}
rigidLid=.TRUE.,
implicitFreeSurface=.FALSE.,
\end{verbatim}

These lines activate  the rigid lid formulation of the surface
pressure inverter and suppress the implicit free surface form
of the pressure inverter.

\item Line 40,
\begin{verbatim}
nIter=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.
Instead, the file thetaPol.bin will be loaded to initialized the
temperature fields as indicated below, and other variables will be
initialized to their defaults.


\item Line 43,
\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.  Using the ensemble Kalman filter to produce
input fields can necessitate even shorter timesteps.

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

\item Line 57,
\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 comprised of $120$ grid lines each separated by $3^{\circ}$.
                                                                               

\item Line 58,
\begin{verbatim}
dYspacing=0.01,
\end{verbatim}

This line sets the radial cylindrical grid spacing between each
$a$-coordinate line in the discrete grid to $1cm$.

\item Line 59,
\begin{verbatim}
delZ=29*0.005,
\end{verbatim}

This line sets the vertical grid spacing between each of 29
z-coordinate lines in the discrete grid to $0.005m$ ($5$~mm).

\item Line 64,
\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 
($a,\phi$) 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 $\phi$ 
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 65,
\begin{verbatim}
hydrogThetaFile='thetaPol.bin',
\end{verbatim}
This line specifies the name of the file from which the initial values 
of temperature
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 Lines 66 and 67
\begin{verbatim}
 tCylIn  = 0
 tCylOut  = 20
\end{verbatim}
These line specify the temperatures in degrees Celsius of the interior
and exterior walls of the tank -- typically taken to be icewater on
the inside and room temperature on the outside.


\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.  This particular 
experiment is set to random values x around 20C to provide initial 
perturbations.

\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.13	% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.12 2005/06/14 20:09:04 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	edhill	1.11	\begin{rawhtml}
20			<!-- CMIREDIR:eg-tank: -->
21			\end{rawhtml}
22	afe	1.2
23	afe	1.4	This section illustrates an example of MITgcm simulating a laboratory
24	afe	1.10	experiment on much smaller scales than those commonly considered in
25			geophysical
26	afe	1.4	fluid dynamics.
27
28			\subsection{Overview}
29			\label{www:tutorials}
30	afe	1.12
31			This example configuration demonstrates using the MITgcm to simulate a
32			laboratory demonstration using a differentially heated rotating
33			annulus of water. The simulation is configured for a laboratory scale
34			on a $3^{\circ}$ $\times$ 1cm cyclindrical grid with twenty-nine
35			vertical levels of 0.5cm each. This is a typical laboratory setup for
36			illustration principles of GFD, as well as for a laboratory data
37			assimilation project.
38	afe	1.4	\\
39	afe	1.12
40	afe	1.10	example illustration from GFD lab here
41			\\
42	afe	1.4
43
44	afe	1.2
45	afe	1.3
46
47			\subsection{Equations Solved}
48			\label{www:tutorials}
49	afe	1.1
50	afe	1.3
51			\subsection{Discrete Numerical Configuration}
52			\label{www:tutorials}
53
54	afe	1.12	The domain is discretised with a uniform cylindrical grid spacing in
55			the horizontal set to $\Delta a=1$~cm and $\Delta \phi=3^{\circ}$, so
56			that there are 120 grid cells in the azimuthal direction and
57			thirty-one grid cells in the radial, representing a tank 62cm in
58			diameter. The bathymetry file sets the depth=0 in the nine lowest
59			radial rows to represent the central of the annulus. Vertically the
60			model is configured with twenty-nine layers of uniform 0.5cm
61			thickness.
62	afe	1.10	\\
63			something about heat flux
64	afe	1.2
65	afe	1.3	\subsection{Code Configuration}
66	afe	1.1	\label{www:tutorials}
67	afe	1.3	\label{SEC:eg-baro-code_config}
68	afe	1.1
69	afe	1.5	The model configuration for this experiment resides under the
70			directory {\it verification/rotatingi\_tank/}. The experiment files
71	afe	1.1	\begin{itemize}
72			\item {\it input/data}
73			\item {\it input/data.pkg}
74			\item {\it input/eedata},
75	afe	1.5	\item {\it input/bathyPol.bin},
76			\item {\it input/thetaPol.bin},
77	afe	1.1	\item {\it code/CPP\_EEOPTIONS.h}
78			\item {\it code/CPP\_OPTIONS.h},
79	afe	1.5	\item {\it code/SIZE.h}.
80	afe	1.1	\end{itemize}
81	afe	1.5
82	afe	1.3	contain the code customizations and parameter settings for this
83	afe	1.1	experiments. Below we describe the customizations
84			to these files associated with this experiment.
85
86			\subsubsection{File {\it input/data}}
87			\label{www:tutorials}
88
89			This file, reproduced completely below, specifies the main parameters
90			for the experiment. The parameters that are significant for this configuration
91			are
92
93			\begin{itemize}
94
95	afe	1.12	\item Lines 9-10, \begin{verbatim}
96			viscAh=5.0E-6,
97			viscAz=5.0E-6,
98			\end{verbatim}
99
100
101			These lines set the Laplacian friction coefficient in the horizontal
102			and vertical, respectively. Note that they are several orders of
103			magnitude smaller than the other examples due to the small scale of
104			this example.
105
106			\item Lines 13-16, \begin{verbatim}
107			diffKhT=2.5E-6,
108			diffKzT=2.5E-6,
109			diffKhS=1.0E-6,
110			diffKzS=1.0E-6,
111
112			\end{verbatim}
113
114
115			These lines set horizontal and vertical diffusion coefficients for
116			temperature and salinity. Similarly to the friction coefficients, the
117			values are a couple of orders of magnitude less than most
118			configurations.
119
120	afe	1.3
121	afe	1.12	\item Line 17, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the
122			coriolis term, and represents a tank spinning at about 2.4 rpm.
123
124			\item Lines 23 and 24
125	afe	1.3	\begin{verbatim}
126	afe	1.6	rigidLid=.TRUE.,
127			implicitFreeSurface=.FALSE.,
128	afe	1.3	\end{verbatim}
129	afe	1.6
130	afe	1.12	These lines activate the rigid lid formulation of the surface
131			pressure inverter and suppress the implicit free surface form
132	afe	1.3	of the pressure inverter.
133	afe	1.1
134	afe	1.12	\item Line 40,
135	afe	1.1	\begin{verbatim}
136	afe	1.10	nIter=0,
137	afe	1.1	\end{verbatim}
138	afe	1.12	This line indicates that the experiment should start from $t=0$ and
139			implicitly suppresses searching for checkpoint files associated with
140			restarting an numerical integration from a previously saved state.
141			Instead, the file thetaPol.bin will be loaded to initialized the
142			temperature fields as indicated below, and other variables will be
143			initialized to their defaults.
144
145	afe	1.2
146	afe	1.12	\item Line 43,
147	afe	1.1	\begin{verbatim}
148	afe	1.6	deltaT=0.1,
149	afe	1.1	\end{verbatim}
150	afe	1.12	This line sets the integration timestep to $0.1s$. This is an
151			unsually small value among the examples due to the small physical
152			scale of the experiment. Using the ensemble Kalman filter to produce
153			input fields can necessitate even shorter timesteps.
154	afe	1.1
155	afe	1.12	\item Line 56,
156	afe	1.1	\begin{verbatim}
157	afe	1.6	usingCylindricalGrid=.TRUE.,
158	afe	1.1	\end{verbatim}
159	afe	1.3	This line requests that the simulation be performed in a
160	afe	1.7	cylindrical coordinate system.
161	afe	1.1
162	afe	1.12	\item Line 57,
163	afe	1.1	\begin{verbatim}
164	afe	1.7	dXspacing=3,
165	afe	1.1	\end{verbatim}
166	afe	1.10	This line sets the azimuthal grid spacing between each $x$-coordinate line
167	afe	1.3	in the discrete grid. The syntax indicates that the discrete grid
168	afe	1.12	should be comprised of $120$ grid lines each separated by $3^{\circ}$.
169
170	afe	1.7
171	afe	1.12	\item Line 58,
172	afe	1.1	\begin{verbatim}
173	afe	1.7	dYspacing=0.01,
174	afe	1.1	\end{verbatim}
175
176	afe	1.12	This line sets the radial cylindrical grid spacing between each
177			$a$-coordinate line in the discrete grid to $1cm$.
178
179			\item Line 59,
180	afe	1.1	\begin{verbatim}
181	afe	1.7	delZ=29*0.005,
182	afe	1.2	\end{verbatim}
183	afe	1.1
184	afe	1.12	This line sets the vertical grid spacing between each of 29
185			z-coordinate lines in the discrete grid to $0.005m$ ($5$~mm).
186
187			\item Line 64,
188	afe	1.1	\begin{verbatim}
189	afe	1.7	bathyFile='bathyPol.bin',
190	afe	1.1	\end{verbatim}
191			This line specifies the name of the file from which the domain
192	afe	1.7	``bathymetry'' (tank depth) is read. This file is a two-dimensional
193	afe	1.10	($a,\phi$) map of
194	afe	1.1	depths. This file is assumed to contain 64-bit binary numbers
195	afe	1.10	giving the depth of the model at each grid cell, ordered with the $\phi$
196	afe	1.1	coordinate varying fastest. The points are ordered from low coordinate
197	afe	1.7	to high coordinate for both axes. The units and orientation of the
198	afe	1.1	depths in this file are the same as used in the MITgcm code. In this
199	afe	1.7	experiment, a depth of $0m$ indicates an area outside of the tank
200			and a depth
201			f $-0.145m$ indicates the tank itself.
202	afe	1.1
203	afe	1.12	\item Line 65,
204	afe	1.7	\begin{verbatim}
205			hydrogThetaFile='thetaPol.bin',
206			\end{verbatim}
207			This line specifies the name of the file from which the initial values
208	afe	1.10	of temperature
209	afe	1.7	are read. This file is a three-dimensional
210			($x,y,z$) map and is enumerated and formatted in the same manner as the
211			bathymetry file.
212	afe	1.1
213	afe	1.13	\item Lines 66 and 67
214	afe	1.1	\begin{verbatim}
215	afe	1.12	tCylIn = 0
216			tCylOut = 20
217	afe	1.1	\end{verbatim}
218	afe	1.12	These line specify the temperatures in degrees Celsius of the interior
219			and exterior walls of the tank -- typically taken to be icewater on
220	afe	1.13	the inside and room temperature on the outside.
221	afe	1.7
222	afe	1.1
223			\end{itemize}
224
225	afe	1.12	\noindent Other lines in the file {\it input/data} are standard values
226	afe	1.1	that are described in the MITgcm Getting Started and MITgcm Parameters
227			notes.
228
229	afe	1.2	\begin{small}
230	afe	1.5	\input{part3/case_studies/rotating_tank/input/data}
231	afe	1.2	\end{small}
232	afe	1.1
233			\subsubsection{File {\it input/data.pkg}}
234			\label{www:tutorials}
235
236			This file uses standard default values and does not contain
237	afe	1.3	customizations for this experiment.
238	afe	1.1
239			\subsubsection{File {\it input/eedata}}
240			\label{www:tutorials}
241
242			This file uses standard default values and does not contain
243	afe	1.3	customizations for this experiment.
244	afe	1.1
245	afe	1.6	\subsubsection{File {\it input/thetaPol.bin}}
246	afe	1.1	\label{www:tutorials}
247
248	afe	1.6	The {\it input/thetaPol.bin} file specifies a three-dimensional ($x,y,z$)
249	afe	1.10	map of initial values of $\theta$ in degrees Celsius. This particular
250			experiment is set to random values x around 20C to provide initial
251			perturbations.
252	afe	1.1
253	afe	1.6	\subsubsection{File {\it input/bathyPol.bin}}
254	afe	1.1	\label{www:tutorials}
255
256
257	afe	1.6	The {\it input/bathyPol.bin} file specifies a two-dimensional ($x,y$)
258	afe	1.1	map of depth values. For this experiment values are either
259	afe	1.6	$0m$ or {\bf -delZ}m, corresponding respectively to outside or inside of
260			the tank. The file contains a raw binary stream of data that is enumerated
261	afe	1.1	in the same way as standard MITgcm two-dimensional, horizontal arrays.
262
263			\subsubsection{File {\it code/SIZE.h}}
264			\label{www:tutorials}
265
266			Two lines are customized in this file for the current experiment
267
268			\begin{itemize}
269
270			\item Line 39,
271	afe	1.7	\begin{verbatim} sNx=120, \end{verbatim} this line sets
272	afe	1.1	the lateral domain extent in grid points for the
273			axis aligned with the x-coordinate.
274
275			\item Line 40,
276	afe	1.7	\begin{verbatim} sNy=31, \end{verbatim} this line sets
277	afe	1.1	the lateral domain extent in grid points for the
278			axis aligned with the y-coordinate.
279
280			\end{itemize}
281
282			\begin{small}
283	afe	1.7	\input{part3/case_studies/rotating_tank/code/SIZE.h}
284	afe	1.1	\end{small}
285
286			\subsubsection{File {\it code/CPP\_OPTIONS.h}}
287			\label{www:tutorials}
288
289			This file uses standard default values and does not contain
290	afe	1.3	customizations for this experiment.
291	afe	1.1
292
293			\subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
294			\label{www:tutorials}
295
296			This file uses standard default values and does not contain
297	afe	1.3	customizations for this experiment.
298	afe	1.2