s_examples/rotating_tank/tank.tex

% $Header: /u/gcmpack/manual/part3/case_studies/rotating_tank/tank.tex,v 1.8 2004/07/26 21:25:34 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 common to geophysical
fluid dynamics.

\subsection{Overview}
\label{www:tutorials}
                                                                                
                                                                                
This example experiment demonstrates using the MITgcm to simulate
a laboratory experiment with 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.
\\


\subsection{Equations Solved}
\label{www:tutorials}


\subsection{Discrete Numerical Configuration}
\label{www:tutorials}

 The domain is discretised with 
a uniform grid spacing in the horizontal set to
 $\Delta x=\Delta y=20$~km, so 
that there are sixty grid cells in the $x$ and $y$ directions. Vertically the 
model is configured with a single layer with depth, $\Delta z$, of $5000$~m. 


\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 X, \begin{verbatim} viscAh=5.0E-6, \end{verbatim} this line sets
the Laplacian friction coefficient to $0.000006 m^2s^{-1}$, which is ususally 
low because of the small scale, presumably.... qqq

\item Line X, \begin{verbatim}f0=0.5 , \end{verbatim} this line sets the 
coriolis term, and represents a tank spinning at qqq
\item Line 10, \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 15 and 16
\begin{verbatim}
rigidLid=.TRUE.,
implicitFreeSurface=.FALSE.,
\end{verbatim}

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

\item Line qqq,
\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 qqq,
\begin{verbatim}
dYspacing=0.01,
\end{verbatim}
This line sets the radial grid spacing between each $\rho$-coordinate line
in the discrete grid to $1cm$.

\item Line 43,
\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 46,
\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 
($x,y$) 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 $x$ 
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 49,
\begin{verbatim}
hydrogThetaFile='thetaPol.bin',
\end{verbatim}
This line specifies the name of the file from which the initial values 
of $\theta$ 
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.

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