--- manual/s_examples/baroclinic_gyre/fourlayer.tex	2003/09/15 19:39:04	1.16
+++ manual/s_examples/baroclinic_gyre/fourlayer.tex	2010/08/30 23:09:19	1.28
@@ -1,9 +1,15 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/baroclinic_gyre/fourlayer.tex,v 1.16 2003/09/15 19:39:04 edhill Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/baroclinic_gyre/fourlayer.tex,v 1.28 2010/08/30 23:09:19 jmc Exp $
 % $Name:  $
 
-\section{Four Layer Baroclinic Ocean Gyre In Spherical Coordinates}
-\label{www:tutorials}
-\label{sect:eg-fourlayer}
+\section[Baroclinic Gyre MITgcm Example]{Four Layer Baroclinic Ocean Gyre In Spherical Coordinates}
+%\label{www:tutorials}
+\label{sec:eg-fourlayer}
+\begin{rawhtml}
+<!-- CMIREDIR:eg-fourlayer: -->
+\end{rawhtml}
+\begin{center}
+(in directory: {\it verification/tutorial\_baroclinic\_gyre/})
+\end{center}
 
 \bodytext{bgcolor="#FFFFFFFF"}
 
@@ -18,16 +24,12 @@
 %\end{center}
 
 This document describes an example experiment using MITgcm
-to simulate a baroclinic ocean gyre in spherical
-polar coordinates. The barotropic
-example experiment in section \ref{sect:eg-baro}
-illustrated how to configure the code for a single layer 
-simulation in a Cartesian grid. In this example a similar physical problem
-is simulated, but the code is now configured
-for four layers and in a spherical polar coordinate system.
+to simulate a baroclinic ocean gyre for four layers in spherical
+polar coordinates.  The files for this experiment can be found
+in the verification directory under tutorial\_baroclinic\_gyre.
 
 \subsection{Overview}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 This example experiment demonstrates using the MITgcm to simulate
 a baroclinic, wind-forced, ocean gyre circulation. The experiment 
@@ -45,7 +47,7 @@
 according to latitude, $\varphi$
 
 \begin{equation}
-\label{EQ:eg-fourlayer-fcori}
+\label{eq:eg-fourlayer-fcori}
 f(\varphi) = 2 \Omega \sin( \varphi )
 \end{equation}
  
@@ -55,7 +57,7 @@
  The sinusoidal wind-stress variations are defined according to 
 
 \begin{equation}
-\label{EQ:taux}
+\label{eq:taux}
 \tau_{\lambda}(\varphi) = \tau_{0}\sin(\pi \frac{\varphi}{L_{\varphi}})
 \end{equation}
  
@@ -63,9 +65,9 @@
 $\tau_0$ is set to $0.1N m^{-2}$. 
 \\
 
-Figure \ref{FIG:eg-fourlayer-simulation_config}
+Figure \ref{fig:eg-fourlayer-simulation_config}
 summarizes the configuration simulated.
-In contrast to the example in section \ref{sect:eg-baro}, the 
+In contrast to the example in section \ref{sec:eg-baro}, the 
 current experiment simulates a spherical polar domain. As indicated
 by the axes in the lower left of the figure the model code works internally
 in a locally orthogonal coordinate $(x,y,z)$. For this experiment description 
@@ -84,14 +86,14 @@
 linear
 
 \begin{equation}
-\label{EQ:eg-fourlayer-linear1_eos}
+\label{eq:eg-fourlayer-linear1_eos}
 \rho = \rho_{0} ( 1 - \alpha_{\theta}\theta^{'} )
 \end{equation}
 
 \noindent which is implemented in the model as a density anomaly equation
 
 \begin{equation}
-\label{EQ:eg-fourlayer-linear1_eos_pert}
+\label{eq:eg-fourlayer-linear1_eos_pert}
 \rho^{'} = -\rho_{0}\alpha_{\theta}\theta^{'}
 \end{equation}
 
@@ -104,11 +106,15 @@
 the quantity that is carried in the model core equations.
 
 \begin{figure}
-\begin{center}
- \resizebox{7.5in}{5.5in}{
-   \includegraphics*[0.2in,0.7in][10.5in,10.5in]
-   {part3/case_studies/fourlayer_gyre/simulation_config.eps} }
-\end{center}
+%% \begin{center}
+%%  \resizebox{7.5in}{5.5in}{
+%%    \includegraphics*[0.2in,0.7in][10.5in,10.5in]
+%%    {s_examples/baroclinic_gyre/simulation_config.eps} }
+%% \end{center}
+\centerline{
+  \scalefig{.95}
+  \epsfbox{s_examples/baroclinic_gyre/simulation_config.eps}
+}
 \caption{Schematic of simulation domain and wind-stress forcing function 
 for the four-layer gyre numerical experiment. The domain is enclosed by solid
 walls at $0^{\circ}$~E, $60^{\circ}$~E, $0^{\circ}$~N and $60^{\circ}$~N.
@@ -116,13 +122,13 @@
 imposed by setting the potential temperature, $\theta$, in each layer.
 The vertical spacing, $\Delta z$, is constant and equal to $500$m.
 }
-\label{FIG:eg-fourlayer-simulation_config}
+\label{fig:eg-fourlayer-simulation_config}
 \end{figure}
 
 \subsection{Equations solved}
-\label{www:tutorials}
+%\label{www:tutorials}
 For this problem
-the implicit free surface, {\bf HPE} (see section \ref{sect:hydrostatic_and_quasi-hydrostatic_forms}) form of the 
+the implicit free surface, {\bf HPE} (see section \ref{sec:hydrostatic_and_quasi-hydrostatic_forms}) form of the 
 equations described in Marshall et. al \cite{marshall:97a} are
 employed. The flow is three-dimensional with just temperature, $\theta$, as 
 an active tracer.  The equation of state is linear.
@@ -131,12 +137,12 @@
 temperature equation. A wind-stress momentum forcing 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:eg_fourl_code_config} ). This yields an active set of equations
+\ref{sec:eg_fourl_code_config} ). This yields an active set of equations
 solved in this configuration, written in spherical polar coordinates as 
 follows
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-model_equations}
+\label{eq:eg-fourlayer-model_equations}
 \frac{Du}{Dt} - fv + 
   \frac{1}{\rho}\frac{\partial p^{\prime}}{\partial \lambda} - 
   A_{h}\nabla_{h}^2u - A_{z}\frac{\partial^{2}u}{\partial z^{2}} 
@@ -175,11 +181,11 @@
 flow vector $\vec{u}$ on the sphere ($u=\dot{\lambda},v=\dot{\varphi}$).
 The terms $H\widehat{u}$ and $H\widehat{v}$ are the components of the vertical
 integral term given in equation \ref{eq:free-surface} and
-explained in more detail in section \ref{sect:pressure-method-linear-backward}.
+explained in more detail in section \ref{sec:pressure-method-linear-backward}.
 However, for the problem presented here, the continuity relation (equation
 \ref{eq:fourl_example_continuity}) differs from the general form given
-in section \ref{sect:pressure-method-linear-backward},
-equation \ref{eq:linear-free-surface=P-E+R}, because the source terms
+in section \ref{sec:pressure-method-linear-backward},
+equation \ref{eq:linear-free-surface=P-E}, because the source terms
 ${\cal P}-{\cal E}+{\cal R}$ 
 are all $0$.
 
@@ -197,7 +203,7 @@
 lateral and vertical boundary conditions for the $\nabla_{h}^{2}$
 and $\frac{\partial^{2}}{\partial z^{2}}$ operators are specified
 when the numerical simulation is run - see section 
-\ref{SEC:eg_fourl_code_config}. For temperature
+\ref{sec:eg_fourl_code_config}. For temperature
 the boundary condition is ``zero-flux'' 
 e.g. $\frac{\partial \theta}{\partial \varphi}=
 \frac{\partial \theta}{\partial \lambda}=\frac{\partial \theta}{\partial z}=0$.
@@ -205,7 +211,7 @@
 
 
 \subsection{Discrete Numerical Configuration}
-\label{www:tutorials}
+%\label{www:tutorials}
 
  The domain is discretised with 
 a uniform grid spacing in latitude and longitude
@@ -225,7 +231,7 @@
 
 The procedure for generating a set of internal grid variables from a
 spherical polar grid specification is discussed in section 
-\ref{sect:spatial_discrete_horizontal_grid}.
+\ref{sec:spatial_discrete_horizontal_grid}.
 
 \noindent\fbox{ \begin{minipage}{5.5in}
 {\em S/R INI\_SPHERICAL\_POLAR\_GRID} ({\em
@@ -246,32 +252,32 @@
 
 
 
-As described in \ref{sect:tracer_equations}, the time evolution of potential 
+As described in \ref{sec:tracer_equations}, the time evolution of potential 
 temperature, 
 $\theta$, (equation \ref{eq:eg_fourl_theta})
 is evaluated prognostically. The centered second-order scheme with
 Adams-Bashforth time stepping described in section 
-\ref{sect:tracer_equations_abII} is used to step forward the temperature 
+\ref{sec:tracer_equations_abII} is used to step forward the temperature 
 equation. Prognostic terms in
 the momentum equations are solved using flux form as
-described in section \ref{sect:flux-form_momentum_eqautions}.
+described in section \ref{sec:flux-form_momentum_equations}.
 The pressure forces that drive the fluid motions, (
 $\frac{\partial p^{'}}{\partial \lambda}$ and $\frac{\partial p^{'}}{\partial \varphi}$), are found by summing pressure due to surface 
 elevation $\eta$ and the hydrostatic pressure. The hydrostatic part of the 
 pressure is diagnosed explicitly by integrating density. The sea-surface
 height, $\eta$, is diagnosed using an implicit scheme. The pressure
 field solution method is described in sections
-\ref{sect:pressure-method-linear-backward} and 
-\ref{sect:finding_the_pressure_field}.
+\ref{sec:pressure-method-linear-backward} and 
+\ref{sec:finding_the_pressure_field}.
 
 \subsubsection{Numerical Stability Criteria}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 The Laplacian viscosity coefficient, $A_{h}$, is set to $400 m s^{-1}$.
 This value is chosen to yield a Munk layer width,
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-munk_layer}
+\label{eq:eg-fourlayer-munk_layer}
 M_{w} = \pi ( \frac { A_{h} }{ \beta } )^{\frac{1}{3}}
 \end{eqnarray}
 
@@ -287,7 +293,7 @@
 parameter to the horizontal Laplacian friction
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-laplacian_stability}
+\label{eq:eg-fourlayer-laplacian_stability}
 S_{l} = 4 \frac{A_{h} \delta t}{{\Delta x}^2}
 \end{eqnarray}
 
@@ -299,7 +305,7 @@
 $1\times10^{-2} {\rm m}^2{\rm s}^{-1}$. The associated stability limit
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-laplacian_stability_z}
+\label{eq:eg-fourlayer-laplacian_stability_z}
 S_{l} = 4 \frac{A_{z} \delta t}{{\Delta z}^2}
 \end{eqnarray}
 
@@ -312,7 +318,7 @@
 \noindent The numerical stability for inertial oscillations
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-inertial_stability}
+\label{eq:eg-fourlayer-inertial_stability}
 S_{i} = f^{2} {\delta t}^2
 \end{eqnarray}
 
@@ -325,7 +331,7 @@
 speed of $ | \vec{u} | = 2 ms^{-1}$
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-cfl_stability}
+\label{eq:eg-fourlayer-cfl_stability}
 C_{a} = \frac{| \vec{u} | \delta t}{ \Delta x}
 \end{eqnarray}
 
@@ -337,7 +343,7 @@
 propagating at $2~{\rm m}~{\rm s}^{-1}$ 
 
 \begin{eqnarray}
-\label{EQ:eg-fourlayer-igw_stability}
+\label{eq:eg-fourlayer-igw_stability}
 S_{c} = \frac{c_{g} \delta t}{ \Delta x}
 \end{eqnarray}
 
@@ -345,11 +351,12 @@
 stability limit of 0.25.
   
 \subsection{Code Configuration}
-\label{www:tutorials}
-\label{SEC:eg_fourl_code_config}
+%\label{www:tutorials}
+\label{sec:eg_fourl_code_config}
 
 The model configuration for this experiment resides under the 
-directory {\it verification/exp2/}.  The experiment files 
+directory {\it verification/tutorial\_barotropic\_gyre/}.
+The experiment files 
 \begin{itemize}
 \item {\it input/data}
 \item {\it input/data.pkg}
@@ -365,7 +372,7 @@
 associated with this experiment.
 
 \subsubsection{File {\it input/data}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 This file, reproduced completely below, specifies the main parameters 
 for the experiment. The parameters that are significant for this configuration
@@ -376,7 +383,7 @@
 \item Line 4, 
 \begin{verbatim} tRef=20.,10.,8.,6., \end{verbatim} 
 this line sets the initial and reference values of potential
-temperature at each model level in units of $^{\circ}$C.  The entries
+temperature at each model level in units of $^{\circ}\mathrm{C}$.  The entries
 are ordered from surface to depth. For each depth level the initial
 and reference profiles will be uniform in $x$ and $y$. The values
 specified here are read into the variable \varlink{tRef}{tRef} in the
@@ -414,18 +421,12 @@
   coefficient to $1 \times 10^{-2} {\rm m^{2}s^{-1}}$. Boundary
   conditions for this operator are specified later.  The variable
   \varlink{viscAh}{viscAh} is read in the routine
-  \varlink{INI\_PARMS}{INI_PARMS} and applied in routines
-  \varlink{CALC\_MOM\_RHS}{CALC_MOM_RHS} and
-  \varlink{CALC\_GW}{CALC_GW}.
+  \varlink{INI\_PARMS}{INI_PARMS} and applied in routine
+  \varlink{MOM\_FLUXFORM}{MOM_FLUXFORM}.
 
 \fbox{
   \begin{minipage}{5.0in}
-    {\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F})
-  \end{minipage}
-}
-\fbox{
-  \begin{minipage}{5.0in}
-    {\it S/R CALC\_GW}({\it calc\_gw.F})
+    {\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F})
   \end{minipage}
 }
 
@@ -443,10 +444,10 @@
 
   \fbox{
     \begin{minipage}{5.0in}
-      {\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F})
+      {\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F})
     \end{minipage}
   }
-  \filelink{calc\_mom\_rhs.F}{calc_mom_rhs.F}
+  \filelink{mom\_fluxform.F}{pkg-mom_fluxform-mom_fluxform.F}
   
 \item Lines 9,
 \begin{verbatim}
@@ -457,14 +458,14 @@
   at $z=-H$, where $H$ is the local depth of the domain.  The variable
   \varlink{no\_slip\_bottom}{no\_slip\_bottom} is read in the routine
   \filelink{INI\_PARMS}{model-src-ini_parms.F} and is applied in the
-  routine \varlink{CALC\_MOM\_RHS}{CALC_MOM_RHS}.
+  routine \varlink{MOM\_FLUXFORM}{MOM_FLUXFORM}.
 
   \fbox{
     \begin{minipage}{5.0in}
-      {\it S/R CALC\_MOM\_RHS}({\it calc\_mom\_rhs.F})
+      {\it S/R MOM\_FLUXFORM}({\it mom\_fluxform.F})
     \end{minipage}
   }
-  \filelink{calc\_mom\_rhs.F}{calc_mom_rhs.F}
+  \filelink{mom\_fluxform.F}{pkg-mom_fluxform-mom_fluxform.F}
 
 \item Line 10,
 \begin{verbatim}
@@ -558,7 +559,7 @@
 
 \item Line 41,
 \begin{verbatim}
-phiMin=0.,
+ygOrigin=0.,
 \end{verbatim}
   This line sets the southern boundary of the modeled domain to
   $0^{\circ}$ latitude. This value affects both the generation of the
@@ -566,7 +567,7 @@
   the initialization of the coriolis force.  Note - it is not required
   to set a longitude boundary, since the absolute longitude does not
   alter the kernel equation discretisation.  The variable
-  \varlink{phiMin}{phiMin} is read in the
+  \varlink{ygOrigin}{ygOrigin} is read in the
   routine \varlink{INI\_PARMS}{INI_PARMS} and is used in routine
 
   \fbox{
@@ -678,24 +679,24 @@
 
 \begin{rawhtml}<PRE>\end{rawhtml}
 \begin{small}
-\input{part3/case_studies/fourlayer_gyre/input/data}
+\input{s_examples/baroclinic_gyre/input/data}
 \end{small}
 \begin{rawhtml}</PRE>\end{rawhtml}
 
 \subsubsection{File {\it input/data.pkg}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 This file uses standard default values and does not contain
 customisations for this experiment.
 
 \subsubsection{File {\it input/eedata}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 This file uses standard default values and does not contain
 customisations for this experiment.
 
 \subsubsection{File {\it input/windx.sin\_y}}
-\label{www:tutorials}
+%\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}$
@@ -708,7 +709,7 @@
   input/windx.sin\_y} file.
 
 \subsubsection{File {\it input/topog.box}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 
 The {\it input/topog.box} file specifies a two-dimensional ($x,y$) 
@@ -720,7 +721,7 @@
 code for creating the {\it input/topog.box} file.
 
 \subsubsection{File {\it code/SIZE.h}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 Two lines are customized in this file for the current experiment
 
@@ -743,24 +744,24 @@
 \end{itemize}
 
 \begin{small}
-\include{part3/case_studies/fourlayer_gyre/code/SIZE.h}
+\include{s_examples/baroclinic_gyre/code/SIZE.h}
 \end{small}
 
 \subsubsection{File {\it code/CPP\_OPTIONS.h}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 This file uses standard default values and does not contain
 customisations for this experiment.
 
 
 \subsubsection{File {\it code/CPP\_EEOPTIONS.h}}
-\label{www:tutorials}
+%\label{www:tutorials}
 
 This file uses standard default values and does not contain
 customisations for this experiment.
 
 \subsubsection{Other Files }
-\label{www:tutorials}
+%\label{www:tutorials}
 
 Other files relevant to this experiment are
 \begin{itemize}
@@ -773,18 +774,18 @@
 \end{itemize}
 
 \subsection{Running The Example}
-\label{www:tutorials}
-\label{SEC:running_the_example}
+%\label{www:tutorials}
+%\label{sec:running_the_example}
 
 \subsubsection{Code Download}
-\label{www:tutorials}
+%\label{www:tutorials}
 
  In order to run the examples you must first download the code distribution.
 Instructions for downloading the code can be found in section
-\ref{sect:obtainingCode}.
+\ref{sec:obtainingCode}.
 
 \subsubsection{Experiment Location}
-\label{www:tutorials}
+%\label{www:tutorials}
 
  This example experiments is located under the release sub-directory
 
@@ -792,7 +793,7 @@
 {\it verification/exp2/ }
 
 \subsubsection{Running the Experiment}
-\label{www:tutorials}
+%\label{www:tutorials}
 
  To run the experiment