--- manual/s_examples/rotating_tank/tank.tex	2004/07/26 18:41:32	1.5
+++ manual/s_examples/rotating_tank/tank.tex	2004/07/27 13:40:09	1.9
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.5 2004/07/26 18:41:32 afe Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.9 2004/07/27 13:40:09 afe Exp $
 % $Name:  $
 
 \bodytext{bgcolor="#FFFFFFFF"}
@@ -36,94 +36,10 @@
 
 
 
-This example experiment demonstrates using the MITgcm to simulate
-a Barotropic, wind-forced, ocean gyre circulation. The experiment 
-is a numerical rendition of the gyre circulation problem similar
-to the problems described analytically by Stommel in 1966 
-\cite{Stommel66} and numerically in Holland et. al \cite{Holland75}.
-
-In this experiment the model 
-is configured to represent a rectangular enclosed box of fluid,
-$1200 \times 1200 $~km in lateral extent. The fluid is $5$~km deep and is forced
-by a constant in time zonal wind stress, $\tau_x$, that varies sinusoidally
-in the ``north-south'' direction. Topologically the grid is Cartesian and 
-the coriolis parameter $f$ is defined according to a mid-latitude beta-plane 
-equation
-
-\begin{equation}
-\label{EQ:eg-baro-fcori}
-f(y) = f_{0}+\beta y
-\end{equation}
  
-\noindent where $y$ is the distance along the ``north-south'' axis of the 
-simulated domain. For this experiment $f_{0}$ is set to $10^{-4}s^{-1}$ in 
-(\ref{EQ:eg-baro-fcori}) and $\beta = 10^{-11}s^{-1}m^{-1}$. 
-\\
-\\
- The sinusoidal wind-stress variations are defined according to 
-
-\begin{equation}
-\label{EQ:eg-baro-taux}
-\tau_x(y) = \tau_{0}\sin(\pi \frac{y}{L_y})
-\end{equation}
- 
-\noindent where $L_{y}$ is the lateral domain extent ($1200$~km) and 
-$\tau_0$ is set to $0.1N m^{-2}$. 
-\\
-\\
-Figure \ref{FIG:eg-baro-simulation_config}
-summarizes the configuration simulated.
-
-%% === eh3 ===
-\begin{figure}
-%% \begin{center}
-%%  \resizebox{7.5in}{5.5in}{
-%%    \includegraphics*[0.2in,0.7in][10.5in,10.5in]
-%%     {part3/case_studies/barotropic_gyre/simulation_config.eps} }
-%% \end{center}
-\centerline{
-  \scalefig{.95}
-  \epsfbox{part3/case_studies/barotropic_gyre/simulation_config.eps}
-}
-\caption{Schematic of simulation domain and wind-stress forcing function 
-for barotropic gyre numerical experiment. The domain is enclosed bu solid
-walls at $x=$~0,1200km and at $y=$~0,1200km.}
-\label{FIG:eg-baro-simulation_config}
-\end{figure}
 
 \subsection{Equations Solved}
 \label{www:tutorials}
-The model is configured in hydrostatic form. The implicit free surface form of the
-pressure equation described in Marshall et. al \cite{marshall:97a} is
-employed.
-A horizontal Laplacian operator $\nabla_{h}^2$ provides viscous
-dissipation. The wind-stress momentum input is added to the momentum equation
-for the ``zonal flow'', $u$. Other terms in the model
-are explicitly switched off for this experiment configuration (see section
-\ref{SEC:code_config} ), yielding an active set of equations solved in this
-configuration as follows 
-
-\begin{eqnarray}
-\label{EQ:eg-baro-model_equations}
-\frac{Du}{Dt} - fv +
-              g\frac{\partial \eta}{\partial x} -
-              A_{h}\nabla_{h}^2u
-& = &
-\frac{\tau_{x}}{\rho_{0}\Delta z}
-\\
-\frac{Dv}{Dt} + fu + g\frac{\partial \eta}{\partial y} -
-              A_{h}\nabla_{h}^2v
-& = &
-0
-\\
-\frac{\partial \eta}{\partial t} + \nabla_{h}\cdot \vec{u}
-&=&
-0
-\end{eqnarray}
-
-\noindent where $u$ and $v$ and the $x$ and $y$ components of the
-flow vector $\vec{u}$.
-\\
 
 
 \subsection{Discrete Numerical Configuration}
@@ -135,59 +51,6 @@
 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}
-\label{www:tutorials}
-
-The Laplacian dissipation coefficient, $A_{h}$, is set to $400 m s^{-1}$.
-This value is chosen to yield a Munk layer width \cite{adcroft:95},
-
-\begin{eqnarray}
-\label{EQ:eg-baro-munk_layer}
-M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}}
-\end{eqnarray}
-
-\noindent  of $\approx 100$km. This is greater than the model
-resolution $\Delta x$, ensuring that the frictional boundary
-layer is well resolved.
-\\
-
-\noindent The model is stepped forward with a 
-time step $\delta t=1200$secs. With this time step the stability 
-parameter to the horizontal Laplacian friction \cite{adcroft:95}
-
-
-
-\begin{eqnarray}
-\label{EQ:eg-baro-laplacian_stability}
-S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2}
-\end{eqnarray}
-
-\noindent evaluates to 0.012, which is well below the 0.3 upper limit
-for stability. 
-\\
-
-\noindent The numerical stability for inertial oscillations  
-\cite{adcroft:95} 
-
-\begin{eqnarray}
-\label{EQ:eg-baro-inertial_stability}
-S_{i} = f^{2} {\delta t}^2
-\end{eqnarray}
-
-\noindent evaluates to $0.0144$, which is well below the $0.5$ upper 
-limit for stability.
-\\
-
-\noindent The advective CFL \cite{adcroft:95} for an extreme maximum 
-horizontal flow speed of $ | \vec{u} | = 2 ms^{-1}$
-
-\begin{eqnarray}
-\label{EQ:eg-baro-cfl_stability}
-S_{a} = \frac{| \vec{u} | \delta t}{ \Delta x}
-\end{eqnarray}
-
-\noindent evaluates to 0.12. This is approaching the stability limit
-of 0.5 and limits $\delta t$ to $1200s$.
 
 \subsection{Code Configuration}
 \label{www:tutorials}
@@ -219,17 +82,23 @@
 
 \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 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=.FALSE.,
-implicitFreeSurface=.TRUE.,
+rigidLid=.TRUE.,
+implicitFreeSurface=.FALSE.,
 \end{verbatim}
-these lines suppress the rigid lid formulation of the surface
+
+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.
 
@@ -241,76 +110,78 @@
 and implicitly suppresses searching for checkpoint files associated
 with restarting an numerical integration from a previously saved state.
 
-\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,
 \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.
 
 \item Line 39,
 \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 qqq,
 \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 comprise of $120$ grid lines each separated by $3^{\circ}$.
+                                                                                
+
 
-\item Line 42,
+\item Line qqq,
 \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).
+This line sets the radial grid spacing between each $\rho$-coordinate line
+in the discrete grid to $1cm$.
 
 \item Line 43,
 \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,
 \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 
+($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 
+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
+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 49,
 \begin{verbatim}
-zonalWindFile='windx.sin_y'
+hydrogThetaFile='thetaPol.bin',
 \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.  
+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}
 
@@ -334,28 +205,21 @@
 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.
 
-\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}
@@ -365,19 +229,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}}