--- manual/s_getstarted/text/getting_started.tex 2001/10/22 11:55:47 1.8 +++ manual/s_getstarted/text/getting_started.tex 2001/12/05 15:49:39 1.12 @@ -1,4 +1,4 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.8 2001/10/22 11:55:47 cnh Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.12 2001/12/05 15:49:39 adcroft Exp $ % $Name: $ %\section{Getting started} @@ -48,7 +48,7 @@ You can download the model two ways: \begin{enumerate} -\item Using CVS software. CVS is a freely available source code managment +\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 @@ -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% @@ -139,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. @@ -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. @@ -255,12 +318,12 @@ cube sphere grid. \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection -test on cartesian grid. +test on Cartesian grid. -\item \textit{advect\_yz} Two-dimensional (vertical 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{sec:eg-carbon-ad}. +calculation. Described in detail in section \ref{sect:eg-carbon-ad}. \item \textit{flt\_example} Example of using float package. @@ -297,7 +360,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} @@ -330,9 +393,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 @@ -354,7 +417,7 @@ % ../../../tools/genmake -mods=../code \end{verbatim} -Next, create the dependancies: +Next, create the dependencies: \begin{verbatim} % make depend \end{verbatim} @@ -406,7 +469,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 @@ -418,7 +481,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