--- manual/s_getstarted/text/getting_started.tex	2001/10/25 18:36:54	1.9
+++ manual/s_getstarted/text/getting_started.tex	2003/07/30 13:42:52	1.14
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.9 2001/10/25 18:36:54 cnh Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.14 2003/07/30 13:42:52 edhill Exp $
 % $Name:  $
 
 %\section{Getting started}
@@ -28,7 +28,7 @@
 documentation, to data-sources and other related sites.
 
 There is also a support news group for the model that you can email at
-\texttt{support@mitgcm.org} or browse at:
+\texttt{MITgcm-support@mitgcm.org} or browse at:
 \begin{verbatim}
 news://mitgcm.org/mitgcm.support
 \end{verbatim}
@@ -41,8 +41,8 @@
 
 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 href=mailto:MITgcm-support@mitgcm.org> \end{rawhtml}
+MITgcm-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:
@@ -86,7 +86,7 @@
 
 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}
@@ -116,17 +116,80 @@
 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%
@@ -184,7 +247,7 @@
 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{sec:eg-baro} - \ref{sec:eg-global}. The other examples
+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
@@ -196,14 +259,14 @@
 \begin{enumerate}
 \item \textit{exp0} - single layer, ocean double gyre (barotropic with
 free-surface). This experiment is described in detail in section
-\ref{sec:eg-baro}.
+\ref{sect:eg-baro}.
 
 \item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section
-\ref{sec:eg-baroc}.
+\ref{sect:eg-baroc}.
 
 \item \textit{exp2} - 4x4 degree global ocean simulation with steady
 climatological forcing. This experiment is described in detail in section
-\ref{sec:eg-global}.
+\ref{sect:eg-global}.
 
 \item \textit{exp4} - Flow over a Gaussian bump in open-water or channel
 with open boundaries.
@@ -260,13 +323,17 @@
 \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{sec:eg-carbon-ad}.
+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.
 
@@ -804,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}
 
@@ -1073,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: 
