--- manual/s_examples/rotating_tank/tank.tex	2004/07/26 21:09:47	1.7
+++ manual/s_examples/rotating_tank/tank.tex	2005/06/14 20:09:04	1.12
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.7 2004/07/26 21:09:47 afe Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/rotating_tank/tank.tex,v 1.12 2005/06/14 20:09:04 afe Exp $
 % $Name:  $
 
 \bodytext{bgcolor="#FFFFFFFF"}
@@ -16,178 +16,51 @@
 \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 common to geophysical
+experiment on much smaller scales than those commonly considered in  
+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.
+                                                                          
+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}$ $\times$ 1cm 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.
 \\
 
+example illustration from GFD lab here
+\\
 
 
-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}
 \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}
-\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. 
+ 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.
 \\
-
-\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$.
+something about heat flux
 
 \subsection{Code Configuration}
 \label{www:tutorials}
@@ -219,82 +92,107 @@
 
 \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 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} 
 
-\item Lines 15 and 16
+
+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 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=.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
+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 30,
+\item Line 43,
 \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.
+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}
 usingCylindricalGrid=.TRUE.,
 \end{verbatim}
 This line requests that the simulation be performed in a 
 cylindrical coordinate system.
 
-\item Line qqq,
+\item Line 57,
 \begin{verbatim}
 dXspacing=3,
 \end{verbatim}
-This line sets the azimuthal 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 $120$ grid lines each separated by $3^{\circ}$.
-                                                                                
-
+should be comprised of $120$ grid lines each separated by $3^{\circ}$.
+                                                                               
 
-\item Line qqq,
+\item Line 58,
 \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,
+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=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='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
+($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
 depths in this file are the same as used in the MITgcm code. In this
@@ -302,27 +200,29 @@
 and a depth
 f $-0.145m$ indicates the tank itself. 
 
-\item Line 49,
+\item Line 65,
 \begin{verbatim}
 hydrogThetaFile='thetaPol.bin',
 \end{verbatim}
 This line specifies the name of the file from which the initial values 
-of $\theta$ 
+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
+\item Lines 66 and 57
 \begin{verbatim}
- tCyl  = 0
+ tCylIn  = 0
+ tCylOut  = 20
 \end{verbatim}
-This line specifies the temperature in degrees Celsius of the interior
-wall of the tank -- usually a bucket of ice water.
+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 inside.
 
 
 \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.
 
@@ -346,7 +246,9 @@
 \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.
+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}
