--- manual/s_getstarted/text/getting_started.tex 2001/10/15 19:36:09 1.5
+++ manual/s_getstarted/text/getting_started.tex 2001/11/13 20:13:54 1.10
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.5 2001/10/15 19:36:09 adcroft Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.10 2001/11/13 20:13:54 adcroft Exp $
% $Name: $
%\section{Getting started}
@@ -36,10 +36,37 @@
on the newsgroup. A users email list will be established at some time
in the future.
-
\section{Obtaining the code}
\label{sect:obtainingCode}
+MITgcm can be downloaded from our system by following
+the instructions below. As a courtesy we ask that you send e-mail to us at
+\begin{rawhtml} \end{rawhtml}
+support@mitgcm.org
+\begin{rawhtml} \end{rawhtml}
+to enable us to keep track of who's using the model and in what application.
+You can download the model two ways:
+
+\begin{enumerate}
+\item Using CVS software. CVS is a freely available source code management
+tool. To use CVS you need to have the software installed. Many systems
+come with CVS pre-installed, otherwise good places to look for
+the software for a particular platform are
+\begin{rawhtml} \end{rawhtml}
+cvshome.org
+\begin{rawhtml} \end{rawhtml}
+and
+\begin{rawhtml} \end{rawhtml}
+wincvs.org
+\begin{rawhtml} \end{rawhtml}
+.
+
+\item Using a tar file. This method is simple and does not
+require any special software. However, this method does not
+provide easy support for maintenance updates.
+
+\end{enumerate}
+
If CVS is available on your system, we strongly encourage you to use it. CVS
provides an efficient and elegant way of organizing your code and keeping
track of your changes. If CVS is not available on your machine, you can also
@@ -49,10 +76,15 @@
your .cshrc or .tcshrc:
\begin{verbatim}
% setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/u0/gcmpack
+\end{verbatim}
+
+To start using CVS, register with the MITgcm CVS server using command:
+\begin{verbatim}
% cvs login ( CVS password: cvsanon )
\end{verbatim}
+You only need to do ``cvs login'' once.
-You only need to do ``cvs login'' once. To obtain the source for the release:
+To obtain the sources for release1 type:
\begin{verbatim}
% cvs co -d directory -P -r release1 MITgcmUV
\end{verbatim}
@@ -61,24 +93,25 @@
exists this command updates your code based on the repository. Each
directory in the source tree contains a directory \textit{CVS}. This
information is required by CVS to keep track of your file versions with
-respect to the repository. Don't edit the files in \textit{CVS}! To obtain a
-different \textit{version} that is not the latest source:
-\begin{verbatim}
-% cvs co -d directory -P -r version MITgcm
-\end{verbatim}
-or the latest development version:
-\begin{verbatim}
-% cvs co -d directory -P MITgcm
-\end{verbatim}
+respect to the repository. Don't edit the files in \textit{CVS}!
+You can also use CVS to download code updates. More extensive
+information on using CVS for maintaining MITgcm code can be found
+\begin{rawhtml} \end{rawhtml}
+here
+\begin{rawhtml} \end{rawhtml}
+.
+
\paragraph*{Conventional download method}
\label{sect:conventionalDownload}
If you do not have CVS on your system, you can download the model as a
tar file from the reference web site at:
+\begin{rawhtml} \end{rawhtml}
\begin{verbatim}
http://mitgcm.org/download/
\end{verbatim}
+\begin{rawhtml} \end{rawhtml}
The tar file still contains CVS information which we urge you not to
delete; even if you do not use CVS yourself the information can help
us if you should need to send us your copy of the code.
@@ -106,7 +139,7 @@
\item \textit{diags}: contains the code relative to time-averaged
diagnostics. It is subdivided into two subdirectories \textit{inc} and
-\textit{src} that contain include files (*.\textit{h} files) and fortran
+\textit{src} that contain include files (*.\textit{h} files) and Fortran
subroutines (*.\textit{F} files), respectively.
\item \textit{doc}: contains brief documentation notes.
@@ -147,40 +180,47 @@
\section{Example experiments}
\label{sect:modelExamples}
-Now that you have successfully downloaded the model code we recommend that
-you first try to run the examples provided with the base version. You will
-probably want to run the example that is the closest to the configuration
-you will use eventually. The examples are located in subdirectories under
-the directory \textit{verification} and are briefly described below (a full
-description is given in section 2):
+The MITgcm distribution comes with a set of twenty-four pre-configured
+numerical experiments. Some of these examples experiments are tests of
+individual parts of the model code, but many are fully fledged numerical
+simulations. A few of the examples are used for tutorial documentation
+in sections \ref{sect:eg-baro} - \ref{sect:eg-global}. 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 \textit{verification}. Each
+example is briefly described below.
-\subsection{List of model examples}
+\subsection{Full list of model examples}
-\begin{itemize}
+\begin{enumerate}
\item \textit{exp0} - single layer, ocean double gyre (barotropic with
-free-surface).
+free-surface). This experiment is described in detail in section
+\ref{sect:eg-baro}.
-\item \textit{exp1} - 4 layers, ocean double gyre.
+\item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section
+\ref{sect:eg-baroc}.
\item \textit{exp2} - 4x4 degree global ocean simulation with steady
-climatological forcing.
+climatological forcing. This experiment is described in detail in section
+\ref{sect:eg-global}.
-\item \textit{exp4} - flow over a Gaussian bump in open-water or channel
+\item \textit{exp4} - Flow over a Gaussian bump in open-water or channel
with open boundaries.
-\item \textit{exp5} - inhomogenously forced ocean convection in a doubly
+\item \textit{exp5} - Inhomogenously forced ocean convection in a doubly
periodic box.
-\item \textit{front\_relax} - relaxation of an ocean thermal front (test for
+\item \textit{front\_relax} - Relaxation of an ocean thermal front (test for
Gent/McWilliams scheme). 2D (Y-Z).
-\item \textit{internal wave} - ocean internal wave forced by open boundary
+\item \textit{internal wave} - Ocean internal wave forced by open boundary
conditions.
-\item \textit{natl\_box} - eastern subtropical North Atlantic with KPP
+\item \textit{natl\_box} - Eastern subtropical North Atlantic with KPP
scheme; 1 month integration
-\item \textit{hs94.1x64x5} - zonal averaged atmosphere using Held and Suarez
+\item \textit{hs94.1x64x5} - Zonal averaged atmosphere using Held and Suarez
'94 forcing.
\item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez
@@ -189,24 +229,48 @@
\item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
Suarez '94 forcing on the cubed sphere.
-\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics, 5 layers
-Molteni physics package. Global Zonal Mean configuration, 1x64x5 resolution.
+\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. Global
+Zonal Mean configuration, 1x64x5 resolution.
\item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric
-physics, 5 layers Molteni physics package. Equatorial Slice configuration.
+physics, equatorial Slice configuration.
2D (X-Z).
\item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
-physics, 5 layers Molteni physics package. 3D Equatorial Channel
-configuration (not completely tested).
+physics. 3D Equatorial Channel configuration.
-\item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics, 5 layers
-Molteni physics package. Global configuration, 128x64x5 resolution.
+\item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics.
+Global configuration, on latitude longitude grid with 128x64x5 grid points
+($2.8^\circ{\rm degree}$ resolution).
-\item \textit{adjustment.128x64x1}
+\item \textit{adjustment.128x64x1} Barotropic adjustment
+problem on latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm degree}$ resolution).
\item \textit{adjustment.cs-32x32x1}
-\end{itemize}
+Barotropic adjustment
+problem on cube sphere grid with 32x32 points per face ( roughly
+$2.8^\circ{\rm degree}$ resolution).
+
+\item \textit{advect\_cs} Two-dimensional passive advection test on
+cube sphere grid.
+
+\item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection
+test on Cartesian grid.
+
+\item \textit{advect\_yz} Two-dimensional (vertical plane) passive advection test on Cartesian grid.
+
+\item \textit{carbon} Simple passive tracer experiment. Includes derivative
+calculation. Described in detail in section \ref{sect:eg-carbon-ad}.
+
+\item \textit{flt\_example} Example of using float package.
+
+\item \textit{global\_ocean.90x40x15} Global circulation with
+GM, flux boundary conditions and poles.
+
+\item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube sphere
+grid.
+
+\end{enumerate}
\subsection{Directory structure of model examples}
@@ -233,7 +297,7 @@
code} depending on the particular experiment. See section 2 for more details.
\item \textit{input}: contains the input data files required to run the
-example. At a mimimum, the \textit{input} directory contains the following
+example. At a minimum, the \textit{input} directory contains the following
files:
\begin{itemize}
@@ -266,9 +330,9 @@
To compile the code, we use the {\em make} program. This uses a file
({\em Makefile}) that allows us to pre-process source files, specify
compiler and optimization options and also figures out any file
-dependancies. We supply a script ({\em genmake}), described in section
+dependencies. We supply a script ({\em genmake}), described in section
\ref{sect:genmake}, that automatically creates the {\em Makefile} for
-you. You then need to build the dependancies and compile the code.
+you. You then need to build the dependencies and compile the code.
As an example, let's assume that you want to build and run experiment
\textit{verification/exp2}. The are multiple ways and places to actually
@@ -290,7 +354,7 @@
% ../../../tools/genmake -mods=../code
\end{verbatim}
-Next, create the dependancies:
+Next, create the dependencies:
\begin{verbatim}
% make depend
\end{verbatim}
@@ -342,7 +406,7 @@
% cp ../code/mitgcmuv ./
% ./mitgcmuv > output.txt
\end{verbatim}
-or if you will be making muliple runs with the same executable:
+or if you will be making multiple runs with the same executable:
\begin{verbatim}
% cd ../
% cp -r input run1
@@ -354,7 +418,7 @@
\subsubsection{Building from a new directory}
Since the {\em input} directory contains input files it is often more
-useful to keep {\em input} prestine and build in a new directory
+useful to keep {\em input} pristine and build in a new directory
within {\em verification/exp2/}:
\begin{verbatim}
% cd verification/exp2