/[MITgcm]/manual/s_getstarted/text/getting_started.tex

Diff of /manual/s_getstarted/text/getting_started.tex

Parent Directory | Revision Log | View Revision Graph Revision Graph | View Patch Patch

-revision 1.5 by adcroft,
Mon Oct 15 19:36:09 2001 UTC
+revision 1.13 by mlosch,
Tue Dec 17 14:39:53 2002 UTC
 Line 36 
 A mail to the email list will reach all
  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
-Line 49 
 Before you can use CVS, the following en
+Line 76 
 Before you can use CVS, the following en
  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
+ respect to the repository. Don't edit the files in \textit{CVS}!
- different \textit{version} that is not the latest source:
+ You can also use CVS to download code updates.  More extensive
- \begin{verbatim}
+ information on using CVS for maintaining MITgcm code can be found
- % cvs co -d directory -P -r version MITgcm
+ \begin{rawhtml} <A href=http://mitgcm.org/usingcvstoget.html target="idontexist"> \end{rawhtml}
- \end{verbatim}
+ here
- or the latest development version:
+ \begin{rawhtml} </A> \end{rawhtml}
- \begin{verbatim}
+ .
- % cvs co -d directory -P MITgcm
- \end{verbatim}
  \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
+ The ``numerical'' model is contained within a execution environment
- wrapper. This wrapper is designed to provide a general framework for
+ support wrapper. This wrapper is designed to provide a general
- grid-point models. MITgcmUV is a specific numerical model that uses the
+ framework for grid-point models. MITgcmUV is a specific numerical
- framework. Under this structure the model is split into execution
+ model that uses the framework. Under this structure the model is split
- environment support code and conventional numerical model code. The
+ into execution environment support code and conventional numerical
- execution environment support code is held under the \textit{eesupp}
+ model code. The execution environment support code is held under the
- directory. The grid point model code is held under the \textit{model}
+ \textit{eesupp} directory. The grid point model code is held under the
- directory. Code execution actually starts in the \textit{eesupp} routines
+ \textit{model} directory. Code execution actually starts in the
- and not in the \textit{model} routines. For this reason the top-level
+ \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%
-Line 106 
 directory in which to compile the code.
+Line 202 
 directory in which to compile the code.
  \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.
-Line 147 
 section \ref{sect:modelExamples}.
+Line 243 
 section \ref{sect:modelExamples}.
  \section{Example experiments}
  \label{sect:modelExamples}
- Now that you have successfully downloaded the model code we recommend that
+ The MITgcm distribution comes with a set of twenty-four pre-configured
- you first try to run the examples provided with the base version. You will
+ numerical experiments. Some of these examples experiments are tests of
- probably want to run the example that is the closest to the configuration
+ individual parts of the model code, but many are fully fledged numerical
- you will use eventually. The examples are located in subdirectories under
+ simulations. A few of the examples are used for tutorial documentation
- the directory \textit{verification} and are briefly described below (a full
+ in sections \ref{sect:eg-baro} - \ref{sect:eg-global}. The other examples
- description is given in section 2):
+ 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
-Line 189 
 scheme; 1 month integration
+Line 292 
 scheme; 1 month integration
  \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
+ \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. Global
- Molteni physics package. Global Zonal Mean configuration, 1x64x5 resolution.
+ 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.
 D (X-Z).
  \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
- physics, 5 layers Molteni physics package. 3D Equatorial Channel
+ physics. 3D Equatorial Channel configuration.
- configuration (not completely tested).
- \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics, 5 layers
+ \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics.
- Molteni physics package. Global configuration, 128x64x5 resolution.
+ 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}
-Line 233 
 In addition, other include files and sub
+Line 364 
 In addition, other include files and sub
  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}
-Line 266 
 the code.
+Line 397 
 the code.
  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
-Line 290 
 to use the following options when invoki
+Line 421 
 to use the following options when invoki
  % ../../../tools/genmake  -mods=../code
  \end{verbatim}
- Next, create the dependancies:
+ Next, create the dependencies:
  \begin{verbatim}
  % make depend
  \end{verbatim}
-Line 342 
 files must be in the same place. If you
+Line 473 
 files must be in the same place. If you
  % 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
-Line 354 
 or if you will be making muliple runs wi
+Line 485 
 or if you will be making muliple runs wi
  \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
-Line 740 
 here I think. To come soon...)
+Line 871 
 here I think. To come soon...)
  \item time-discretization
  \end{itemize}
- The time steps are set through the real variables \textbf{deltaTMom }and
+ The time steps are set through the real variables \textbf{deltaTMom}
- \textbf{deltaTtracer }(in s) which represent the time step for the momentum
+ and \textbf{deltaTtracer} (in s) which represent the time step for the
- and tracer equations, respectively. For synchronous integrations, simply set
+ momentum and tracer equations, respectively. For synchronous
- the two variables to the same value (or you can prescribe one time step only
+ integrations, simply set the two variables to the same value (or you
- through the variable \textbf{deltaT}). The Adams-Bashforth stabilizing
+ can prescribe one time step only through the variable
- parameter is set through the variable \textbf{abEps }(dimensionless). The
+ \textbf{deltaT}). The Adams-Bashforth stabilizing parameter is set
- stagger baroclinic time stepping can be activated by setting the logical
+ through the variable \textbf{abEps} (dimensionless). The stagger
- variable \textbf{staggerTimeStep }to '.\texttt{TRUE}.'.
+ 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
+ First, because the model equations are written in terms of
- reference thermodynamic state needs to be specified. This is done through
+ perturbations, a reference thermodynamic state needs to be specified.
- the 1D arrays \textbf{tRef}\textit{\ }and \textbf{sRef}. \textbf{tRef }%
+ This is done through the 1D arrays \textbf{tRef} and \textbf{sRef}.
- specifies the reference potential temperature profile (in $^{o}$C for
+ \textbf{tRef} specifies the reference potential temperature profile
- the ocean and $^{o}$K for the atmosphere) starting from the level
+ (in $^{o}$C for the ocean and $^{o}$K for the atmosphere) starting
- k=1. Similarly, \textbf{sRef}\textit{\ }specifies the reference salinity
+ from the level k=1. Similarly, \textbf{sRef} specifies the reference
- profile (in ppt) for the ocean or the reference specific humidity profile
+ salinity profile (in ppt) for the ocean or the reference specific
- (in g/kg) for the atmosphere.
+ humidity profile (in g/kg) for the atmosphere.
- The form of the equation of state is controlled by the character variables
+ The form of the equation of state is controlled by the character
- \textbf{buoyancyRelation}\textit{\ }and \textbf{eosType}\textit{. }\textbf{%
+ variables \textbf{buoyancyRelation} and \textbf{eosType}.
- buoyancyRelation}\textit{\ }is set to '\texttt{OCEANIC}' by default and
+ \textbf{buoyancyRelation} is set to '\texttt{OCEANIC}' by default and
- needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. In
+ needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations.
- this case, \textbf{eosType}\textit{\ }must be set to '\texttt{IDEALGAS}'.
+ 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
+ For the ocean, two forms of the equation of state are available:
- \textbf{eosType}\textit{\ }to '\texttt{LINEAR}') and a polynomial
+ linear (set \textbf{eosType} to '\texttt{LINEAR}') and a polynomial
- approximation to the full nonlinear equation ( set \textbf{eosType}\textit{\
+ approximation to the full nonlinear equation ( set
- }to '\texttt{POLYNOMIAL}'). In the linear case, you need to specify the
+ \textbf{eosType}\textit{\ }to '\texttt{POLYNOMIAL}'). In the linear
- thermal and haline expansion coefficients represented by the variables
+ case, you need to specify the thermal and haline expansion
- \textbf{tAlpha}\textit{\ }(in K$^{-1}$) and \textbf{sBeta}\textit{\ }(in ppt$%
+ coefficients represented by the variables \textbf{tAlpha}\textit{\
- ^{-1}$). For the nonlinear case, you need to generate a file of polynomial
+   }(in K$^{-1}$) and \textbf{sBeta} (in ppt$^{-1}$). For the nonlinear
- coefficients called \textit{POLY3.COEFFS. }To do this, use the program
+ case, you need to generate a file of polynomial coefficients called
- \textit{utils/knudsen2/knudsen2.f }under the model tree (a Makefile is
+ \textit{POLY3.COEFFS}. To do this, use the program
- available in the same directory and you will need to edit the number and the
+ \textit{utils/knudsen2/knudsen2.f} under the model tree (a Makefile is
- values of the vertical levels in \textit{knudsen2.f }so that they match
+ available in the same directory and you will need to edit the number
- those of your configuration). \textit{\ }
+ 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}
-Line 1009 
 fields can be written out by setting the
+Line 1167 
 fields can be written out by setting the
  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{%
 }).
+ %%% Local Variables:
+ %%% mode: latex
+ %%% TeX-master: t
+ %%% End:

 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.13
 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.13
-Removed from v.1.5
+Added in v.1.13

	ViewVC Help
Powered by ViewVC 1.1.22