--- manual/s_examples/rotating_tank/tank.tex	2004/06/22 15:07:37	1.1
+++ manual/s_examples/rotating_tank/tank.tex	2008/01/15 20:16:44	1.16
@@ -1,70 +1,83 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.1 2004/06/22 15:07:37 afe Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.16 2008/01/15 20:16:44 jmc Exp $
 % $Name:  $
 
 \bodytext{bgcolor="#FFFFFFFF"}
 
 %\begin{center} 
-%{\Large \bf Using MITgcm to Simulate a Rotating Tank in Cylindrical 
+%{\Large \bf Using MITgcm to Simulate a Rotating Tank in Cylindrical
 %Coordinates}
 %
 %\vspace*{4mm}
 %
 %\vspace*{3mm}
-%{\large June 2004}
+%{\large May 2001}
 %\end{center}
 
-This is the first in a series of tutorials describing
-example MITgcm numerical experiments. The example experiments 
-include both straightforward examples of idealized geophysical 
-fluid simulations and more involved cases encompassing
-large scale modeling and
-automatic differentiation. Both hydrostatic and non-hydrostatic 
-experiments are presented, as well as experiments employing
-Cartesian, spherical-polar and cube-sphere coordinate systems.
-These ``case study'' documents include information describing
-the experimental configuration and detailed information on how to
-configure the MITgcm code and input files for each experiment.
-
-\section{Barotropic Ocean Gyre In Cartesian Coordinates}
-\label{sect:eg-baro}
+\section{A Rotating Tank in Cylindrical Coordinates}
+\label{sect: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}
-The model is configured in hydrostatic form. The implicit free surface form of the
 
+ 
 
-\subsection{Discrete Numerical Configuration}
+\subsection{Equations Solved}
 \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. 
 
-\subsubsection{Numerical Stability Criteria}
+\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-baro-code_config}
 
-The model configuration for this experiment resides under the 
-directory {\it verification/exp0/}.  The experiment files 
+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/windx.sin\_y},
-\item {\it input/topog.box},
+\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}. 
+\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.
@@ -78,108 +91,143 @@
 
 \begin{itemize}
 
-\item Line 7, \begin{verbatim} viscAh=4.E2, \end{verbatim} this line sets
-the Laplacian friction coefficient to $400 m^2s^{-1}$
-\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 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 Lines 15 and 16
+\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=.FALSE.,
-implicitFreeSurface=.TRUE.,
+rigidLid=.TRUE.,
+implicitFreeSurface=.FALSE.,
 \end{verbatim}
-these lines suppress the rigid lid formulation of the surface
-pressure inverter and activate the implicit free surface form
+
+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 27,
+\item Line 40,
 \begin{verbatim}
-startTime=0,
+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.
+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 29,
-\begin{verbatim}
-endTime=12000,
-\end{verbatim}
-this line indicates that the experiment should start finish at $t=12000s$.
-A restart file will be written at this time that will enable the
-simulation to be continued from this point.
 
-\item Line 30,
+\item Line 43,
 \begin{verbatim}
-deltaTmom=1200,
+deltaT=0.1,
 \end{verbatim}
-This line sets the momentum equation timestep to $1200s$.
+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 39,
+\item Line 56,
 \begin{verbatim}
-usingCartesianGrid=.TRUE.,
+usingCylindricalGrid=.TRUE.,
 \end{verbatim}
 This line requests that the simulation be performed in a 
-Cartesian coordinate system.
+cylindrical coordinate system.
 
-\item Line 41,
+\item Line 57,
 \begin{verbatim}
-delX=60*20E3,
+dXspacing=3,
 \end{verbatim}
-This line sets the horizontal grid spacing between each x-coordinate line
+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 $60$ grid lines each separated by $20 \times 10^{3}m$
-($20$~km).
+should be comprised of $120$ grid lines each separated by $3^{\circ}$.
+                                                                               
 
-\item Line 42,
+\item Line 58,
 \begin{verbatim}
-delY=60*20E3,
+dYspacing=0.01,
 \end{verbatim}
-This line sets the horizontal grid spacing between each y-coordinate line
-in the discrete grid to $20 \times 10^{3}m$ ($20$~km).
 
-\item Line 43,
+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=5000,
+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,
+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='topog.box'
+bathyFile='bathyPol.bin',
 \end{verbatim}
 This line specifies the name of the file from which the domain
-bathymetry is read. This file is a two-dimensional ($x,y$) map of
+``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 x 
+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
+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 a solid wall and a depth
-of $-5000m$ indicates open ocean. The matlab program
-{\it input/gendata.m} shows an example of how to generate a
-bathymetry file.
+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 Line 49,
+\item Lines 66 and 67
 \begin{verbatim}
-zonalWindFile='windx.sin_y'
+ tCylIn  = 0
+ tCylOut  = 20
 \end{verbatim}
-This line specifies the name of the file from which the x-direction
-surface wind stress is read. This file is also a two-dimensional
-($x,y$) map and is enumerated and formatted in the same manner as the 
-bathymetry file. The matlab program {\it input/gendata.m} includes example 
-code to generate a valid {\bf zonalWindFile} file.  
+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
+\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/barotropic_gyre/input/data}
-%%\end{small}
+\begin{small}
+\input{part3/case_studies/rotating_tank/input/data}
+\end{small}
 
 \subsubsection{File {\it input/data.pkg}}
 \label{www:tutorials}
@@ -193,28 +241,23 @@
 This file uses standard default values and does not contain
 customizations for this experiment.
 
-\subsubsection{File {\it input/windx.sin\_y}}
+\subsubsection{File {\it input/thetaPol.bin}}
 \label{www:tutorials}
 
-The {\it input/windx.sin\_y} file specifies a two-dimensional ($x,y$) 
-map of wind stress ,$\tau_{x}$, values. The units used are $Nm^{-2}$.
-Although $\tau_{x}$ is only a function of $y$n in this experiment
-this file must still define a complete two-dimensional map in order
-to be compatible with the standard code for loading forcing fields 
-in MITgcm. The included matlab program {\it input/gendata.m} gives a complete
-code for creating the {\it input/windx.sin\_y} file.
+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/topog.box}}
+\subsubsection{File {\it input/bathyPol.bin}}
 \label{www:tutorials}
 
 
-The {\it input/topog.box} file specifies a two-dimensional ($x,y$) 
+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 a wall or to deep
-ocean. The file contains a raw binary stream of data that is enumerated
+$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.
-The included matlab program {\it input/gendata.m} gives a complete
-code for creating the {\it input/topog.box} file.
 
 \subsubsection{File {\it code/SIZE.h}}
 \label{www:tutorials}
@@ -224,19 +267,19 @@
 \begin{itemize}
 
 \item Line 39, 
-\begin{verbatim} sNx=60, \end{verbatim} this line sets
+\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=60, \end{verbatim} this line sets
+\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/barotropic_gyre/code/SIZE.h}
+\input{part3/case_studies/rotating_tank/code/SIZE.h}
 \end{small}
 
 \subsubsection{File {\it code/CPP\_OPTIONS.h}}
