s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.9 2004/07/27 13:40:09 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 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 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.
\\
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. 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 Line 10, \begin{verbatim} viscAh=5.0E-6, \end{verbatim} this line sets
the Laplacian friction coefficient to $6 \times 10^{-6} m^2s^{-1}$, 
which is ususally 
low because of the small scale, presumably.... qqq

\item Line 19, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the 
coriolis term, and represents a tank spinning at 2/s
\item Line 20, \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 27 and 28
\begin{verbatim}
rigidLid=.TRUE.,
implicitFreeSurface=.FALSE.,
\end{verbatim}

qqq 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 44,
\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.

\item Line 47,
\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 58,
\begin{verbatim}
usingCylindricalGrid=.TRUE.,
\end{verbatim}
This line requests that the simulation be performed in a 
cylindrical coordinate system.

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