--- manual/s_examples/text/model_examples.tex	2005/08/02 19:16:58	1.7
+++ manual/s_examples/text/model_examples.tex	2010/08/30 23:09:20	1.23
@@ -1,41 +1,353 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/text/model_examples.tex,v 1.7 2005/08/02 19:16:58 dfer Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/text/model_examples.tex,v 1.23 2010/08/30 23:09:20 jmc Exp $
 % $Name:  $
 
-\section{Tutorials}
-\label{sect:tutorials}
-\label{www:tutorials}
+\section[MITgcm Example Experiments]{Example experiments}
+\label{sec: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{sec:eg-baro} -
+\ref{sec: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\_advection\_in\_gyre} - Test of various
+  advection schemes in a single-layer double-gyre experiment.
+  This experiment is described in detail in section
+  \ref{sec:eg-adv-gyre}.
+
+\item \texttt{tutorial\_baroclinic\_gyre} - Four layer, ocean double
+  gyre. This experiment is described in detail in section
+  \ref{sec:eg-fourlayer}.
+
+\item \texttt{tutorial\_barotropic\_gyre} - Single layer, ocean double
+  gyre (barotropic with free-surface). 
+  This experiment is described in detail in section \ref{sec:eg-baro}.
+
+\item \texttt{tutorial\_cfc\_offline} - Offline form of the MITgcm to
+  study advection of a passive tracer and CFCs.
+  This experiment is described in detail in section \ref{sec:eg-offline-cfc}.
+
+\item \texttt{tutorial\_deep\_convection} - Inhomogenously forced
+  ocean convection in a doubly periodic box. This experiment is
+  described in detail in section \ref{sec:eg-bconv}.
+
+\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{sec:eg-biogeochem_tutorial}.
+
+\item \texttt{tutorial\_global\_oce\_in\_p} - Global ocean simulation in
+  pressure coordinate (non-Boussinesq ocean model). Described in
+  detail in section \ref{sec:eg-globalpressure}.
+
+\item \texttt{tutorial\_global\_oce\_latlon} - 4x4 degree global ocean
+  simulation with steady climatological forcing. This experiment is
+  described in detail in section \ref{sec:eg-global}.
+
+\item \texttt{tutorial\_global\_oce\_optim} - Global ocean state
+  estimation at $4^\circ$ resolution.  This experiment is described in
+  detail in section \ref{sec:eg-global_state_estimate}.
+
+\item \texttt{tutorial\_held\_suarez\_cs} - 3D atmosphere dynamics
+  using Held and Suarez (1994) forcing on cubed sphere grid.  This
+  experiment is described in detail in section \ref{sec:eg-hs}.
+  
+\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{sec:eg-offline}.
+
+\item \texttt{tutorial\_plume\_on\_slope} - Gravity Plume on a
+  continental slope.  This experiment is described in detail in
+  section \ref{sec:eg-gravityplume}.
+
+\item \texttt{tutorial\_tracer\_adjsens} - Simple passive tracer
+  experiment. Includes derivative calculation. This experiment is
+  described in detail in section \ref{sec:eg-simple-tracer-adjoint}.
+
+\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).\\
+  Also contains a non-linear free-surface adjustment version ({\it input.nlfs/}).
+  
+\item \texttt{advect\_cs} Two-dimensional passive advection test on
+  cube sphere grid (32x32 grid points per face, roughly $2.8^\circ$)
+  
+\item \texttt{advect\_xy} - Two-dimensional (horizontal plane) passive
+  advection test on Cartesian grid.\\
+  Also contains an additional set-up using Adams-Bashforth 3 ({\it input.ab3\_c4/}).
+  
+\item \texttt{advect\_xz} - Two-dimensional (vertical plane) passive
+  advection test on Cartesian grid.
+  
+\item \texttt{aim.5l\_Equatorial\_Channel}
+  - 5-levels Intermediate Atmospheric physics, 
+  3D Equatorial Channel configuration.
+  
+\item \texttt{aim.5l\_LatLon} - 5-levels Intermediate Atmospheric physics,
+  Global configuration, on latitude longitude grid with 128x64x5 grid
+  points ($2.8^\circ$ resolution).
+  
+\item \texttt{aim.5l\_cs} - 5-levels Intermediate Atmospheric physics,
+  Global configuration on cube sphere grid 
+  (32x32 grid points per face, roughly $2.8^\circ$).\\
+  Also contains an additional set-up with an ocean mixed layer and thermodynamics
+  sea-ice ({\it input.thSI/}).
+
+\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{cpl\_aim+ocn} - Coupled Ocean - Atmosphere realistic 
+  configuration on cubed-sphere cs32 horizontal grid, 
+  using Intermediate Atmospheric physics ({\it pkg/aim\_v23})
+  thermodynamics seaice ({\it pkg/thsice}) and land packages.
+  on cubed-sphere cs32 in a realistics configuration.
+
+\item \texttt{cpl\_atm2d+ocn} - Coupled Ocean - Atmosphere realistic 
+  configuration using 2-D Atmospheric Model ({\it pkg/atm2d}).
+
+\item \texttt{deep\_anelastic} - Convection simulation on a giant planet:
+  relax both the Boussinesq approximation (anelastic) and the thin atmosphere
+  approximation (deep atmosphere).
+
+\item \texttt{dome} - Idealized 3D test of a density-driven bottom current.
+
+\item \texttt{exp2} - Old version of the global ocean experiment (no GM, 
+      no partial-cells).\\
+  Also contains an additional set-up with ridid-lid ({\it input.rigidLid/}).
+
+\item \texttt{exp4} - Flow over a Gaussian bump in open-water or
+  channel with open boundaries.
+  
+\item \texttt{exp5} - Deep convection.
+
+\item \texttt{fizhi-cs-32x32x40} - Global atmospheric simulation with
+  realistic topography, 40 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{flt\_example} - Example of using float package.
+  
+\item \texttt{front\_relax} - Relaxation of an ocean thermal front
+  (test for Gent/McWilliams scheme). 2D (Y-Z).\\
+  Also contains an additional set-up with Mixed-Layer Eddy parameterization
+  (Ferrari \& McWilliams, 2007) ({\it input.mxl/}).
+
+\item \texttt{global1x1\_tot} - ECCO-GODAE production configuration
+ version 1, 2 \& 3
+
+\item \texttt{global2x2\_tot} - ECCO production configuration version 0
+
+\item \texttt{global\_ocean.90x40x15} Global ocean simulation at 4x4 
+  degree resolution. Similar to tutorial\_global\_oce\_latlon, with
+  quasi-non-hydrostatics and non-hydrostatic metric terms.\\
+  Also contains an adjoint set-up ({\it code\_ad/, input\_ad/}).
+
+\item \texttt{global\_ocean.cs32x15} - Global ocean experiment on the
+  cubed sphere grid.\\ 
+  Also contains additional set-ups:
+  \begin{enumerate}
+   \item non-hydrostratic with biharmonic viscosity ({\it input.viscA4/})
+   \item using thermodynamic sea ice and bulk force ({\it input.thsice/})
+   \item using thermodynamic ({\it pkg/thsice}) dynamics ({\it pkg/seaice}) sea-ice
+         and EXF package ({\it input.icedyn/})
+  \end{enumerate}
+
+\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.\\
+  Also contains an adjoint set-up ({\it code\_ad/, input\_ad/}).
+
+\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.128x64x5} - 3D atmosphere dynamics on lat-lon grid,
+  using Held and Suarez '94 forcing.
+  
+\item \texttt{hs94.1x64x5} - Zonal averaged atmosphere dynamics 
+  using Held and Suarez '94 forcing.\\
+  Also contains an adjoint set-up ({\it code\_ad/, input\_ad/}).
+  
+\item \texttt{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
+  Suarez (1994) forcing on the cubed sphere. 5 vertical levels.\\
+  Also contains an additional set-up with Implicit Internal gravity waves
+  treatment ({\it input.impIGW/}).
+
+\item \texttt{ideal\_2D\_oce} - Idealized 2D global ocean simulation on
+  an aqua planet.
+
+\item \texttt{internal\_wave} - Ocean internal wave forced by open
+  boundary conditions.
+
+\item \texttt{inverted\_barometer} - Simple test of ocean response to
+  atmospheric pressure loading.
+
+\item \texttt{isomip} - ISOMIP like set-up including ice-shelf cavities
+  ({\it pkg/shelfice}).\\
+  Also contains an additional set-up with ({\it input.htd/})
+  but only Martin knows what "htd" stands for.
+
+\item \texttt{lab\_sea} - Regional Labrador Sea simulation on a lat-lon
+  grid using the sea ice package.\\
+  Also contains additional set-ups:
+  \begin{enumerate}
+   \item using the LSR solver (instead of EVP dynamics) ({\it input.lsr/})
+   \item using Hibler and Bryan (1987) sea-ice ocean stress ({\it input.hb87/})
+   \item using package {\it salt\_plume} ({\it input.salt\_plume/})
+  \end{enumerate}
+  and also 3 adjoint set-ups ({\it code\_ad/, input\_ad/, input\_ad.noseaicedyn/,
+  input\_ad.noseaice/}).
+
+\item \texttt{matrix\_example} - Test of experimental method to
+  accelerated convergence towards equillibrium.
+
+\item \texttt{MLAdjust} - Simple tests for different viscosity formulations.\\
+  Also contains additional set-ups:
+  \begin{enumerate}
+   \item ({\it input.0.leith/})
+   \item ({\it input.0.leithD/})
+   \item ({\it input.0.smag/})
+   \item ({\it input.1.leith/})
+  \end{enumerate}
+
+\item \texttt{natl\_box} - Eastern subtropical North Atlantic with KPP
+  scheme; 1 month integration
+
+\item \texttt{natl\_box\_adjoint} - Eastern subtropical North Atlantic with KPP
+  scheme; adjoint set-up.
+
+\item \texttt{offline\_exf\_seaice} - oceanic surface forcing computed
+  by bulk-formulae ({\it pkg/exf}) and inposed SST (offline ocean).\\
+  Also contains additional set-ups:
+  \begin{enumerate}
+   \item with sea-ice ({\it pkg/seaice}) thermodynamics ({\it input.seaicetd/})
+   \item an adjoint test ({\it code\_ad/, input\_ad/}).
+  \end{enumerate}
+  
+\item \texttt{OpenAD} simple Adjoint experiement (used also to test 
+  open-AD compiler)
+
+\item \texttt{rotating\_tank} Rotating tank simulation in cylindrical
+  coordinates.  This experiment is described in detail in section
+  \ref{sec:eg-tank}.
+
+\item \texttt{seaice\_obcs} similar to "lab\_sea" ({\it input.salt\_plume/})
+  experiment with only a fraction of the domain and open-boundary conditions
+  derived from "lab\_sea" experiment.
+
+\item \texttt{solid-body.cs-32x32x1} Solid body rotation test for cube
+  sphere grid.
+
+\item \texttt{tidal\_basin\_2d} 2-D vertical section (X-Z) with tidal forcing
+
+\item \texttt{vermix} Simple test in a small domain (3 columns) for
+  ocean vertical mixing schemes. The standard set-up ({\it input/}) uses
+  KPP scheme.\\
+  Also contains additional set-ups:
+  \begin{enumerate}
+   \item with Gaspar et al. (1990) ({\it pkg/ggl90}) scheme ({\it input.ggl90/})
+   \item with Mellor \& Yamada (1982) level 2. ({\it pkg/my82}) scheme ({\it input.my82/})
+   \item with Paluszkiewicz \& Romea (1997) ({\it pkg/opps}) scheme ({\it input.opps/})
+   \item with Pacanowski \& Philander (1981) ({\it pkg/pp81}) scheme ({\it input.pp81/})
+  \end{enumerate}
+
+\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
+  the verification directories refered to in this chapter 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.
 
+\item \texttt{build}: this directory is where the model is compiled
+  and loaded, and where the executable resides.
 
-\input{part3/case_studies/barotropic_gyre/baro.tex}
+\end{itemize}
 
-\newpage
-\input{part3/case_studies/fourlayer_gyre/fourlayer.tex}
+Once you have chosen the example you want to run, you are ready to
+compile the code.
 
-\newpage
-\input{part3/case_studies/climatalogical_ogcm/climatalogical_ogcm.tex}
-
-\newpage
-\input{part3/case_studies/ogcm_in_pressure/ogcm_in_pressure.tex}
-
-\newpage
-\input{part3/case_studies/hs_atmosphere/hs_atmos.tex}
-
-\newpage
-\input{part3/case_studies/doubly_periodic_convection/convection.tex}
-
-\newpage
-\input{part3/case_studies/plume_on_slope/plume_on_slope.tex}
-
-\newpage
-\input{part3/case_studies/carbon_outgassing_sensitivity/co2sens.tex}
-
-\newpage
-\input{part3/case_studies/biogeochem_tutorial/biogeochem.tex}
-
-\newpage
-\input{part3/case_studies/global_oce_estimation/global_oce_estimation.tex}
-
-\begin{versionprivate}
-\newpage
-\input{part3/case_studies/rotating_tank/tank.tex}
-\end{versionprivate}
