s_examples/text/model_examples.tex

% $Header: /u/gcmpack/manual/s_examples/text/model_examples.tex,v 1.22 2010/08/27 18:21:43 jmc Exp $
% $Name:  $

\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.

\end{itemize}

Once you have chosen the example you want to run, you are ready to
compile the code.

1	jmc	1.23	% $Header: /u/gcmpack/manual/s_examples/text/model_examples.tex,v 1.22 2010/08/27 18:21:43 jmc Exp $
2	adcroft	1.1	% $Name: $
3
4	molod	1.11	\section[MITgcm Example Experiments]{Example experiments}
5	jmc	1.23	\label{sec:modelExamples}
6	molod	1.11	\begin{rawhtml}
7			<!-- CMIREDIR:modelExamples: -->
8			\end{rawhtml}
9
10			%% a set of pre-configured numerical experiments
11
12	edhill	1.13	The full MITgcm distribution comes with a set of pre-configured
13			numerical experiments. Some of these example experiments are tests of
14			individual parts of the model code, but many are fully fledged
15			numerical simulations. Full tutorials exist for a few of the examples,
16	jmc	1.23	and are documented in sections \ref{sec:eg-baro} -
17			\ref{sec:eg-tank}. The other examples follow the same general
18	edhill	1.13	structure as the tutorial examples. However, they only include brief
19			instructions in a text file called {\it README}. The examples are
20			located in subdirectories under the directory \texttt{verification}.
21			Each example is briefly described below.
22	molod	1.11
23			\subsection{Full list of model examples}
24
25			\begin{enumerate}
26
27	jmc	1.20	\item \texttt{tutorial\_advection\_in\_gyre} - Test of various
28	jahn	1.15	advection schemes in a single-layer double-gyre experiment.
29			This experiment is described in detail in section
30	jmc	1.23	\ref{sec:eg-adv-gyre}.
31	molod	1.12
32	jmc	1.17	\item \texttt{tutorial\_baroclinic\_gyre} - Four layer, ocean double
33			gyre. This experiment is described in detail in section
34	jmc	1.23	\ref{sec:eg-fourlayer}.
35	jmc	1.17
36	jmc	1.20	\item \texttt{tutorial\_barotropic\_gyre} - Single layer, ocean double
37	jmc	1.19	gyre (barotropic with free-surface).
38	jmc	1.23	This experiment is described in detail in section \ref{sec:eg-baro}.
39	edhill	1.13
40	jmc	1.20	\item \texttt{tutorial\_cfc\_offline} - Offline form of the MITgcm to
41	jmc	1.17	study advection of a passive tracer and CFCs.
42	jmc	1.23	This experiment is described in detail in section \ref{sec:eg-offline-cfc}.
43	jmc	1.17
44			\item \texttt{tutorial\_deep\_convection} - Inhomogenously forced
45			ocean convection in a doubly periodic box. This experiment is
46	jmc	1.23	described in detail in section \ref{sec:eg-bconv}.
47	jmc	1.17
48	jmc	1.20	\item \texttt{tutorial\_global\_oce\_biogeo} - Ocean model coupled to
49	jmc	1.17	the dissolved inorganic carbon biogeochemistry model. This
50			experiment is described in detail in section
51	jmc	1.23	\ref{sec:eg-biogeochem_tutorial}.
52	jmc	1.17
53	jmc	1.20	\item \texttt{tutorial\_global\_oce\_in\_p} - Global ocean simulation in
54	jmc	1.17	pressure coordinate (non-Boussinesq ocean model). Described in
55	jmc	1.23	detail in section \ref{sec:eg-globalpressure}.
56	edhill	1.13
57			\item \texttt{tutorial\_global\_oce\_latlon} - 4x4 degree global ocean
58			simulation with steady climatological forcing. This experiment is
59	jmc	1.23	described in detail in section \ref{sec:eg-global}.
60	edhill	1.13
61	jmc	1.20	\item \texttt{tutorial\_global\_oce\_optim} - Global ocean state
62	jmc	1.17	estimation at $4^\circ$ resolution. This experiment is described in
63	jmc	1.23	detail in section \ref{sec:eg-global_state_estimate}.
64	molod	1.11
65	edhill	1.13	\item \texttt{tutorial\_held\_suarez\_cs} - 3D atmosphere dynamics
66	jmc	1.19	using Held and Suarez (1994) forcing on cubed sphere grid. This
67	jmc	1.23	experiment is described in detail in section \ref{sec:eg-hs}.
68	molod	1.11
69	jmc	1.20	\item \texttt{tutorial\_offline} - Offline form of the MITgcm to study
70	jmc	1.17	advection of a passive tracer. This experiment is described in
71	jmc	1.23	detail in section \ref{sec:eg-offline}.
72	jmc	1.17
73	jmc	1.20	\item \texttt{tutorial\_plume\_on\_slope} - Gravity Plume on a
74	jmc	1.17	continental slope. This experiment is described in detail in
75	jmc	1.23	section \ref{sec:eg-gravityplume}.
76	jmc	1.17
77	jmc	1.20	\item \texttt{tutorial\_tracer\_adjsens} - Simple passive tracer
78	jmc	1.17	experiment. Includes derivative calculation. This experiment is
79	jmc	1.23	described in detail in section \ref{sec:eg-simple-tracer-adjoint}.
80	molod	1.12
81	jmc	1.20	\item \texttt{adjustment.128x64x1} - Barotropic adjustment problem on
82	molod	1.11	latitude longitude grid with 128x64 grid points ($2.8^\circ$ resolution).
83
84	jmc	1.20	\item \texttt{adjustment.cs-32x32x1} - Barotropic adjustment problem on
85	molod	1.11	cube sphere grid with 32x32 points per face (roughly $2.8^\circ$
86	jmc	1.20	resolution).\\
87			Also contains a non-linear free-surface adjustment version ({\it input.nlfs/}).
88	molod	1.11
89			\item \texttt{advect\_cs} Two-dimensional passive advection test on
90	jmc	1.17	cube sphere grid (32x32 grid points per face, roughly $2.8^\circ$)
91	molod	1.11
92	jmc	1.20	\item \texttt{advect\_xy} - Two-dimensional (horizontal plane) passive
93	jmc	1.19	advection test on Cartesian grid.\\
94	jmc	1.20	Also contains an additional set-up using Adams-Bashforth 3 ({\it input.ab3\_c4/}).
95	molod	1.11
96	jmc	1.20	\item \texttt{advect\_xz} - Two-dimensional (vertical plane) passive
97	molod	1.11	advection test on Cartesian grid.
98
99	jmc	1.17	\item \texttt{aim.5l\_Equatorial\_Channel}
100			- 5-levels Intermediate Atmospheric physics,
101			3D Equatorial Channel configuration.
102
103			\item \texttt{aim.5l\_LatLon} - 5-levels Intermediate Atmospheric physics,
104			Global configuration, on latitude longitude grid with 128x64x5 grid
105			points ($2.8^\circ$ resolution).
106	molod	1.11
107	jmc	1.17	\item \texttt{aim.5l\_cs} - 5-levels Intermediate Atmospheric physics,
108			Global configuration on cube sphere grid
109	jmc	1.19	(32x32 grid points per face, roughly $2.8^\circ$).\\
110			Also contains an additional set-up with an ocean mixed layer and thermodynamics
111	jmc	1.20	sea-ice ({\it input.thSI/}).
112	jmc	1.19
113	jmc	1.20	\item \texttt{bottom\_ctrl\_5x5} - Adjoint test using the bottom
114	edhill	1.13	topography as the control parameter.
115	molod	1.12
116	jmc	1.20	\item \texttt{cfc\_example} - Global ocean with online computation and
117	edhill	1.13	advection of CFC11 and CFC12.
118	molod	1.12
119	jmc	1.20	\item \texttt{cpl\_aim+ocn} - Coupled Ocean - Atmosphere realistic
120			configuration on cubed-sphere cs32 horizontal grid,
121			using Intermediate Atmospheric physics ({\it pkg/aim\_v23})
122			thermodynamics seaice ({\it pkg/thsice}) and land packages.
123			on cubed-sphere cs32 in a realistics configuration.
124
125			\item \texttt{cpl\_atm2d+ocn} - Coupled Ocean - Atmosphere realistic
126			configuration using 2-D Atmospheric Model ({\it pkg/atm2d}).
127
128			\item \texttt{deep\_anelastic} - Convection simulation on a giant planet:
129			relax both the Boussinesq approximation (anelastic) and the thin atmosphere
130			approximation (deep atmosphere).
131	jmc	1.19
132	jmc	1.20	\item \texttt{dome} - Idealized 3D test of a density-driven bottom current.
133	jmc	1.19
134	jmc	1.20	\item \texttt{exp2} - Old version of the global ocean experiment (no GM,
135	jmc	1.19	no partial-cells).\\
136	jmc	1.20	Also contains an additional set-up with ridid-lid ({\it input.rigidLid/}).
137	molod	1.12
138	jmc	1.17	\item \texttt{exp4} - Flow over a Gaussian bump in open-water or
139			channel with open boundaries.
140
141	jmc	1.20	\item \texttt{exp5} - Deep convection.
142	molod	1.12
143	jmc	1.20	\item \texttt{fizhi-cs-32x32x40} - Global atmospheric simulation with
144			realistic topography, 40 vertical levels, a cubed sphere grid and
145	edhill	1.13	the full atmospheric physics package.
146
147	jmc	1.20	\item \texttt{fizhi-cs-aqualev20} - Global atmospheric simulation on an
148	edhill	1.13	aqua planet with full atmospheric physics. Run is perpetual march
149			with an analytical SST distribution. This is the configuration for
150			the APE (Aqua Planet Experiment) participation experiment.
151
152	jmc	1.20	\item \texttt{fizhi-gridalt-hs} - Global atmospheric simulation
153	edhill	1.13	Held-Suarez (1994) forcing, with the physical forcing and the
154			dynamical forcing running on different vertical grids.
155
156	jmc	1.20	\item \texttt{flt\_example} - Example of using float package.
157	jmc	1.17
158			\item \texttt{front\_relax} - Relaxation of an ocean thermal front
159	jmc	1.20	(test for Gent/McWilliams scheme). 2D (Y-Z).\\
160			Also contains an additional set-up with Mixed-Layer Eddy parameterization
161			(Ferrari \& McWilliams, 2007) ({\it input.mxl/}).
162	jmc	1.17
163	jmc	1.20	\item \texttt{global1x1\_tot} - ECCO-GODAE production configuration
164	jmc	1.19	version 1, 2 \& 3
165
166	jmc	1.20	\item \texttt{global2x2\_tot} - ECCO production configuration version 0
167	jmc	1.19
168			\item \texttt{global\_ocean.90x40x15} Global ocean simulation at 4x4
169			degree resolution. Similar to tutorial\_global\_oce\_latlon, with
170			quasi-non-hydrostatics and non-hydrostatic metric terms.\\
171	jmc	1.20	Also contains an adjoint set-up ({\it code\_ad/, input\_ad/}).
172	jmc	1.17
173	jmc	1.20	\item \texttt{global\_ocean.cs32x15} - Global ocean experiment on the
174	jmc	1.19	cubed sphere grid.\\
175			Also contains additional set-ups:
176			\begin{enumerate}
177	jmc	1.20	\item non-hydrostratic with biharmonic viscosity ({\it input.viscA4/})
178			\item using thermodynamic sea ice and bulk force ({\it input.thsice/})
179			\item using thermodynamic ({\it pkg/thsice}) dynamics ({\it pkg/seaice}) sea-ice
180			and EXF package ({\it input.icedyn/})
181	jmc	1.19	\end{enumerate}
182	edhill	1.13
183	jmc	1.20	\item \texttt{global\_ocean\_ebm} - Global ocean experiment on a lat-lon
184	edhill	1.13	grid coupled to an atmospheric energy balance model. Similar to
185	jmc	1.20	global\_ocean.90x40x15 experiment.\\
186			Also contains an adjoint set-up ({\it code\_ad/, input\_ad/}).
187	molod	1.12
188	jmc	1.20	\item \texttt{global\_with\_exf} - Global ocean experiment on a lat-lon
189	edhill	1.13	grid using the exf package. Similar to global\_ocean.90x40x15
190			experiment.
191	molod	1.12
192	jmc	1.19	\item \texttt{hs94.128x64x5} - 3D atmosphere dynamics on lat-lon grid,
193			using Held and Suarez '94 forcing.
194	jmc	1.17
195	jmc	1.19	\item \texttt{hs94.1x64x5} - Zonal averaged atmosphere dynamics
196	jmc	1.20	using Held and Suarez '94 forcing.\\
197			Also contains an adjoint set-up ({\it code\_ad/, input\_ad/}).
198	jmc	1.17
199	jmc	1.20	\item \texttt{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
200			Suarez (1994) forcing on the cubed sphere. 5 vertical levels.\\
201			Also contains an additional set-up with Implicit Internal gravity waves
202			treatment ({\it input.impIGW/}).
203	molod	1.12
204	jmc	1.20	\item \texttt{ideal\_2D\_oce} - Idealized 2D global ocean simulation on
205	edhill	1.13	an aqua planet.
206	molod	1.12
207	jmc	1.17	\item \texttt{internal\_wave} - Ocean internal wave forced by open
208			boundary conditions.
209
210	jmc	1.20	\item \texttt{inverted\_barometer} - Simple test of ocean response to
211	edhill	1.13	atmospheric pressure loading.
212	molod	1.12
213	jmc	1.20	\item \texttt{isomip} - ISOMIP like set-up including ice-shelf cavities
214			({\it pkg/shelfice}).\\
215			Also contains an additional set-up with ({\it input.htd/})
216			but only Martin knows what "htd" stands for.
217	jmc	1.19
218	jmc	1.20	\item \texttt{lab\_sea} - Regional Labrador Sea simulation on a lat-lon
219			grid using the sea ice package.\\
220			Also contains additional set-ups:
221			\begin{enumerate}
222			\item using the LSR solver (instead of EVP dynamics) ({\it input.lsr/})
223			\item using Hibler and Bryan (1987) sea-ice ocean stress ({\it input.hb87/})
224			\item using package {\it salt\_plume} ({\it input.salt\_plume/})
225			\end{enumerate}
226			and also 3 adjoint set-ups ({\it code\_ad/, input\_ad/, input\_ad.noseaicedyn/,
227			input\_ad.noseaice/}).
228	molod	1.12
229	jmc	1.20	\item \texttt{matrix\_example} - Test of experimental method to
230	edhill	1.13	accelerated convergence towards equillibrium.
231	molod	1.12
232	jmc	1.20	\item \texttt{MLAdjust} - Simple tests for different viscosity formulations.\\
233			Also contains additional set-ups:
234			\begin{enumerate}
235			\item ({\it input.0.leith/})
236			\item ({\it input.0.leithD/})
237			\item ({\it input.0.smag/})
238			\item ({\it input.1.leith/})
239			\end{enumerate}
240	jmc	1.17
241			\item \texttt{natl\_box} - Eastern subtropical North Atlantic with KPP
242			scheme; 1 month integration
243	jmc	1.19
244	jmc	1.20	\item \texttt{natl\_box\_adjoint} - Eastern subtropical North Atlantic with KPP
245			scheme; adjoint set-up.
246	jmc	1.19
247	jmc	1.20	\item \texttt{offline\_exf\_seaice} - oceanic surface forcing computed
248			by bulk-formulae ({\it pkg/exf}) and inposed SST (offline ocean).\\
249			Also contains additional set-ups:
250			\begin{enumerate}
251			\item with sea-ice ({\it pkg/seaice}) thermodynamics ({\it input.seaicetd/})
252			\item an adjoint test ({\it code\_ad/, input\_ad/}).
253			\end{enumerate}
254	jmc	1.17
255	jmc	1.20	\item \texttt{OpenAD} simple Adjoint experiement (used also to test
256			open-AD compiler)
257	jmc	1.19
258	jmc	1.17	\item \texttt{rotating\_tank} Rotating tank simulation in cylindrical
259			coordinates. This experiment is described in detail in section
260	jmc	1.23	\ref{sec:eg-tank}.
261	jmc	1.17
262	jmc	1.20	\item \texttt{seaice\_obcs} similar to "lab\_sea" ({\it input.salt\_plume/})
263			experiment with only a fraction of the domain and open-boundary conditions
264			derived from "lab\_sea" experiment.
265	jmc	1.19
266	jmc	1.17	\item \texttt{solid-body.cs-32x32x1} Solid body rotation test for cube
267			sphere grid.
268	molod	1.12
269	jmc	1.20	\item \texttt{tidal\_basin\_2d} 2-D vertical section (X-Z) with tidal forcing
270	jmc	1.19
271	edhill	1.13	\item \texttt{vermix} Simple test in a small domain (3 columns) for
272	jmc	1.20	ocean vertical mixing schemes. The standard set-up ({\it input/}) uses
273			KPP scheme.\\
274			Also contains additional set-ups:
275			\begin{enumerate}
276			\item with Gaspar et al. (1990) ({\it pkg/ggl90}) scheme ({\it input.ggl90/})
277			\item with Mellor \& Yamada (1982) level 2. ({\it pkg/my82}) scheme ({\it input.my82/})
278			\item with Paluszkiewicz \& Romea (1997) ({\it pkg/opps}) scheme ({\it input.opps/})
279			\item with Pacanowski \& Philander (1981) ({\it pkg/pp81}) scheme ({\it input.pp81/})
280			\end{enumerate}
281	molod	1.12
282	molod	1.11	\end{enumerate}
283
284			\subsection{Directory structure of model examples}
285
286			Each example directory has the following subdirectories:
287
288			\begin{itemize}
289			\item \texttt{code}: contains the code particular to the example. At a
290			minimum, this directory includes the following files:
291
292			\begin{itemize}
293			\item \texttt{code/packages.conf}: declares the list of packages or
294			package groups to be used. If not included, the default version
295			is located in \texttt{pkg/pkg\_default}. Package groups are
296			simply convenient collections of commonly used packages which are
297			defined in \texttt{pkg/pkg\_default}. Some packages may require
298			other packages or may require their absence (that is, they are
299			incompatible) and these package dependencies are listed in
300			\texttt{pkg/pkg\_depend}.
301
302			\item \texttt{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to
303			the ``execution environment'' part of the code. The default
304			version is located in \texttt{eesupp/inc}.
305
306			\item \texttt{code/CPP\_OPTIONS.h}: declares CPP keys relative to
307			the ``numerical model'' part of the code. The default version is
308			located in \texttt{model/inc}.
309
310			\item \texttt{code/SIZE.h}: declares size of underlying
311			computational grid. The default version is located in
312			\texttt{model/inc}.
313			\end{itemize}
314
315			In addition, other include files and subroutines might be present in
316			\texttt{code} depending on the particular experiment. See Section 2
317			for more details.
318
319			\item \texttt{input}: contains the input data files required to run
320			the example. At a minimum, the \texttt{input} directory contains the
321			following files:
322
323			\begin{itemize}
324			\item \texttt{input/data}: this file, written as a namelist,
325			specifies the main parameters for the experiment.
326
327			\item \texttt{input/data.pkg}: contains parameters relative to the
328			packages used in the experiment.
329
330			\item \texttt{input/eedata}: this file contains ``execution
331			environment'' data. At present, this consists of a specification
332			of the number of threads to use in $X$ and $Y$ under multithreaded
333			execution.
334			\end{itemize}
335
336			In addition, you will also find in this directory the forcing and
337			topography files as well as the files describing the initial state
338			of the experiment. This varies from experiment to experiment. See
339	molod	1.14	the verification directories refered to in this chapter for more details.
340	molod	1.11
341			\item \texttt{results}: this directory contains the output file
342			\texttt{output.txt} produced by the simulation example. This file is
343			useful for comparison with your own output when you run the
344			experiment.
345	molod	1.14
346			\item \texttt{build}: this directory is where the model is compiled
347			and loaded, and where the executable resides.
348
349	molod	1.11	\end{itemize}
350
351			Once you have chosen the example you want to run, you are ready to
352			compile the code.
353