/[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.8 by cnh,
Mon Oct 22 11:55:47 2001 UTC
+revision 1.14 by edhill,
Wed Jul 30 13:42:52 2003 UTC
 Line 28 
 and site, as well as links for downloadi
  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}
 Line 41 
 in the future.
  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}
+ \begin{rawhtml} <A href=mailto:MITgcm-support@mitgcm.org> \end{rawhtml}
- support@mitgcm.org
+ 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:
  \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
 Line 86 
 You only need to do ``cvs login'' once.
  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}
 Line 116 
 The tar file still contains CVS informat
  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 139 
 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 184 
 The MITgcm distribution comes with a set
+Line 247 
 The MITgcm distribution comes with a set
  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
-Line 196 
 example is briefly described below.
+Line 259 
 example is briefly described below.
  \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.
-Line 255 
 $2.8^\circ{\rm degree}$ resolution).
+Line 318 
 $2.8^\circ{\rm degree}$ resolution).
  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.
  \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.
-Line 297 
 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 330 
 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 354 
 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 406 
 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 418 
 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 804 
 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 1073 
 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.8
 


changed lines


 
Added in v.1.14
 Legend:



Removed from v.1.8
 


changed lines


 
Added in v.1.14
-Removed from v.1.8
+Added in v.1.14

	ViewVC Help
Powered by ViewVC 1.1.22