s_examples/rotating_tank/tank.tex

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