/[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.16 by edhill,
Thu Jan 29 03:02:33 2004 UTC
 Line 18 
 you are ready to try implementing the co
  \section{Where to find information}
  \label{sect:whereToFindInfo}
- A web site is maintained for release 1 (Sealion) of MITgcm:
+ A web site is maintained for release 2 (``Pelican'') of MITgcm:
+ \begin{rawhtml} <A href=http://mitgcm.org/pelican/ target="idontexist"> \end{rawhtml}
  \begin{verbatim}
- http://mitgcm.org/sealion
+ http://mitgcm.org/pelican
  \end{verbatim}
+ \begin{rawhtml} </A> \end{rawhtml}
  Here you will find an on-line version of this document, a
  ``browsable'' copy of the code and a searchable database of the model
  and site, as well as links for downloading the model and
- documentation, to data-sources and other related sites.
+ documentation, to data-sources, and other related sites.
- There is also a support news group for the model that you can email at
+ There is also a web-archived support mailing list for the model that
- \texttt{support@mitgcm.org} or browse at:
+ you can email at \texttt{MITgcm-support@mitgcm.org} or browse at:
+ \begin{rawhtml} <A href=http://mitgcm.org/mailman/listinfo/mitgcm-support/ target="idontexist"> \end{rawhtml}
  \begin{verbatim}
- news://mitgcm.org/mitgcm.support
+ http://mitgcm.org/mailman/listinfo/mitgcm-support/
+ http://mitgcm.org/pipermail/mitgcm-support/
  \end{verbatim}
- A mail to the email list will reach all the developers and be archived
+ \begin{rawhtml} </A> \end{rawhtml}
- on the newsgroup. A users email list will be established at some time
+ Essentially all of the MITgcm web pages can be searched using a
- in the future.
+ popular web crawler such as Google or through our own search facility:
+ \begin{rawhtml} <A href=http://mitgcm.org/mailman/htdig/ target="idontexist"> \end{rawhtml}
+ \begin{verbatim}
+ http://mitgcm.org/htdig/
+ \end{verbatim}
+ \begin{rawhtml} </A> \end{rawhtml}
+ %%% http://www.google.com/search?q=hydrostatic+site%3Amitgcm.org
  \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}
+ \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 72 
 provides an efficient and elegant way of
+Line 84 
 provides an efficient and elegant way of
  track of your changes. If CVS is not available on your machine, you can also
  download a tar file.
- Before you can use CVS, the following environment variable has to be set in
+ Before you can use CVS, the following environment variable(s) should
- your .cshrc or .tcshrc:
+ be set within your shell.  For a csh or tcsh shell, put the following
+ \begin{verbatim}
+ % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/gcmpack
+ \end{verbatim}
+ in your .cshrc or .tcshrc file.  For bash or sh shells, put:
  \begin{verbatim}
- % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/u0/gcmpack
+ % export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
  \end{verbatim}
+ in your .profile or .bashrc file.
- To start using CVS, register with the MITgcm CVS server using command:
+ To get MITgcm through CVS, first 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 a ``cvs login'' once.
- To obtain the sources for release1 type:
+ To obtain the latest sources type:
+ \begin{verbatim}
+ % cvs co MITgcm
+ \end{verbatim}
+ or to get a specific release type:
+ \begin{verbatim}
+ % cvs co -P -r checkpoint52i_post  MITgcm
+ \end{verbatim}
+ The MITgcm web site contains further directions concerning the source
+ code and CVS.  It also contains a web interface to our CVS archive so
+ that one may easily view the state of files, revisions, and other
+ development milestones:
+ \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
  \begin{verbatim}
- % cvs co -d directory -P -r release1 MITgcmUV
+ http://mitgcm.org/source\_code.html
  \end{verbatim}
+ \begin{rawhtml} </A> \end{rawhtml}
- This creates a directory called \textit{directory}. If \textit{directory}
+ The checkout process creates a directory called \textit{MITgcm}. If
- exists this command updates your code based on the repository. Each
+ the directory \textit{MITgcm} exists this command updates your code
- directory in the source tree contains a directory \textit{CVS}. This
+ based on the repository. Each directory in the source tree contains a
- information is required by CVS to keep track of your file versions with
+ directory \textit{CVS}. This information is required by CVS to keep
- respect to the repository. Don't edit the files in \textit{CVS}!
+ track of your file versions with respect to the repository. Don't edit
- You can also use CVS to download code updates.  More extensive
+ the files in \textit{CVS}!  You can also use CVS to download code
- information on using CVS for maintaining MITgcm code can be found
+ 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}
-Line 106 
 here
+Line 140 
 here
  \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:
+ tar file from the web site at:
  \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
  \begin{verbatim}
  http://mitgcm.org/download/
-Line 114 
 http://mitgcm.org/download/
+Line 148 
 http://mitgcm.org/download/
  \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.
+ us if you should need to send us your copy of the code.  If a recent
+ tar file does not exist, then please contact the developers through
+ the MITgcm-support list.
+ \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 such as:
+ \begin{verbatim}
+ % cvs -q update -r checkpoint52i_post -d -P
+ \end{verbatim}
+ This will update the ``tag'' to ``checkpoint52i\_post'', 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 238 
 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 160 
 relative to the atmospheric intermediate
+Line 259 
 relative to the atmospheric intermediate
  in detail in section 3.
  \item \textit{tools}: this directory contains various useful tools. For
- example, \textit{genmake} is a script written in csh (C-shell) that should
+ example, \textit{genmake2} is a script written in csh (C-shell) that should
  be used to generate your makefile. The directory \textit{adjoint} contains
  the makefile specific to the Tangent linear and Adjoint Compiler (TAMC) that
  generates the adjoint code. The latter is described in details in part V.
-Line 180 
 section \ref{sect:modelExamples}.
+Line 279 
 section \ref{sect:modelExamples}.
  \section{Example experiments}
  \label{sect:modelExamples}
- The MITgcm distribution comes with a set of twenty-four pre-configured
+ %% a set of twenty-four pre-configured numerical experiments
- numerical experiments. Some of these examples experiments are tests of
- individual parts of the model code, but many are fully fledged numerical
+ The MITgcm distribution comes with more than a dozen pre-configured
- simulations. A few of the examples are used for tutorial documentation
+ numerical experiments. Some of these example experiments are tests of
- in sections \ref{sec:eg-baro} - \ref{sec:eg-global}. The other examples
+ individual parts of the model code, but many are fully fledged
- follow the same general structure as the tutorial examples. However,
+ numerical simulations. A few of the examples are used for tutorial
- they only include brief instructions in a text file called {\it README}.
+ documentation in sections \ref{sect:eg-baro} - \ref{sect:eg-global}.
- The examples are located in subdirectories under
+ The other examples follow the same general structure as the tutorial
- the directory \textit{verification}. Each
+ examples. However, they only include brief instructions in a text file
- example is briefly described below.
+ called {\it README}.  The examples are located in subdirectories under
+ the directory \textit{verification}. Each example is briefly described
+ below.
  \subsection{Full list of model examples}
  \begin{enumerate}
  \item \textit{exp0} - single layer, ocean double gyre (barotropic with
- free-surface). This experiment is described in detail in section
+   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}.
+ \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. This experiment is described in detail in section
+   climatological forcing. This experiment is described in detail in
- \ref{sec:eg-global}.
+   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
- with open boundaries.
+   channel with open boundaries.
- \item \textit{exp5} - Inhomogenously forced ocean convection in a doubly
+ \item \textit{exp5} - Inhomogenously forced ocean convection in a
- periodic box.
+   doubly periodic box.
  \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
- conditions.
+   boundary conditions.
  \item \textit{natl\_box} - Eastern subtropical North Atlantic with KPP
- scheme; 1 month integration
+   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
- '94 forcing.
+   Suarez '94 forcing.
- \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez
+ \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and
- '94 forcing.
+   Suarez '94 forcing.
  \item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
- Suarez '94 forcing on the cubed sphere.
+   Suarez '94 forcing on the cubed sphere.
- \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. Global
+ \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics.
- Zonal Mean configuration, 1x64x5 resolution.
+   Global Zonal Mean configuration, 1x64x5 resolution.
- \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric
+ \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate
- physics, equatorial Slice configuration.
+   Atmospheric physics, equatorial Slice configuration.  2D (X-Z).
-D (X-Z).
  \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
- physics. 3D Equatorial Channel configuration.
+   physics. 3D Equatorial Channel configuration.
  \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics.
- Global configuration, on latitude longitude grid with 128x64x5 grid points
+   Global configuration, on latitude longitude grid with 128x64x5 grid
- ($2.8^\circ{\rm degree}$ resolution).
+   points ($2.8^\circ{\rm degree}$ resolution).
- \item \textit{adjustment.128x64x1} Barotropic adjustment
+ \item \textit{adjustment.128x64x1} Barotropic adjustment problem on
- problem on latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm degree}$ resolution).
+   latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm
+     degree}$ resolution).
- \item \textit{adjustment.cs-32x32x1}
- Barotropic adjustment
+ \item \textit{adjustment.cs-32x32x1} Barotropic adjustment problem on
- problem on cube sphere grid with 32x32 points per face ( roughly
+   cube sphere grid with 32x32 points per face ( roughly $2.8^\circ{\rm
- $2.8^\circ{\rm degree}$ resolution).
+     degree}$ resolution).
  \item \textit{advect\_cs} Two-dimensional passive advection test on
- cube sphere grid.
+   cube sphere grid.
- \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection
+ \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive
- test on cartesian grid.
+   advection 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}.
+ \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
+ \item \textit{global\_ocean.90x40x15} Global circulation with GM, flux
- GM, flux boundary conditions and poles.
+   boundary conditions and poles.
- \item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube sphere
+ \item \textit{global\_ocean\_pressure} Global circulation in pressure
- grid.
+   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}
-Line 278 
 Each example directory has the following
+Line 384 
 Each example directory has the following
  \begin{itemize}
  \item \textit{code}: contains the code particular to the example. At a
- minimum, this directory includes the following files:
+   minimum, this directory includes the following files:
- \begin{itemize}
+   \begin{itemize}
- \item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to the
+   \item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to
- ``execution environment'' part of the code. The default version is located
+     the ``execution environment'' part of the code. The default
- in \textit{eesupp/inc}.
+     version is located in \textit{eesupp/inc}.
- \item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to the
+   \item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to
- ``numerical model'' part of the code. The default version is located in
+     the ``numerical model'' part of the code. The default version is
- \textit{model/inc}.
+     located in \textit{model/inc}.
- \item \textit{code/SIZE.h}: declares size of underlying computational grid.
+   \item \textit{code/SIZE.h}: declares size of underlying
- The default version is located in \textit{model/inc}.
+     computational grid.  The default version is located in
- \end{itemize}
+     \textit{model/inc}.
+   \end{itemize}
- In addition, other include files and subroutines might be present in \textit{%
- code} depending on the particular experiment. See section 2 for more details.
+   In addition, other include files and subroutines might be present in
+   \textit{code} depending on the particular experiment. See Section 2
- \item \textit{input}: contains the input data files required to run the
+   for more details.
- example. At a mimimum, the \textit{input} directory contains the following
- files:
+ \item \textit{input}: contains the input data files required to run
+   the example. At a minimum, the \textit{input} directory contains the
- \begin{itemize}
+   following files:
- \item \textit{input/data}: this file, written as a namelist, specifies the
- main parameters for the experiment.
+   \begin{itemize}
+   \item \textit{input/data}: this file, written as a namelist,
- \item \textit{input/data.pkg}: contains parameters relative to the packages
+     specifies the main parameters for the experiment.
- used in the experiment.
+   \item \textit{input/data.pkg}: contains parameters relative to the
- \item \textit{input/eedata}: this file contains ``execution environment''
+     packages used in the experiment.
- data. At present, this consists of a specification of the number of threads
- to use in $X$ and $Y$ under multithreaded execution.
+   \item \textit{input/eedata}: this file contains ``execution
- \end{itemize}
+     environment'' data. At present, this consists of a specification
+     of the number of threads to use in $X$ and $Y$ under multithreaded
- In addition, you will also find in this directory the forcing and topography
+     execution.
- files as well as the files describing the initial state of the experiment.
+   \end{itemize}
- This varies from experiment to experiment. See section 2 for more details.
+ In addition, you will also find in this directory the forcing and
- \item \textit{results}: this directory contains the output file \textit{%
+ topography files as well as the files describing the initial state of
- output.txt} produced by the simulation example. This file is useful for
+ the experiment.  This varies from experiment to experiment. See
- comparison with your own output when you run the experiment.
+ section 2 for more details.
+ \item \textit{results}: this directory contains the output file
+   \textit{output.txt} produced by the simulation example. This file is
+   useful for comparison with your own output when you run the
+   experiment.
  \end{itemize}
  Once you have chosen the example you want to run, you are ready to compile
-Line 330 
 the code.
+Line 441 
 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 genmake2}), described in
- \ref{sect:genmake}, that automatically creates the {\em Makefile} for
+ section \ref{sect:genmake}, that automatically creates the {\em
- you. You then need to build the dependancies and compile the code.
+   Makefile} for 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
+ \textit{verification/exp2}. The are multiple ways and places to
- do this but here let's build the code in
+ actually do this but here let's build the code in
  \textit{verification/exp2/input}:
  \begin{verbatim}
  % cd verification/exp2/input
  \end{verbatim}
  First, build the {\em Makefile}:
  \begin{verbatim}
- % ../../../tools/genmake -mods=../code
+ % ../../../tools/genmake2 -mods=../code
  \end{verbatim}
  The command line option tells {\em genmake} to override model source
  code with any files in the directory {\em ./code/}.
- If there is no \textit{.genmakerc} in the \textit{input} directory, you have
+ On many systems, the {\em genmake2} program will be able to
- to use the following options when invoking \textit{genmake}:
+ automatically recognize the hardware, find compilers and other tools
+ within the user's path (``echo \$PATH''), and then choose an
+ appropriate set of options from the files contained in the {\em
+   tools/build\_options} directory.  Under some circumstances, a user
+ may have to create a new ``optfile'' in order to specify the exact
+ combination of compiler, compiler flags, libraries, and other options
+ necessary to build a particular configuration of MITgcm.  In such
+ cases, it is generally helpful to read the existing ``optfiles'' and
+ mimic their syntax.
+ Through the MITgcm-support list, the MITgcm developers are willing to
+ provide help writing or modifing ``optfiles''.  And we encourage users
+ to post new ``optfiles'' (particularly ones for new machines or
+ architectures) to the MITgcm-support list.
+ To specify an optfile to {\em genmake2}, the syntax is:
  \begin{verbatim}
- % ../../../tools/genmake  -mods=../code
+ % ../../../tools/genmake2 -mods=../code -of /path/to/optfile
  \end{verbatim}
- Next, create the dependancies:
+ Once a {\em Makefile} has been generated, we create the dependencies:
  \begin{verbatim}
  % make depend
  \end{verbatim}
- This modifies {\em Makefile} by attaching a [long] list of files on
+ This modifies the {\em Makefile} by attaching a [long] list of files
- which other files depend. The purpose of this is to reduce
+ upon which other files depend. The purpose of this is to reduce
- re-compilation if and when you start to modify the code. {\tt make
+ re-compilation if and when you start to modify the code. The {\tt make
- depend} also created links from the model source to this directory.
+   depend} command also creates links from the model source to this
+ directory.
- Now compile the code:
+ Next compile the code:
  \begin{verbatim}
  % make
  \end{verbatim}
  The {\tt make} command creates an executable called \textit{mitgcmuv}.
+ Additional make ``targets'' are defined within the makefile to aid in
+ the production of adjoint and other versions of MITgcm.
  Now you are ready to run the model. General instructions for doing so are
  given in section \ref{sect:runModel}. Here, we can run the model with:
-Line 385 
 executable in the {\em input} directory
+Line 515 
 executable in the {\em input} directory
  convenience. You can also configure and compile the code in other
  locations, for example on a scratch disk with out having to copy the
  entire source tree. The only requirement to do so is you have {\tt
- genmake} in your path or you know the absolute path to {\tt genmake}.
+   genmake2} in your path or you know the absolute path to {\tt
+   genmake2}.
- The following sections outline some possible methods of organizing you
+ The following sections outline some possible methods of organizing
- source and data.
+ your source and data.
  \subsubsection{Building from the {\em ../code directory}}
  This is just as simple as building in the {\em input/} directory:
  \begin{verbatim}
  % cd verification/exp2/code
- % ../../../tools/genmake
+ % ../../../tools/genmake2
  % make depend
  % make
  \end{verbatim}
-Line 406 
 files must be in the same place. If you
+Line 537 
 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 549 
 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
  % mkdir build
  % cd build
- % ../../../tools/genmake -mods=../code
+ % ../../../tools/genmake2 -mods=../code
  % make depend
  % make
  \end{verbatim}
-Line 446 
 running in a new directory each time mig
+Line 577 
 running in a new directory each time mig
  % ./mitgcmuv > output.txt
  \end{verbatim}
- \subsubsection{Building from on a scratch disk}
+ \subsubsection{Building on a scratch disk}
  Model object files and output data can use up large amounts of disk
  space so it is often the case that you will be operating on a large
-Line 454 
 scratch disk. Assuming the model source
+Line 585 
 scratch disk. Assuming the model source
  following commands will build the model in {\em /scratch/exp2-run1}:
  \begin{verbatim}
  % cd /scratch/exp2-run1
- % ~/MITgcm/tools/genmake -rootdir=~/MITgcm -mods=~/MITgcm/verification/exp2/code
+ % ~/MITgcm/tools/genmake2 -rootdir=~/MITgcm \
+   -mods=~/MITgcm/verification/exp2/code
  % make depend
  % make
  \end{verbatim}
-Line 470 
 the one experiment:
+Line 602 
 the one experiment:
  % cd /scratch/exp2
  % mkdir build
  % cd build
- % ~/MITgcm/tools/genmake -rootdir=~/MITgcm -mods=~/MITgcm/verification/exp2/code
+ % ~/MITgcm/tools/genmake2 -rootdir=~/MITgcm \
+   -mods=~/MITgcm/verification/exp2/code
  % make depend
  % make
  % cd ../
-Line 481 
 the one experiment:
+Line 614 
 the one experiment:
- \subsection{\textit{genmake}}
+ \subsection{Using \textit{genmake2}}
  \label{sect:genmake}
- To compile the code, use the script \textit{genmake} located in the \textit{%
+ To compile the code, first use the program \texttt{genmake2} (located
- tools} directory. \textit{genmake} is a script that generates the makefile.
+ in the \textit{tools} directory) to generate a Makefile.
- It has been written so that the code can be compiled on a wide diversity of
+ \texttt{genmake2} is a shell script written to work with all
- machines and systems. However, if it doesn't work the first time on your
+ ``sh''--compatible shells including bash v1, bash v2, and Bourne.
- platform, you might need to edit certain lines of \textit{genmake} in the
+ Internally, \texttt{genmake2} determines the locations of needed
- section containing the setups for the different machines. The file is
+ files, the compiler, compiler options, libraries, and Unix tools.  It
- structured like this:
+ relies upon a number of ``optfiles'' located in the {\em
- \begin{verbatim}
+   tools/build\_options} directory.
-         .
-         .
+ The purpose of the optfiles is to provide all the compilation options
-         .
+ for particular ``platforms'' (where ``platform'' roughly means the
- general instructions (machine independent)
+ combination of the hardware and the compiler) and code configurations.
-         .
+ Given the combinations of possible compilers and library dependencies
-         .
+ ({\it eg.}  MPI and NetCDF) there may be numerous optfiles available
-         .
+ for a single machine.  The naming scheme for the majority of the
-     - setup machine 1
+ optfiles shipped with the code is
-     - setup machine 2
+ \begin{center}
-     - setup machine 3
+   {\bf OS\_HARDWARE\_COMPILER }
-     - setup machine 4
+ \end{center}
-        etc
+ where
-         .
+ \begin{description}
-         .
+ \item[OS] is the name of the operating system (generally the
-         .
+   lower-case output of the {\tt 'uname'} command)
- \end{verbatim}
+ \item[HARDWARE] is a string that describes the CPU type and
+   corresponds to output from the  {\tt 'uname -m'} command:
- For example, the setup corresponding to a DEC alpha machine is reproduced
+   \begin{description}
- here:
+   \item[ia32] is for ``x86'' machines such as i386, i486, i586, i686,
- \begin{verbatim}
+     and athlon
-   case OSF1+mpi:
+   \item[ia64] is for Intel IA64 systems (eg. Itanium, Itanium2)
-     echo "Configuring for DEC Alpha"
+   \item[amd64] is AMD x86\_64 systems
-     set CPP        = ( '/usr/bin/cpp -P' )
+   \item[ppc] is for Mac PowerPC systems
-     set DEFINES    = ( ${DEFINES}  '-DTARGET_DEC -DWORDLENGTH=1' )
+   \end{description}
-     set KPP        = ( 'kapf' )
+ \item[COMPILER] is the compiler name (generally, the name of the
-     set KPPFILES   = ( 'main.F' )
+   FORTRAN executable)
-     set KFLAGS1    = ( '-scan=132 -noconc -cmp=' )
+ \end{description}
-     set FC         = ( 'f77' )
-     set FFLAGS     = ( '-convert big_endian -r8 -extend_source -automatic -call_shared -notransform_loops -align dcommons' )
+ In many cases, the default optfiles are sufficient and will result in
-     set FOPTIM     = ( '-O5 -fast -tune host -inline all' )
+ usable Makefiles.  However, for some machines or code configurations,
-     set NOOPTFLAGS = ( '-O0' )
+ new ``optfiles'' must be written. To create a new optfile, it is
-     set LIBS       = ( '-lfmpi -lmpi -lkmp_osfp10 -pthread' )
+ generally best to start with one of the defaults and modify it to suit
-     set NOOPTFILES = ( 'barrier.F different_multiple.F external_fields_load.F')
+ your needs.  Like \texttt{genmake2}, the optfiles are all written
-     set RMFILES    = ( '*.p.out' )
+ using a simple ``sh''--compatible syntax.  While nearly all variables
-     breaksw
+ used within \texttt{genmake2} may be specified in the optfiles, the
- \end{verbatim}
+ critical ones that should be defined are:
- Typically, these are the lines that you might need to edit to make \textit{%
+ \begin{description}
- genmake} work on your platform if it doesn't work the first time. \textit{%
+ \item[FC] the FORTRAN compiler (executable) to use
- genmake} understands several options that are described here:
+ \item[DEFINES] the command-line DEFINE options passed to the compiler
+ \item[CPP] the C pre-processor to use
- \begin{itemize}
+ \item[NOOPTFLAGS] options flags for special files that should not be
- \item -rootdir=dir
+   optimized
+ \end{description}
- indicates where the model root directory is relative to the directory where
- you are compiling. This option is not needed if you compile in the \textit{%
+ For example, the optfile for a typical Red Hat Linux machine (``ia32''
- bin} directory (which is the default compilation directory) or within the
+ architecture) using the GCC (g77) compiler is
- \textit{verification} tree.
+ \begin{verbatim}
+ FC=g77
- \item -mods=dir1,dir2,...
+ DEFINES='-D_BYTESWAPIO -DWORDLENGTH=4'
+ CPP='cpp  -traditional -P'
- indicates the relative or absolute paths directories where the sources
+ NOOPTFLAGS='-O0'
- should take precedence over the default versions (located in \textit{model},
+ #  For IEEE, use the "-ffloat-store" option
- \textit{eesupp},...). Typically, this option is used when running the
+ if test "x$IEEE" = x ; then
- examples, see below.
+     FFLAGS='-Wimplicit -Wunused -Wuninitialized'
+     FOPTIM='-O3 -malign-double -funroll-loops'
- \item -enable=pkg1,pkg2,...
+ else
+     FFLAGS='-Wimplicit -Wunused -ffloat-store'
- enables packages source code \textit{pkg1}, \textit{pkg2},... when creating
+     FOPTIM='-O0 -malign-double'
- the makefile.
+ fi
+ \end{verbatim}
- \item -disable=pkg1,pkg2,...
+ If you write an optfile for an unrepresented machine or compiler, you
- disables packages source code \textit{pkg1}, \textit{pkg2},... when creating
+ are strongly encouraged to submit the optfile to the MITgcm project
- the makefile.
+ for inclusion.  Please send the file to the
+ \begin{rawhtml} <A href="mail-to:MITgcm-support@mitgcm.org"> \end{rawhtml}
- \item -platform=machine
+ \begin{center}
+   MITgcm-support@mitgcm.org
- specifies the platform for which you want the makefile. In general, you
+ \end{center}
- won't need this option. \textit{genmake} will select the right machine for
+ \begin{rawhtml} </A> \end{rawhtml}
- you (the one you're working on!). However, this option is useful if you have
+ mailing list.
- a choice of several compilers on one machine and you want to use the one
- that is not the default (ex: \texttt{pgf77} instead of \texttt{f77} under
- Linux).
- \item -mpi
- this is used when you want to run the model in parallel processing mode
- under mpi (see section on parallel computation for more details).
- \item -jam
+ In addition to the optfiles, \texttt{genmake2} supports a number of
+ helpful command-line options.  A complete list of these options can be
+ obtained from:
+ \begin{verbatim}
+ % genmake2 -h
+ \end{verbatim}
+ The most important command-line options are:
+ \begin{description}
+ \item[--optfile=/PATH/FILENAME] specifies the optfile that should be
+   used for a particular build.
+   If no "optfile" is specified (either through the command line or the
+   MITGCM\_OPTFILE environment variable), genmake2 will try to make a
+   reasonable guess from the list provided in {\em
+     tools/build\_options}.  The method used for making this guess is
+   to first determine the combination of operating system and hardware
+   (eg. "linux\_ia32") and then find a working FORTRAN compiler within
+   the user's path.  When these three items have been identified,
+   genmake2 will try to find an optfile that has a matching name.
+ \item[--pdepend=/PATH/FILENAME] specifies the dependency file used for
+   packages.
+   If not specified, the default dependency file {\em pkg/pkg\_depend}
+   is used.  The syntax for this file is parsed on a line-by-line basis
+   where each line containes either a comment ("\#") or a simple
+   "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or "-" symbol
+   specifies a "must be used with" or a "must not be used with"
+   relationship, respectively.  If no rule is specified, then it is
+   assumed that the two packages are compatible and will function
+   either with or without each other.
+ \item[--pdefault='PKG1 PKG2 PKG3 ...'] specifies the default set of
+   packages to be used.
+   If not set, the default package list will be read from {\em
+     pkg/pkg\_default}
+ \item[--adof=/path/to/file] specifies the "adjoint" or automatic
+   differentiation options file to be used.  The file is analogous to
+   the ``optfile'' defined above but it specifies information for the
+   AD build process.
+   The default file is located in {\em
+     tools/adjoint\_options/adjoint\_default} and it defines the "TAF"
+   and "TAMC" compilers.  An alternate version is also available at
+   {\em tools/adjoint\_options/adjoint\_staf} that selects the newer
+   "STAF" compiler.  As with any compilers, it is helpful to have their
+   directories listed in your {\tt \$PATH} environment variable.
+ \item[--mods='DIR1 DIR2 DIR3 ...'] specifies a list of directories
+   containing ``modifications''.  These directories contain files with
+   names that may (or may not) exist in the main MITgcm source tree but
+   will be overridden by any identically-named sources within the
+   ``MODS'' directories.
+   The order of precedence for this "name-hiding" is as follows:
+   \begin{itemize}
+   \item ``MODS'' directories (in the order given)
+   \item Packages either explicitly specified or provided by default
+     (in the order given)
+   \item Packages included due to package dependencies (in the order
+     that that package dependencies are parsed)
+   \item The "standard dirs" (which may have been specified by the
+     ``-standarddirs'' option)
+   \end{itemize}
+ \item[--make=/path/to/gmake] Due to the poor handling of soft-links and
+   other bugs common with the \texttt{make} versions provided by
+   commercial Unix vendors, GNU \texttt{make} (sometimes called
+   \texttt{gmake}) should be preferred.  This option provides a means
+   for specifying the make executable to be used.
- this is used when you want to run the model in parallel processing mode
+ \end{description}
- under jam (see section on parallel computation for more details).
- \end{itemize}
- For some of the examples, there is a file called \textit{.genmakerc} in the
- \textit{input} directory that has the relevant \textit{genmake} options for
- that particular example. In this way you don't need to type the options when
- invoking \textit{genmake}.
  \section{Running the model}
-Line 804 
 here I think. To come soon...)
+Line 996 
 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 1292 
 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.16
 Legend:



Removed from v.1.8
 


changed lines


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

	ViewVC Help
Powered by ViewVC 1.1.22