--- manual/s_getstarted/text/getting_started.tex	2001/10/15 19:36:09	1.5
+++ manual/s_getstarted/text/getting_started.tex	2002/12/17 14:39:53	1.13
@@ -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.13 2002/12/17 14:39:53 mlosch 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} <A href=mailto:support@mitgcm.org> \end{rawhtml}
+support@mitgcm.org
+\begin{rawhtml} </A> \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} <A href=http://www.cvshome.org/ target="idontexist"> \end{rawhtml}
+cvshome.org
+\begin{rawhtml} </A> \end{rawhtml}
+and
+\begin{rawhtml} <A href=http://www.wincvs.org/ target="idontexist"> \end{rawhtml}
+wincvs.org
+\begin{rawhtml} </A> \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,51 +76,120 @@
 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
+% cvs co -d directory -P -r release1_beta1 MITgcm
 \end{verbatim}
 
 This creates a directory called \textit{directory}. If \textit{directory}
 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} <A href=http://mitgcm.org/usingcvstoget.html target="idontexist"> \end{rawhtml}
+here
+\begin{rawhtml} </A> \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} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
 \begin{verbatim}
 http://mitgcm.org/download/
 \end{verbatim}
+\begin{rawhtml} </A> \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.
 
+\paragraph*{Upgrading from an earlier version}
+
+If you already have an earlier version of the code you can ``upgrade''
+your copy instead of downloading the entire repository again. First,
+``cd'' (change directory) to the top of your working copy:
+\begin{verbatim}
+% cd MITgcm
+\end{verbatim}
+and then issue the cvs update command:
+\begin{verbatim}
+% cvs -q update -r release1_beta1 -d -P
+\end{verbatim}
+This will update the ``tag'' to ``release1\_beta1'', add any new
+directories (-d) and remove any empty directories (-P). The -q option
+means be quiet which will reduce the number of messages you'll see in
+the terminal. If you have modified the code prior to upgrading, CVS
+will try to merge your changes with the upgrades. If there is a
+conflict between your modifications and the upgrade, it will report
+that file with a ``C'' in front, e.g.:
+\begin{verbatim}
+C model/src/ini_parms.F
+\end{verbatim}
+If the list of conflicts scrolled off the screen, you can re-issue the
+cvs update command and it will report the conflicts. Conflicts are
+indicated in the code by the delimites ``<<<<<<<'', ``======='' and
+``>>>>>>>''. For example,
+\begin{verbatim}
+<<<<<<< ini_parms.F
+     & bottomDragLinear,myOwnBottomDragCoefficient,
+=======
+     & bottomDragLinear,bottomDragQuadratic,
+>>>>>>> 1.18
+\end{verbatim}
+means that you added ``myOwnBottomDragCoefficient'' to a namelist at
+the same time and place that we added ``bottomDragQuadratic''. You
+need to resolve this conflict and in this case the line should be
+changed to:
+\begin{verbatim}
+     & bottomDragLinear,bottomDragQuadratic,myOwnBottomDragCoefficient,
+\end{verbatim}
+and the lines with the delimiters (<<<<<<,======,>>>>>>) be deleted.
+Unless you are making modifications which exactly parallel
+developments we make, these types of conflicts should be rare.
+
+\paragraph*{Upgrading to the current pre-release version}
+
+We don't make a ``release'' for every little patch and bug fix in
+order to keep the frequency of upgrades to a minimum. However, if you
+have run into a problem for which ``we have already fixed in the
+latest code'' and we haven't made a ``tag'' or ``release'' since that
+patch then you'll need to get the latest code:
+\begin{verbatim}
+% cvs -q update -A -d -P
+\end{verbatim}
+Unlike, the ``check-out'' and ``update'' procedures above, there is no
+``tag'' or release name. The -A tells CVS to upgrade to the
+very latest version. As a rule, we don't recommend this since you
+might upgrade while we are in the processes of checking in the code so
+that you may only have part of a patch. Using this method of updating
+also means we can't tell what version of the code you are working
+with. So please be sure you understand what you're doing.
+
 \section{Model and directory structure}
 
-The ``numerical'' model is contained within a execution environment support
-wrapper. This wrapper is designed to provide a general framework for
-grid-point models. MITgcmUV is a specific numerical model that uses the
-framework. Under this structure the model is split into execution
-environment support code and conventional numerical model code. The
-execution environment support code is held under the \textit{eesupp}
-directory. The grid point model code is held under the \textit{model}
-directory. Code execution actually starts in the \textit{eesupp} routines
-and not in the \textit{model} routines. For this reason the top-level 
+The ``numerical'' model is contained within a execution environment
+support wrapper. This wrapper is designed to provide a general
+framework for grid-point models. MITgcmUV is a specific numerical
+model that uses the framework. Under this structure the model is split
+into execution environment support code and conventional numerical
+model code. The execution environment support code is held under the
+\textit{eesupp} directory. The grid point model code is held under the
+\textit{model} directory. Code execution actually starts in the
+\textit{eesupp} routines and not in the \textit{model} routines. For
+this reason the top-level
 \textit{MAIN.F} is in the \textit{eesupp/src} directory. In general,
 end-users should not need to worry about this level. The top-level routine
 for the numerical part of the code is in \textit{model/src/THE\_MODEL\_MAIN.F%
@@ -106,7 +202,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 +243,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 +292,52 @@
 \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{global\_ocean\_pressure} Global circulation in pressure
+  coordinate (non-Boussinesq ocean model). Described in detail in
+  section \ref{sect:eg-globalpressure}.
+
+\item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube sphere
+grid.
+
+\end{enumerate}
 
 \subsection{Directory structure of model examples}
 
@@ -233,7 +364,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 +397,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 +421,7 @@
 % ../../../tools/genmake  -mods=../code
 \end{verbatim}
 
-Next, create the dependancies:
+Next, create the dependencies:
 \begin{verbatim}
 % make depend
 \end{verbatim}
@@ -342,7 +473,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 +485,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
@@ -740,43 +871,70 @@
 \item time-discretization
 \end{itemize}
 
-The time steps are set through the real variables \textbf{deltaTMom }and 
-\textbf{deltaTtracer }(in s) which represent the time step for the momentum
-and tracer equations, respectively. For synchronous integrations, simply set
-the two variables to the same value (or you can prescribe one time step only
-through the variable \textbf{deltaT}). The Adams-Bashforth stabilizing
-parameter is set through the variable \textbf{abEps }(dimensionless). The
-stagger baroclinic time stepping can be activated by setting the logical
-variable \textbf{staggerTimeStep }to '.\texttt{TRUE}.'.
+The time steps are set through the real variables \textbf{deltaTMom}
+and \textbf{deltaTtracer} (in s) which represent the time step for the
+momentum and tracer equations, respectively. For synchronous
+integrations, simply set the two variables to the same value (or you
+can prescribe one time step only through the variable
+\textbf{deltaT}). The Adams-Bashforth stabilizing parameter is set
+through the variable \textbf{abEps} (dimensionless). The stagger
+baroclinic time stepping can be activated by setting the logical
+variable \textbf{staggerTimeStep} to '.\texttt{TRUE}.'.
 
 \subsection{Equation of state}
 
-First, because the model equations are written in terms of perturbations, a
-reference thermodynamic state needs to be specified. This is done through
-the 1D arrays \textbf{tRef}\textit{\ }and \textbf{sRef}. \textbf{tRef }%
-specifies the reference potential temperature profile (in $^{o}$C for
-the ocean and $^{o}$K for the atmosphere) starting from the level
-k=1. Similarly, \textbf{sRef}\textit{\ }specifies the reference salinity
-profile (in ppt) for the ocean or the reference specific humidity profile
-(in g/kg) for the atmosphere.
-
-The form of the equation of state is controlled by the character variables 
-\textbf{buoyancyRelation}\textit{\ }and \textbf{eosType}\textit{. }\textbf{%
-buoyancyRelation}\textit{\ }is set to '\texttt{OCEANIC}' by default and
-needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. In
-this case, \textbf{eosType}\textit{\ }must be set to '\texttt{IDEALGAS}'.
-For the ocean, two forms of the equation of state are available: linear (set 
-\textbf{eosType}\textit{\ }to '\texttt{LINEAR}') and a polynomial
-approximation to the full nonlinear equation ( set \textbf{eosType}\textit{\ 
-}to '\texttt{POLYNOMIAL}'). In the linear case, you need to specify the
-thermal and haline expansion coefficients represented by the variables 
-\textbf{tAlpha}\textit{\ }(in K$^{-1}$) and \textbf{sBeta}\textit{\ }(in ppt$%
-^{-1}$). For the nonlinear case, you need to generate a file of polynomial
-coefficients called \textit{POLY3.COEFFS. }To do this, use the program 
-\textit{utils/knudsen2/knudsen2.f }under the model tree (a Makefile is
-available in the same directory and you will need to edit the number and the
-values of the vertical levels in \textit{knudsen2.f }so that they match
-those of your configuration). \textit{\ }
+First, because the model equations are written in terms of
+perturbations, a reference thermodynamic state needs to be specified.
+This is done through the 1D arrays \textbf{tRef} and \textbf{sRef}.
+\textbf{tRef} specifies the reference potential temperature profile
+(in $^{o}$C for the ocean and $^{o}$K for the atmosphere) starting
+from the level k=1. Similarly, \textbf{sRef} specifies the reference
+salinity profile (in ppt) for the ocean or the reference specific
+humidity profile (in g/kg) for the atmosphere.
+
+The form of the equation of state is controlled by the character
+variables \textbf{buoyancyRelation} and \textbf{eosType}.
+\textbf{buoyancyRelation} is set to '\texttt{OCEANIC}' by default and
+needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations.
+In this case, \textbf{eosType} must be set to '\texttt{IDEALGAS}'.
+For the ocean, two forms of the equation of state are available:
+linear (set \textbf{eosType} to '\texttt{LINEAR}') and a polynomial
+approximation to the full nonlinear equation ( set
+\textbf{eosType}\textit{\ }to '\texttt{POLYNOMIAL}'). In the linear
+case, you need to specify the thermal and haline expansion
+coefficients represented by the variables \textbf{tAlpha}\textit{\ 
+  }(in K$^{-1}$) and \textbf{sBeta} (in ppt$^{-1}$). For the nonlinear
+case, you need to generate a file of polynomial coefficients called
+\textit{POLY3.COEFFS}. To do this, use the program
+\textit{utils/knudsen2/knudsen2.f} under the model tree (a Makefile is
+available in the same directory and you will need to edit the number
+and the values of the vertical levels in \textit{knudsen2.f} so that
+they match those of your configuration).
+
+There there are also higher polynomials for the equation of state:
+\begin{description}
+\item['\texttt{UNESCO}':] The UNESCO equation of state formula of
+  Fofonoff and Millard \cite{fofonoff83}. This equation of state
+  assumes in-situ temperature, which is not a model variable; \emph{its use
+  is therefore discouraged, and it is only listed for completeness}.
+\item['\texttt{JMD95Z}':] A modified UNESCO formula by Jackett and
+  McDougall \cite{jackett95}, which uses the model variable potential
+  temperature as input. The '\texttt{Z}' indicates that this equation
+  of state uses a horizontally and temporally constant pressure
+  $p_{0}=-g\rho_{0}z$. 
+\item['\texttt{JMD95P}':] A modified UNESCO formula by Jackett and
+  McDougall \cite{jackett95}, which uses the model variable potential
+  temperature as input. The '\texttt{P}' indicates that this equation
+  of state uses the actual hydrostatic pressure of the last time
+  step. Lagging the pressure in this way requires an additional pickup
+  file for restarts.
+\item['\texttt{MDJWF}':] The new, more accurate and less expensive
+  equation of state by McDougall et~al. \cite{mcdougall03}. It also
+  requires lagging the pressure and therefore an additional pickup
+  file for restarts.
+\end{description}
+For none of these options an reference profile of temperature or
+salinity is required.
 
 \subsection{Momentum equations}
 
@@ -1009,3 +1167,8 @@
 The precision with which to write the binary data is controlled by the
 integer variable w\textbf{riteBinaryPrec }(set it to \texttt{32} or \texttt{%
 64}).
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: t
+%%% End: 
