s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.14 2006/04/08 01:50:50 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 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}

\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}\times1\mathrm{cm}$ 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. The files for this experiment can be found in
the verification directory under rotating\_tank.
\\

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