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	jmc	1.18	% $Header: /u/gcmpack/manual/s_examples/rotating_tank/tank.tex,v 1.17 2010/08/27 13:25:32 jmc 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	jmc	1.18	\label{sec:eg-tank}
18			%\label{www:tutorials}
19	edhill	1.11	\begin{rawhtml}
20			<!-- CMIREDIR:eg-tank: -->
21			\end{rawhtml}
22	jmc	1.16	\begin{center}
23			(in directory: {\it verification/rotating\_tank/})
24			\end{center}
25	afe	1.2
26	afe	1.4	\subsection{Overview}
27	jmc	1.18	%\label{www:tutorials}
28	afe	1.12
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	edhill	1.14	on a $3^{\circ}\times1\mathrm{cm}$ cyclindrical grid with twenty-nine
33	afe	1.12	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	molod	1.15	assimilation project. The files for this experiment can be found in
36			the verification directory under rotating\_tank.
37	afe	1.4	\\
38	afe	1.12
39	afe	1.10	example illustration from GFD lab here
40			\\
41	afe	1.4
42
43	afe	1.2
44	afe	1.3
45
46			\subsection{Equations Solved}
47	jmc	1.18	%\label{www:tutorials}
48	afe	1.1
49	afe	1.3
50			\subsection{Discrete Numerical Configuration}
51	jmc	1.18	%\label{www:tutorials}
52	afe	1.3
53	afe	1.12	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	afe	1.10	\\
62			something about heat flux
63	afe	1.2
64	afe	1.3	\subsection{Code Configuration}
65	jmc	1.18	%\label{www:tutorials}
66			\label{sec:eg-tank-code_config}
67	afe	1.1
68	afe	1.5	The model configuration for this experiment resides under the
69			directory {\it verification/rotatingi\_tank/}. The experiment files
70	afe	1.1	\begin{itemize}
71			\item {\it input/data}
72			\item {\it input/data.pkg}
73			\item {\it input/eedata},
74	afe	1.5	\item {\it input/bathyPol.bin},
75			\item {\it input/thetaPol.bin},
76	afe	1.1	\item {\it code/CPP\_EEOPTIONS.h}
77			\item {\it code/CPP\_OPTIONS.h},
78	afe	1.5	\item {\it code/SIZE.h}.
79	afe	1.1	\end{itemize}
80	afe	1.5
81	afe	1.3	contain the code customizations and parameter settings for this
82	afe	1.1	experiments. Below we describe the customizations
83			to these files associated with this experiment.
84
85			\subsubsection{File {\it input/data}}
86	jmc	1.18	%\label{www:tutorials}
87	afe	1.1
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	afe	1.12	\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	afe	1.3
120	afe	1.12	\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	afe	1.3	\begin{verbatim}
125	afe	1.6	rigidLid=.TRUE.,
126			implicitFreeSurface=.FALSE.,
127	afe	1.3	\end{verbatim}
128	afe	1.6
129	afe	1.12	These lines activate the rigid lid formulation of the surface
130			pressure inverter and suppress the implicit free surface form
131	afe	1.3	of the pressure inverter.
132	afe	1.1
133	afe	1.12	\item Line 40,
134	afe	1.1	\begin{verbatim}
135	afe	1.10	nIter=0,
136	afe	1.1	\end{verbatim}
137	afe	1.12	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	afe	1.2
145	afe	1.12	\item Line 43,
146	afe	1.1	\begin{verbatim}
147	afe	1.6	deltaT=0.1,
148	afe	1.1	\end{verbatim}
149	afe	1.12	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	afe	1.1
154	afe	1.12	\item Line 56,
155	afe	1.1	\begin{verbatim}
156	afe	1.6	usingCylindricalGrid=.TRUE.,
157	afe	1.1	\end{verbatim}
158	afe	1.3	This line requests that the simulation be performed in a
159	afe	1.7	cylindrical coordinate system.
160	afe	1.1
161	afe	1.12	\item Line 57,
162	afe	1.1	\begin{verbatim}
163	afe	1.7	dXspacing=3,
164	afe	1.1	\end{verbatim}
165	afe	1.10	This line sets the azimuthal grid spacing between each $x$-coordinate line
166	afe	1.3	in the discrete grid. The syntax indicates that the discrete grid
167	afe	1.12	should be comprised of $120$ grid lines each separated by $3^{\circ}$.
168
169	afe	1.7
170	afe	1.12	\item Line 58,
171	afe	1.1	\begin{verbatim}
172	afe	1.7	dYspacing=0.01,
173	afe	1.1	\end{verbatim}
174
175	afe	1.12	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	afe	1.1	\begin{verbatim}
180	afe	1.7	delZ=29*0.005,
181	afe	1.2	\end{verbatim}
182	afe	1.1
183	afe	1.12	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	afe	1.1	\begin{verbatim}
188	afe	1.7	bathyFile='bathyPol.bin',
189	afe	1.1	\end{verbatim}
190			This line specifies the name of the file from which the domain
191	afe	1.7	``bathymetry'' (tank depth) is read. This file is a two-dimensional
192	afe	1.10	($a,\phi$) map of
193	afe	1.1	depths. This file is assumed to contain 64-bit binary numbers
194	afe	1.10	giving the depth of the model at each grid cell, ordered with the $\phi$
195	afe	1.1	coordinate varying fastest. The points are ordered from low coordinate
196	afe	1.7	to high coordinate for both axes. The units and orientation of the
197	afe	1.1	depths in this file are the same as used in the MITgcm code. In this
198	afe	1.7	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	afe	1.1
202	afe	1.12	\item Line 65,
203	afe	1.7	\begin{verbatim}
204			hydrogThetaFile='thetaPol.bin',
205			\end{verbatim}
206			This line specifies the name of the file from which the initial values
207	afe	1.10	of temperature
208	afe	1.7	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	afe	1.1
212	afe	1.13	\item Lines 66 and 67
213	afe	1.1	\begin{verbatim}
214	afe	1.12	tCylIn = 0
215			tCylOut = 20
216	afe	1.1	\end{verbatim}
217	afe	1.12	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	afe	1.13	the inside and room temperature on the outside.
220	afe	1.7
221	afe	1.1
222			\end{itemize}
223
224	afe	1.12	\noindent Other lines in the file {\it input/data} are standard values
225	afe	1.1	that are described in the MITgcm Getting Started and MITgcm Parameters
226			notes.
227
228	afe	1.2	\begin{small}
229	jmc	1.17	\input{s_examples/rotating_tank/input/data}
230	afe	1.2	\end{small}
231	afe	1.1
232			\subsubsection{File {\it input/data.pkg}}
233	jmc	1.18	%\label{www:tutorials}
234	afe	1.1
235			This file uses standard default values and does not contain
236	afe	1.3	customizations for this experiment.
237	afe	1.1
238			\subsubsection{File {\it input/eedata}}
239	jmc	1.18	%\label{www:tutorials}
240	afe	1.1
241			This file uses standard default values and does not contain
242	afe	1.3	customizations for this experiment.
243	afe	1.1
244	afe	1.6	\subsubsection{File {\it input/thetaPol.bin}}
245	jmc	1.18	%\label{www:tutorials}
246	afe	1.1
247	afe	1.6	The {\it input/thetaPol.bin} file specifies a three-dimensional ($x,y,z$)
248	afe	1.10	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	afe	1.1
252	afe	1.6	\subsubsection{File {\it input/bathyPol.bin}}
253	jmc	1.18	%\label{www:tutorials}
254	afe	1.1
255
256	afe	1.6	The {\it input/bathyPol.bin} file specifies a two-dimensional ($x,y$)
257	afe	1.1	map of depth values. For this experiment values are either
258	afe	1.6	$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	afe	1.1	in the same way as standard MITgcm two-dimensional, horizontal arrays.
261
262			\subsubsection{File {\it code/SIZE.h}}
263	jmc	1.18	%\label{www:tutorials}
264	afe	1.1
265			Two lines are customized in this file for the current experiment
266
267			\begin{itemize}
268
269			\item Line 39,
270	afe	1.7	\begin{verbatim} sNx=120, \end{verbatim} this line sets
271	afe	1.1	the lateral domain extent in grid points for the
272			axis aligned with the x-coordinate.
273
274			\item Line 40,
275	afe	1.7	\begin{verbatim} sNy=31, \end{verbatim} this line sets
276	afe	1.1	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	jmc	1.17	\input{s_examples/rotating_tank/code/SIZE.h}
283	afe	1.1	\end{small}
284
285			\subsubsection{File {\it code/CPP\_OPTIONS.h}}
286	jmc	1.18	%\label{www:tutorials}
287	afe	1.1
288			This file uses standard default values and does not contain
289	afe	1.3	customizations for this experiment.
290	afe	1.1
291
292			\subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
293	jmc	1.18	%\label{www:tutorials}
294	afe	1.1
295			This file uses standard default values and does not contain
296	afe	1.3	customizations for this experiment.
297	afe	1.2