--- manual/s_examples/text/model_examples.tex 2002/12/17 14:39:53 1.3 +++ manual/s_examples/text/model_examples.tex 2006/06/27 19:08:22 1.11 @@ -1,22 +1,191 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/text/model_examples.tex,v 1.3 2002/12/17 14:39:53 mlosch Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_examples/text/model_examples.tex,v 1.11 2006/06/27 19:08:22 molod Exp $ % $Name: $ -\section{Tutorials} -\label{sect:tutorials} -\label{www:tutorials} - -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[MITgcm Example Experiments]{Example experiments} +\label{sect:modelExamples} +\begin{rawhtml} + +\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} - 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{hs94.cs-32x32x5} - 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{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\_yz} 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}. + +\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 @@ -29,7 +198,7 @@ \input{part3/case_studies/ogcm_in_pressure/ogcm_in_pressure.tex} \newpage -\input{part3/case_studies/hs_atmosphere/hs_atmos.tex} +\input{part3/case_studies/held_suarez_cs/held_suarez_cs.tex} \newpage \input{part3/case_studies/doubly_periodic_convection/convection.tex} @@ -39,3 +208,18 @@ \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} + +\newpage +\input{part3/case_studies/sens_airsea_tracer/doc_ad_examples.tex} + +\newpage +\input{part3/case_studies/offline/offline_tutorial.tex} + +\newpage +\input{part3/case_studies/rotating_tank/tank.tex}