--- manual/s_examples/rotating_tank/tank.tex	2004/06/22 15:07:37	1.1
+++ manual/s_examples/rotating_tank/tank.tex	2004/06/22 16:56:31	1.2
@@ -1,11 +1,15 @@
-% $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.2 2004/06/22 16:56:31 afe Exp $
 % $Name:  $
 
+\section{Simulating a Rotating Tank in Cylindrical Coordinates}
+\label{www:tutorials}
+\label{sect:eg-tank}
+
 \bodytext{bgcolor="#FFFFFFFF"}
 
 %\begin{center} 
-%{\Large \bf Using MITgcm to Simulate a Rotating Tank in Cylindrical 
-%Coordinates}
+%{\Large \bf Simulating a Rotating Tank in Cylindrical Coordinates}
+%
 %
 %\vspace*{4mm}
 %
@@ -13,59 +17,307 @@
 %{\large June 2004}
 %\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}
+\subsection{Introduction}
 \label{www:tutorials}
 
-
-
-\subsection{Equations Solved}
-\label{www:tutorials}
-The model is configured in hydrostatic form. The implicit free surface form of the
+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.   
+\\
+
+The model is forced with climatological wind stress data and surface
+flux data from DaSilva \cite{DaSilva94}. Climatological data
+from Levitus \cite{Levitus94} is used to initialize the model hydrography.
+Levitus seasonal climatology data is also used throughout the calculation
+to provide additional air-sea fluxes.
+These fluxes are combined with the DaSilva climatological estimates of
+surface heat flux and fresh water, resulting in a mixed boundary
+condition of the style described in Haney \cite{Haney}.
+Altogether, this yields the following forcing applied
+in the model surface layer.
+
+
+\noindent where ${\cal F}_{u}$, ${\cal F}_{v}$, ${\cal F}_{\theta}$,
+${\cal F}_{s}$ are the forcing terms in the zonal and meridional
+momentum and in the potential temperature and salinity
+equations respectively.
+The term $\Delta z_{s}$ represents the top ocean layer thickness in
+meters.
+It is used in conjunction with a reference density, $\rho_{0}$
+(here set to $999.8\,{\rm kg\,m^{-3}}$), a
+reference salinity, $S_{0}$ (here set to 35~ppt),
+and a specific heat capacity, $C_{p}$ (here set to
+$4000~{\rm J}~^{\circ}{\rm C}^{-1}~{\rm kg}^{-1}$), to convert
+input dataset values into time tendencies of
+potential temperature (with units of $^{\circ}{\rm C}~{\rm s}^{-1}$),
+salinity (with units ${\rm ppt}~s^{-1}$) and
+velocity (with units ${\rm m}~{\rm s}^{-2}$).
+The externally supplied forcing fields used in this
+experiment are $\tau_{x}$, $\tau_{y}$, $\theta^{\ast}$, $S^{\ast}$,
+$\cal{Q}$ and $\cal{E}-\cal{P}-\cal{R}$. The wind stress fields ($\tau_x$, $\tau_y$)
+have units of ${\rm N}~{\rm m}^{-2}$. The temperature forcing fields
+($\theta^{\ast}$ and $Q$) have units of $^{\circ}{\rm C}$ and ${\rm W}~{\rm m}^{-2}$
+respectively. The salinity forcing fields ($S^{\ast}$ and 
+$\cal{E}-\cal{P}-\cal{R}$) have units of ${\rm ppt}$ and ${\rm m}~{\rm s}^{-1}$
+respectively.
+\\
+
+
+Figures (\ref{FIG:sim_config_tclim}-\ref{FIG:sim_config_empmr}) show the
+relaxation temperature ($\theta^{\ast}$) and salinity ($S^{\ast}$) fields,
+the wind stress components ($\tau_x$ and $\tau_y$), the heat flux ($Q$)
+and the net fresh water flux (${\cal E} - {\cal P} - {\cal R}$) used
+in equations \ref{EQ:eg-hs-global_forcing_fu}-\ref{EQ:eg-hs-global_forcing_fs}. The figures
+also indicate the lateral extent and coastline used in the experiment.
+Figure ({\ref{FIG:model_bathymetry}) shows the depth contours of the model
+domain.
 
 
 \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. 
+
+ The model is configured in hydrostatic form.  The domain is discretised with 
+a uniform grid spacing in latitude and longitude on the sphere
+ $\Delta \phi=\Delta \lambda=4^{\circ}$, so 
+that there are ninety grid cells in the zonal and forty in the 
+meridional direction. The internal model coordinate variables
+$x$ and $y$ are initialized according to
+\begin{eqnarray}
+x=r\cos(\phi),~\Delta x & = &r\cos(\Delta \phi) \\
+y=r\lambda,~\Delta x &= &r\Delta \lambda 
+\end{eqnarray}
+
+Arctic polar regions are not
+included in this experiment. Meridionally the model extends from
+$80^{\circ}{\rm S}$ to $80^{\circ}{\rm N}$.
+Vertically the model is configured with twenty layers with the 
+following thicknesses
+$\Delta z_{1} = 50\,{\rm m},\,
+ \Delta z_{2} = 50\,{\rm m},\,
+ \Delta z_{3} = 55\,{\rm m},\,
+ \Delta z_{4} = 60\,{\rm m},\,
+ \Delta z_{5} = 65\,{\rm m},\,
+$
+$
+ \Delta z_{6}~=~70\,{\rm m},\,
+ \Delta z_{7}~=~80\,{\rm m},\,
+ \Delta z_{8}~=95\,{\rm m},\,
+ \Delta z_{9}=120\,{\rm m},\,
+ \Delta z_{10}=155\,{\rm m},\,
+$
+$
+ \Delta z_{11}=200\,{\rm m},\,
+ \Delta z_{12}=260\,{\rm m},\,
+ \Delta z_{13}=320\,{\rm m},\,
+ \Delta z_{14}=400\,{\rm m},\,
+ \Delta z_{15}=480\,{\rm m},\,
+$
+$
+ \Delta z_{16}=570\,{\rm m},\,
+ \Delta z_{17}=655\,{\rm m},\,
+ \Delta z_{18}=725\,{\rm m},\,
+ \Delta z_{19}=775\,{\rm m},\,
+ \Delta z_{20}=815\,{\rm m}
+$ (here the numeric subscript indicates the model level index number, ${\tt k}$).
+The implicit free surface form of the pressure equation described in Marshall et. al 
+\cite{marshall:97a} is employed. A Laplacian operator, $\nabla^2$, provides viscous
+dissipation. Thermal and haline diffusion is also represented by a Laplacian operator.
+
+Wind-stress forcing is added to the momentum equations for both
+the zonal flow, $u$ and the meridional flow $v$, according to equations 
+(\ref{EQ:eg-hs-global_forcing_fu}) and (\ref{EQ:eg-hs-global_forcing_fv}).
+Thermodynamic forcing inputs are added to the equations for
+potential temperature, $\theta$, and salinity, $S$, according to equations 
+(\ref{EQ:eg-hs-global_forcing_ft}) and (\ref{EQ:eg-hs-global_forcing_fs}).
+This produces a set of equations solved in this configuration as follows:
+
+\begin{eqnarray}
+\label{EQ:eg-hs-model_equations}
+\frac{Du}{Dt} - fv + 
+  \frac{1}{\rho}\frac{\partial p^{'}}{\partial x} - 
+  \nabla_{h}\cdot A_{h}\nabla_{h}u - 
+  \frac{\partial}{\partial z}A_{z}\frac{\partial u}{\partial z} 
+ & = &
+\begin{cases}
+{\cal F}_u & \text{(surface)} \\
+0 & \text{(interior)}
+\end{cases}
+\\
+\frac{Dv}{Dt} + fu + 
+  \frac{1}{\rho}\frac{\partial p^{'}}{\partial y} - 
+  \nabla_{h}\cdot A_{h}\nabla_{h}v - 
+  \frac{\partial}{\partial z}A_{z}\frac{\partial v}{\partial z} 
+& = &
+\begin{cases}
+{\cal F}_v & \text{(surface)} \\
+0 & \text{(interior)}
+\end{cases}
+\\
+\frac{\partial \eta}{\partial t} + \nabla_{h}\cdot \vec{u}
+&=&
+0
+\\
+\frac{D\theta}{Dt} -
+ \nabla_{h}\cdot K_{h}\nabla_{h}\theta
+ - \frac{\partial}{\partial z}\Gamma(K_{z})\frac{\partial\theta}{\partial z} 
+& = &
+\begin{cases}
+{\cal F}_\theta & \text{(surface)} \\
+0 & \text{(interior)}
+\end{cases}
+\\
+\frac{D s}{Dt} -
+ \nabla_{h}\cdot K_{h}\nabla_{h}s
+ - \frac{\partial}{\partial z}\Gamma(K_{z})\frac{\partial s}{\partial z} 
+& = &
+\begin{cases}
+{\cal F}_s & \text{(surface)} \\
+0 & \text{(interior)}
+\end{cases}
+\\
+g\rho_{0} \eta + \int^{0}_{-z}\rho^{'} dz & = & p^{'}
+\end{eqnarray}
+
+\noindent where $u=\frac{Dx}{Dt}=r \cos(\phi)\frac{D \lambda}{Dt}$ and 
+$v=\frac{Dy}{Dt}=r \frac{D \phi}{Dt}$ 
+are the zonal and meridional components of the
+flow vector, $\vec{u}$, on the sphere. As described in
+MITgcm Numerical Solution Procedure \ref{chap:discretization}, the time 
+evolution of potential temperature, $\theta$, equation is solved prognostically.
+The total pressure, $p$, is diagnosed by summing pressure due to surface 
+elevation $\eta$ and the hydrostatic pressure.
+\\
 
 \subsubsection{Numerical Stability Criteria}
 \label{www:tutorials}
 
-
-\subsection{Code Configuration}
+The Laplacian dissipation coefficient, $A_{h}$, is set to $5 \times 10^5 m s^{-1}$.
+This value is chosen to yield a Munk layer width \cite{adcroft:95},
+\begin{eqnarray}
+\label{EQ:eg-hs-munk_layer}
+M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}}
+\end{eqnarray}
+
+\noindent  of $\approx 600$km. This is greater than the model
+resolution in low-latitudes, $\Delta x \approx 400{\rm km}$, ensuring that the frictional 
+boundary layer is adequately resolved.
+\\
+
+\noindent The model is stepped forward with a 
+time step $\delta t_{\theta}=30~{\rm hours}$ for thermodynamic variables and
+$\delta t_{v}=40~{\rm minutes}$ for momentum terms. With this time step, the stability 
+parameter to the horizontal Laplacian friction \cite{adcroft:95}
+\begin{eqnarray}
+\label{EQ:eg-hs-laplacian_stability}
+S_{l} = 4 \frac{A_{h} \delta t_{v}}{{\Delta x}^2}
+\end{eqnarray}
+
+\noindent evaluates to 0.16 at a latitude of $\phi=80^{\circ}$, which is below the 
+0.3 upper limit for stability. The zonal grid spacing $\Delta x$ is smallest at
+$\phi=80^{\circ}$ where $\Delta x=r\cos(\phi)\Delta \phi\approx 77{\rm km}$.
+\\
+
+\noindent The vertical dissipation coefficient, $A_{z}$, is set to 
+$1\times10^{-3} {\rm m}^2{\rm s}^{-1}$. The associated stability limit
+\begin{eqnarray}
+\label{EQ:eg-hs-laplacian_stability_z}
+S_{l} = 4 \frac{A_{z} \delta t_{v}}{{\Delta z}^2}
+\end{eqnarray}
+
+\noindent evaluates to $0.015$ for the smallest model
+level spacing ($\Delta z_{1}=50{\rm m}$) which is again well below
+the upper stability limit.
+\\
+
+The values of the horizontal ($K_{h}$) and vertical ($K_{z}$) diffusion coefficients 
+for both temperature and salinity are set to $1 \times 10^{3}~{\rm m}^{2}{\rm s}^{-1}$ 
+and $3 \times 10^{-5}~{\rm m}^{2}{\rm s}^{-1}$ respectively. The stability limit 
+related to $K_{h}$ will be at $\phi=80^{\circ}$ where $\Delta x \approx 77 {\rm km}$. 
+Here the stability parameter 
+\begin{eqnarray} 
+\label{EQ:eg-hs-laplacian_stability_xtheta}
+S_{l} = \frac{4 K_{h} \delta t_{\theta}}{{\Delta x}^2} 
+\end{eqnarray}
+evaluates to $0.07$, well below the stability limit of $S_{l} \approx 0.5$. The 
+stability parameter related to $K_{z}$
+\begin{eqnarray} 
+\label{EQ:eg-hs-laplacian_stability_ztheta}
+S_{l} = \frac{4 K_{z} \delta t_{\theta}}{{\Delta z}^2} 
+\end{eqnarray}
+evaluates to $0.005$ for $\min(\Delta z)=50{\rm m}$, well below the stability limit 
+of $S_{l} \approx 0.5$.
+\\
+
+\noindent The numerical stability for inertial oscillations
+\cite{adcroft:95} 
+
+\begin{eqnarray}
+\label{EQ:eg-hs-inertial_stability}
+S_{i} = f^{2} {\delta t_v}^2
+\end{eqnarray}
+
+\noindent evaluates to $0.24$ for $f=2\omega\sin(80^{\circ})=1.43\times10^{-4}~{\rm s}^{-1}$, which is close to 
+the $S_{i} < 1$ upper limit for stability.
+\\
+
+\noindent The advective CFL \cite{adcroft:95} for a extreme maximum 
+horizontal flow
+speed of $ | \vec{u} | = 2 ms^{-1}$
+
+\begin{eqnarray}
+\label{EQ:eg-hs-cfl_stability}
+S_{a} = \frac{| \vec{u} | \delta t_{v}}{ \Delta x}
+\end{eqnarray}
+
+\noindent evaluates to $6 \times 10^{-2}$. This is well below the stability 
+limit of 0.5.
+\\
+
+\noindent The stability parameter for internal gravity waves propagating
+with a maximum speed of $c_{g}=10~{\rm ms}^{-1}$
+\cite{adcroft:95}
+
+\begin{eqnarray}
+\label{EQ:eg-hs-gfl_stability}
+S_{c} = \frac{c_{g} \delta t_{v}}{ \Delta x}
+\end{eqnarray}
+
+\noindent evaluates to $3 \times 10^{-1}$. This is close to the linear
+stability limit of 0.5.
+  
+\subsection{Experiment Configuration}
 \label{www:tutorials}
-\label{SEC:eg-baro-code_config}
+\label{SEC:eg-hs_examp_exp_config}
 
 The model configuration for this experiment resides under the 
-directory {\it verification/exp0/}.  The experiment files 
+directory {\it verification/hs94.128x64x5}.  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/windx.bin},
+\item {\it input/windy.bin},
+\item {\it input/salt.bin},
+\item {\it input/theta.bin},
+\item {\it input/SSS.bin},
+\item {\it input/SST.bin},
+\item {\it input/topog.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 
+contain the code customizations and parameter settings for these
 experiments. Below we describe the customizations
 to these files associated with this experiment.
 
@@ -78,74 +330,250 @@
 
 \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 15 and 16
-\begin{verbatim}
-rigidLid=.FALSE.,
-implicitFreeSurface=.TRUE.,
-\end{verbatim}
-these lines suppress the rigid lid formulation of the surface
-pressure inverter and activate the implicit free surface form
-of the pressure inverter.
+\item Lines 7-10 and 11-14 
+\begin{verbatim} tRef= 16.0 , 15.2 , 14.5 , 13.9 , 13.3 ,  \end{verbatim} 
+$\cdots$ \\
+set reference values for potential
+temperature and salinity at each model level in units of $^{\circ}$C and
+${\rm ppt}$. The entries are ordered from surface to depth.
+Density is calculated from anomalies at each level evaluated
+with respect to the reference values set here.\\
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R INI\_THETA}({\it ini\_theta.F})
+\end{minipage}
+}
+
+
+\item Line 15, 
+\begin{verbatim} viscAz=1.E-3, \end{verbatim}
+this line sets the vertical Laplacian dissipation coefficient to
+$1 \times 10^{-3} {\rm m^{2}s^{-1}}$. Boundary conditions
+for this operator are specified later. This variable is copied into
+model general vertical coordinate variable {\bf viscAr}.
+
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R CALC\_DIFFUSIVITY}({\it calc\_diffusivity.F})
+\end{minipage}
+}
+
+\item Line 16, 
+\begin{verbatim}
+viscAh=5.E5,
+\end{verbatim} 
+this line sets the horizontal Laplacian frictional dissipation coefficient to
+$5 \times 10^{5} {\rm m^{2}s^{-1}}$. Boundary conditions
+for this operator are specified later.
+
+\item Lines 17,
+\begin{verbatim}
+no_slip_sides=.FALSE.
+\end{verbatim}
+this line selects a free-slip lateral boundary condition for
+the horizontal Laplacian friction operator 
+e.g. $\frac{\partial u}{\partial y}$=0 along boundaries in $y$ and
+$\frac{\partial v}{\partial x}$=0 along boundaries in $x$.
+
+\item Lines 9,
+\begin{verbatim}
+no_slip_bottom=.TRUE.
+\end{verbatim}
+this line selects a no-slip boundary condition for bottom
+boundary condition in the vertical Laplacian friction operator 
+e.g. $u=v=0$ at $z=-H$, where $H$ is the local depth of the domain.
+
+\item Line 19,
+\begin{verbatim}
+diffKhT=1.E3,
+\end{verbatim}
+this line sets the horizontal diffusion coefficient for temperature
+to $1000\,{\rm m^{2}s^{-1}}$. The boundary condition on this
+operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
+all boundaries.
+
+\item Line 20,
+\begin{verbatim}
+diffKzT=3.E-5,
+\end{verbatim}
+this line sets the vertical diffusion coefficient for temperature
+to $3 \times 10^{-5}\,{\rm m^{2}s^{-1}}$. The boundary 
+condition on this operator is $\frac{\partial}{\partial z}=0$ at both
+the upper and lower boundaries.
+
+\item Line 21,
+\begin{verbatim}
+diffKhS=1.E3,
+\end{verbatim}
+this line sets the horizontal diffusion coefficient for salinity
+to $1000\,{\rm m^{2}s^{-1}}$. The boundary condition on this
+operator is $\frac{\partial}{\partial x}=\frac{\partial}{\partial y}=0$ on
+all boundaries.
+
+\item Line 22,
+\begin{verbatim}
+diffKzS=3.E-5,
+\end{verbatim}
+this line sets the vertical diffusion coefficient for salinity
+to $3 \times 10^{-5}\,{\rm m^{2}s^{-1}}$. The boundary 
+condition on this operator is $\frac{\partial}{\partial z}=0$ at both
+the upper and lower boundaries.
+
+\item Lines 23-26
+\begin{verbatim}
+beta=1.E-11,
+\end{verbatim}
+\vspace{-5mm}$\cdots$\\
+These settings do not apply for this experiment.
 
 \item Line 27,
 \begin{verbatim}
-startTime=0,
+gravity=9.81,
 \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.
+Sets the gravitational acceleration coefficient to $9.81{\rm m}{\rm s}^{-1}$.\\
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R CALC\_PHI\_HYD}~({\it calc\_phi\_hyd.F})\\
+{\it S/R INI\_CG2D}~({\it ini\_cg2d.F})\\
+{\it S/R INI\_CG3D}~({\it ini\_cg3d.F})\\
+{\it S/R INI\_PARMS}~({\it ini\_parms.F})\\
+{\it S/R SOLVE\_FOR\_PRESSURE}~({\it solve\_for\_pressure.F})
+\end{minipage}
+}
+
 
-\item Line 29,
+\item Line 28-29,
 \begin{verbatim}
-endTime=12000,
+rigidLid=.FALSE., 
+implicitFreeSurface=.TRUE., 
 \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.
+Selects the barotropic pressure equation to be the implicit free surface
+formulation.
 
 \item Line 30,
 \begin{verbatim}
-deltaTmom=1200,
+eosType='POLY3',
 \end{verbatim}
-This line sets the momentum equation timestep to $1200s$.
+Selects the third order polynomial form of the equation of state.\\
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R FIND\_RHO}~({\it find\_rho.F})\\
+{\it S/R FIND\_ALPHA}~({\it find\_alpha.F})
+\end{minipage}
+}
 
-\item Line 39,
+\item Line 31,
 \begin{verbatim}
-usingCartesianGrid=.TRUE.,
+readBinaryPrec=32,
 \end{verbatim}
-This line requests that the simulation be performed in a 
-Cartesian coordinate system.
+Sets format for reading binary input datasets holding model fields to
+use 32-bit representation for floating-point numbers.\\
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R READ\_WRITE\_FLD}~({\it read\_write\_fld.F})\\
+{\it S/R READ\_WRITE\_REC}~({\it read\_write\_rec.F})
+\end{minipage}
+}
 
-\item Line 41,
+\item Line 36,
 \begin{verbatim}
-delX=60*20E3,
+cg2dMaxIters=1000,
 \end{verbatim}
-This line sets the horizontal 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).
+Sets maximum number of iterations the two-dimensional, conjugate
+gradient solver will use, {\bf irrespective of convergence 
+criteria being met}.\\
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R CG2D}~({\it cg2d.F})
+\end{minipage}
+}
+
+\item Line 37,
+\begin{verbatim}
+cg2dTargetResidual=1.E-13,
+\end{verbatim}
+Sets the tolerance which the two-dimensional, conjugate
+gradient solver will use to test for convergence in equation 
+\ref{EQ:eg-hs-congrad_2d_resid} to $1 \times 10^{-13}$.
+Solver will iterate until 
+tolerance falls below this value or until the maximum number of
+solver iterations is reached.\\
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R CG2D}~({\it cg2d.F})
+\end{minipage}
+}
 
 \item Line 42,
 \begin{verbatim}
-delY=60*20E3,
+startTime=0,
 \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).
+Sets the starting time for the model internal time counter.
+When set to non-zero this option implicitly requests a 
+checkpoint file be read for initial state.
+By default the checkpoint file is named according to
+the integer number of time steps in the {\bf startTime} value.
+The internal time counter works in seconds.
 
 \item Line 43,
 \begin{verbatim}
-delZ=5000,
+endTime=2808000.,
 \end{verbatim}
-This line sets the vertical grid spacing between each z-coordinate line
-in the discrete grid to $5000m$ ($5$~km).
+Sets the time (in seconds) at which this simulation will terminate.
+At the end of a simulation a checkpoint file is automatically
+written so that a numerical experiment can consist of multiple
+stages.
+
+\item Line 44,
+\begin{verbatim}
+#endTime=62208000000,
+\end{verbatim}
+A commented out setting for endTime for a 2000 year simulation.
+
+\item Line 45,
+\begin{verbatim}
+deltaTmom=2400.0,
+\end{verbatim}
+Sets the timestep $\delta t_{v}$ used in the momentum equations to
+$20~{\rm mins}$.
+See section \ref{SEC:mom_time_stepping}.
+
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R TIMESTEP}({\it timestep.F})
+\end{minipage}
+}
 
 \item Line 46,
 \begin{verbatim}
+tauCD=321428.,
+\end{verbatim}
+Sets the D-grid to C-grid coupling time scale $\tau_{CD}$ used in the momentum equations.
+See section \ref{SEC:cd_scheme}.
+
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R INI\_PARMS}({\it ini\_parms.F})\\
+{\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F})
+\end{minipage}
+}
+
+\item Line 47,
+\begin{verbatim}
+deltaTtracer=108000.,
+\end{verbatim}
+Sets the default timestep, $\delta t_{\theta}$, for tracer equations to
+$30~{\rm hours}$.
+See section \ref{SEC:tracer_time_stepping}.
+
+\fbox{
+\begin{minipage}{5.0in}
+{\it S/R TIMESTEP\_TRACER}({\it timestep\_tracer.F})
+\end{minipage}
+}
+
+\item Line 47,
+\begin{verbatim}
 bathyFile='topog.box'
 \end{verbatim}
 This line specifies the name of the file from which the domain
@@ -156,12 +584,12 @@
 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
+of $-2000m$ indicates open ocean. The matlab program
 {\it input/gendata.m} shows an example of how to generate a
 bathymetry file.
 
 
-\item Line 49,
+\item Line 50,
 \begin{verbatim}
 zonalWindFile='windx.sin_y'
 \end{verbatim}
@@ -169,7 +597,9 @@
 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.  
+code to generate a valid 
+{\bf zonalWindFile} 
+file.  
 
 \end{itemize}
 
@@ -177,21 +607,21 @@
 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/climatalogical_ogcm/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.
+customisations 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.
+customisations for this experiment.
 
 \subsubsection{File {\it input/windx.sin\_y}}
 \label{www:tutorials}
@@ -210,7 +640,7 @@
 
 The {\it input/topog.box} 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
+$0m$ or $-2000\,{\rm m}$, corresponding respectively to a wall or to deep
 ocean. 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
@@ -233,22 +663,40 @@
 the lateral domain extent in grid points for the
 axis aligned with the y-coordinate.
 
+\item Line 49, 
+\begin{verbatim} Nr=4,   \end{verbatim} this line sets
+the vertical domain extent in grid points.
+
 \end{itemize}
 
 \begin{small}
-\input{part3/case_studies/barotropic_gyre/code/SIZE.h}
+\input{part3/case_studies/climatalogical_ogcm/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.
+customisations 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.
+customisations for this experiment.
+
+\subsubsection{Other Files }
+\label{www:tutorials}
 
+Other files relevant to this experiment are
+\begin{itemize}
+\item {\it model/src/ini\_cori.F}. This file initializes the model
+coriolis variables {\bf fCorU}.
+\item {\it model/src/ini\_spherical\_polar\_grid.F}
+\item {\it model/src/ini\_parms.F},
+\item {\it input/windx.sin\_y},
+\end{itemize}
+contain the code customisations and parameter settings for this 
+experiments. Below we describe the customisations
+to these files associated with this experiment.
