--- manual/s_examples/text/model_examples.tex	2006/04/04 20:23:08	1.10
+++ manual/s_examples/text/model_examples.tex	2006/06/27 20:47:05	1.12
@@ -1,6 +1,247 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/text/model_examples.tex,v 1.10 2006/04/04 20:23:08 molod Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/text/model_examples.tex,v 1.12 2006/06/27 20:47:05 molod Exp $
 % $Name:  $
 
+\section[MITgcm Example Experiments]{Example experiments}
+\label{sect:modelExamples}
+\begin{rawhtml}
+<!-- CMIREDIR:modelExamples: -->
+\end{rawhtml}
+
+%% a set of pre-configured numerical experiments
+
+The full MITgcm distribution comes with a set of pre-configured numerical experiments. 
+Some of these example experiments are tests of individual parts of the model code, but many
+are fully fledged numerical simulations. Full tutorials exist for a few of the examples,
+and are documented in sections \ref{sect:eg-baro} - \ref{sect:eg-tank}. The other examples 
+follow the same general structure as the tutorial examples. However, they only include brief
+instructions in a text file called {\it README}.  The examples are located in subdirectories 
+under the directory \texttt{verification}.  Each example is briefly described below.
+
+\subsection{Full list of model examples}
+
+\begin{enumerate}
+  
+\item \texttt{tutorial\_barotropic\_gyre}
+
+\item \texttt{tutorial\_barotropic\_gyre} - single layer, ocean double gyre 
+  (barotropic with free-surface). This experiment is described in detail in section
+  \ref{sect:eg-baro}.
+
+\item \texttt{tutorial\_baroclinic\_gyre} - Four layer, ocean double gyre. This experiment
+  is described in detail in section \ref{sect:eg-fourlayer}.
+
+\item \texttt{tutorial\_global\_oce\_latlon} - 4x4 degree global ocean simulation with steady
+  climatological forcing. This experiment is described in detail in section \ref{sect:eg-global}.
+
+\item \texttt{exp4} - Flow over a Gaussian bump in open-water or channel with open boundaries.
+  
+\item \texttt{tutorial\_deep\_convection} - Inhomogenously forced ocean convection in a
+  doubly periodic box. This experiment is described in detail in section \ref{sect:eg-bconv}.
+
+\item \texttt{front\_relax} - Relaxation of an ocean thermal front (test for
+Gent/McWilliams scheme). 2D (Y-Z).
+
+\item \texttt{internal\_wave} - Ocean internal wave forced by open
+  boundary conditions.
+  
+\item \texttt{natl\_box} - Eastern subtropical North Atlantic with KPP
+  scheme; 1 month integration
+  
+\item \texttt{hs94.1x64x5} - Zonal averaged atmosphere using Held and
+  Suarez '94 forcing.
+  
+\item \texttt{hs94.128x64x5} - 3D atmosphere dynamics using Held and
+  Suarez '94 forcing.
+  
+\item \texttt{tutorial\_held\_suarez\_cs} - 3D atmosphere dynamics using Held and Suarez 
+  (1994) forcing on the cubed sphere.  This experiment is described in detail in
+  section \ref{sect:eg-hs}.
+  
+\item \texttt{aim.5l\_zon-ave} - Intermediate Atmospheric physics.
+  Global Zonal Mean configuration, 1x64x5 resolution.
+  
+\item \texttt{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate
+  Atmospheric physics, equatorial Slice configuration.  2D (X-Z).
+  
+\item \texttt{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
+  physics. 3D Equatorial Channel configuration.
+  
+\item \texttt{aim.5l\_LatLon} - Intermediate Atmospheric physics.
+  Global configuration, on latitude longitude grid with 128x64x5 grid
+  points ($2.8^\circ$ resolution).
+  
+\item \texttt{aim.5l_cs}
+
+\item \texttt{adjustment.128x64x1} Barotropic adjustment problem on
+  latitude longitude grid with 128x64 grid points ($2.8^\circ$ resolution).
+  
+\item \texttt{adjustment.cs-32x32x1} Barotropic adjustment problem on
+  cube sphere grid with 32x32 points per face (roughly $2.8^\circ$
+  resolution).
+  
+\item \texttt{advect\_cs} Two-dimensional passive advection test on
+  cube sphere grid.
+  
+\item \texttt{advect\_xy} Two-dimensional (horizontal plane) passive
+  advection test on Cartesian grid.
+  
+\item \texttt{advect\_xz} Two-dimensional (vertical plane) passive
+  advection test on Cartesian grid.
+  
+\item \texttt{tutorial\_tracer\_adjsens} Simple passive tracer experiment. Includes
+  derivative calculation. This experiment is described in detail in section
+  \ref{sect:eg-simple-tracer}.
+
+\item \texttt{flt\_example} Example of using float package.
+  
+\item \texttt{global\_ocean.90x40x15} Global circulation with GM, flux
+  boundary conditions and poles.
+
+\item \texttt{tutorial\_global\_oce\_in\_p} Global circulation in pressure
+  coordinate (non-Boussinesq ocean model). Described in detail in
+  section \ref{sect:eg-globalpressure}.
+
+\item \texttt{solid-body.cs-32x32x1} Solid body rotation test for cube
+  sphere grid.
+
+\item \texttt{tutorial\_plume\_on\_slope} Gravity Plume on a continental slope.
+  This experiment is described in detail in section \ref{sect:eg-gravityplume}.
+
+\item \texttt{tutorial\_global\_oce\_biogeo} Ocean model coupled to the dissolved 
+  inorganic carbon biogeochemistry model. This experiment is described in detail in section
+  \ref{sect:eg-biogeochem\_tutorial}.
+
+\item \texttt{tutorial\_global\_oce\_optim} Global ocean state estimation at $4^\circ$ resolution.
+  This experiment is described in detail in section \ref{sect:eg-global\_state\_estimate}.
+
+\item \texttt{tutorial\_offline} Offline form of the MITgcm to study advection of a passive 
+  tracer.  This experiment is described in detail in section \ref{sect:eg-offline}.
+
+\item \texttt{rotating\_tank} Rotating tank simulation in cylindrical coordinates.
+  This experiment is described in detail in section \ref{sect:eg-tank}.
+
+\item \texttt{MLAdjust} Simple test for different viscosity formulations.
+
+\item \texttt{bottom_ctrl_5x5} Adjoint test using the bottom topography as the
+  control parameter.
+
+\item \texttt{cfc_example} Global ocean with online computation and advection of
+CFC11 and CFC12.
+
+\item \texttt{dome} Idealized 3D test of a density-driven bottom current.
+
+\item \texttt{exp2} Old version of the global ocean experiment.
+
+\item \texttt{exp5} Deep convection.
+
+\item \texttt{fizhi-cs-32x32x10} Global atmospheric simulation with realistic topography,
+  10 vertical levels, a cubed sphere grid and the full atmospheric physics package.
+
+\item \texttt{fizhi-cs-aqualev20} Global atmospheric simulation on an aqua planet with
+  full atmospheric physics. Run is perpetual march with an analytical SST distribution.
+  This is the configuration for the APE (Aqua Planet Experiment) participation experiment.
+
+\item \texttt{fizhi-gridalt-hs} Global atmospheric simulation Held-Suarez (1994) forcing,
+  with the physical forcing and the dynamical forcing running on different vertical grids.
+
+\item \texttt{global_ocean.cs32x15} Global ocean experiment on the cubed sphere grid, using
+thermodynamic sea ice and bulk force packages.
+
+\item \texttt{global_ocean_ebm} Global ocean experiment on a lat-lon grid coupled to an
+atmospheric energy balance model. Similar to global_ocean.90x40x15 experiment.
+
+\item \texttt{global_with_exf} Global ocean experiment on a lat-lon grid using the exf
+package. Similar to global_ocean.90x40x15 experiment.
+
+\item \texttt{hs94.cs-32x32x5} 3D atmosphere dynamics using Held and Suarez
+  (1994) forcing on the cubed sphere. 5 vertical levels.
+
+\item \texttt{ideal_2D_oce} Idealized 2D global ocean simulation on an aqua planet.
+
+\item \texttt{inverted_barometer} Simple test of ocean response to atmospheric pressure
+loading.
+
+\item \texttt{lab_sea} Regional Labrador Sea simulation on a lat-lon grid. Coupled to
+the sea ice model.
+
+\item \texttt{matrix_example} Test of experimental method to accelerated convergence towards
+equillibrium.
+
+\item \texttt{tutorial_cfc_offline} Offline form of the MITgcm to study advection of a passive
+  tracer and CFCs.
+
+\item \texttt{vermix} Simple test in a small domain (3 columns) for ocean vertical mixing schemes.
+
+\end{enumerate}
+
+\subsection{Directory structure of model examples}
+
+Each example directory has the following subdirectories:
+
+\begin{itemize}
+\item \texttt{code}: contains the code particular to the example. At a
+  minimum, this directory includes the following files:
+
+  \begin{itemize}
+  \item \texttt{code/packages.conf}: declares the list of packages or
+    package groups to be used.  If not included, the default version
+    is located in \texttt{pkg/pkg\_default}.  Package groups are
+    simply convenient collections of commonly used packages which are
+    defined in \texttt{pkg/pkg\_default}.  Some packages may require
+    other packages or may require their absence (that is, they are
+    incompatible) and these package dependencies are listed in
+    \texttt{pkg/pkg\_depend}.
+
+  \item \texttt{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to
+    the ``execution environment'' part of the code. The default
+    version is located in \texttt{eesupp/inc}.
+  
+  \item \texttt{code/CPP\_OPTIONS.h}: declares CPP keys relative to
+    the ``numerical model'' part of the code. The default version is
+    located in \texttt{model/inc}.
+  
+  \item \texttt{code/SIZE.h}: declares size of underlying
+    computational grid.  The default version is located in
+    \texttt{model/inc}.
+  \end{itemize}
+  
+  In addition, other include files and subroutines might be present in
+  \texttt{code} depending on the particular experiment. See Section 2
+  for more details.
+  
+\item \texttt{input}: contains the input data files required to run
+  the example. At a minimum, the \texttt{input} directory contains the
+  following files:
+
+  \begin{itemize}
+  \item \texttt{input/data}: this file, written as a namelist,
+    specifies the main parameters for the experiment.
+  
+  \item \texttt{input/data.pkg}: contains parameters relative to the
+    packages used in the experiment.
+  
+  \item \texttt{input/eedata}: this file contains ``execution
+    environment'' data. At present, this consists of a specification
+    of the number of threads to use in $X$ and $Y$ under multithreaded
+    execution.
+  \end{itemize}
+  
+  In addition, you will also find in this directory the forcing and
+  topography files as well as the files describing the initial state
+  of the experiment.  This varies from experiment to experiment. See
+  section 2 for more details.
+
+\item \texttt{results}: this directory contains the output file
+  \texttt{output.txt} produced by the simulation example. This file is
+  useful for comparison with your own output when you run the
+  experiment.
+\end{itemize}
+
+Once you have chosen the example you want to run, you are ready to
+compile the code.
+
+
+\newpage
 \input{part3/case_studies/barotropic_gyre/baro.tex}
 
 \newpage
@@ -31,9 +272,10 @@
 \input{part3/case_studies/global_oce_estimation/global_oce_estimation.tex}
 
 \newpage
+\input{part3/case_studies/sens_airsea_tracer/doc_ad_examples.tex}
+
+\newpage
 \input{part3/case_studies/offline/offline_tutorial.tex}
 
-\begin{versionprivate}
 \newpage
 \input{part3/case_studies/rotating_tank/tank.tex}
-\end{versionprivate}