s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/s_examples/rotating_tank/tank.tex,v 1.17 2010/08/27 13:25:32 jmc 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{sec:eg-tank}
%\label{www:tutorials}
\begin{rawhtml}
<!-- CMIREDIR:eg-tank: -->
\end{rawhtml}
\begin{center}
(in directory: {\it verification/rotating\_tank/})
\end{center}

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