--- manual/s_getstarted/text/getting_started.tex 2001/10/25 18:36:54 1.9 +++ manual/s_getstarted/text/getting_started.tex 2004/01/29 03:02:33 1.16 @@ -1,4 +1,4 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.9 2001/10/25 18:36:54 cnh Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.16 2004/01/29 03:02:33 edhill Exp $ % $Name: $ %\section{Getting started} @@ -18,31 +18,43 @@ \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} \end{rawhtml} \begin{verbatim} -http://mitgcm.org/sealion +http://mitgcm.org/pelican \end{verbatim} +\begin{rawhtml} \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 -\texttt{support@mitgcm.org} or browse at: +There is also a web-archived support mailing list for the model that +you can email at \texttt{MITgcm-support@mitgcm.org} or browse at: +\begin{rawhtml} \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 -on the newsgroup. A users email list will be established at some time -in the future. +\begin{rawhtml} \end{rawhtml} +Essentially all of the MITgcm web pages can be searched using a +popular web crawler such as Google or through our own search facility: +\begin{rawhtml} \end{rawhtml} +\begin{verbatim} +http://mitgcm.org/htdig/ +\end{verbatim} +\begin{rawhtml} \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} \end{rawhtml} -support@mitgcm.org +\begin{rawhtml} \end{rawhtml} +MITgcm-support@mitgcm.org \begin{rawhtml} \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: @@ -72,30 +84,52 @@ 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 -your .cshrc or .tcshrc: +Before you can use CVS, the following environment variable(s) should +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} \end{rawhtml} \begin{verbatim} -% cvs co -d directory -P -r release1 MITgcmUV +http://mitgcm.org/source\_code.html \end{verbatim} +\begin{rawhtml} \end{rawhtml} + -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}! -You can also use CVS to download code updates. More extensive -information on using CVS for maintaining MITgcm code can be found +The checkout process creates a directory called \textit{MITgcm}. If +the directory \textit{MITgcm} 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}! You can also use CVS to download code +updates. More extensive information on using CVS for maintaining +MITgcm code can be found \begin{rawhtml} \end{rawhtml} here \begin{rawhtml} \end{rawhtml} @@ -106,7 +140,7 @@ \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} \end{rawhtml} \begin{verbatim} http://mitgcm.org/download/ @@ -114,19 +148,84 @@ \begin{rawhtml} \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 -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% @@ -160,7 +259,7 @@ 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. @@ -180,95 +279,102 @@ \section{Example experiments} \label{sect:modelExamples} -The MITgcm distribution comes with a set of twenty-four pre-configured -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 -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. +%% a set of twenty-four pre-configured numerical experiments + +The MITgcm distribution comes with more than a dozen pre-configured +numerical experiments. Some of these example 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{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 +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 -\ref{sec:eg-baro}. - -\item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section -\ref{sec:eg-baroc}. + free-surface). This experiment is described in detail in section + \ref{sect:eg-baro}. +\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 -\ref{sec:eg-global}. - -\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 -periodic box. + 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 with open boundaries. + +\item \textit{exp5} - Inhomogenously forced ocean convection in a + 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 -conditions. - +\item \textit{internal wave} - Ocean internal wave forced by open + boundary conditions. + \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 -'94 forcing. - -\item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez -'94 forcing. - + scheme; 1 month integration + +\item \textit{hs94.1x64x5} - Zonal averaged atmosphere using Held and + Suarez '94 forcing. + +\item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and + Suarez '94 forcing. + \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. Global -Zonal Mean configuration, 1x64x5 resolution. - -\item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric -physics, equatorial Slice configuration. -2D (X-Z). - + Suarez '94 forcing on the cubed sphere. + +\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. + Global Zonal Mean configuration, 1x64x5 resolution. + +\item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate + Atmospheric physics, equatorial Slice configuration. 2D (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 -($2.8^\circ{\rm degree}$ resolution). - -\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} -Barotropic adjustment -problem on cube sphere grid with 32x32 points per face ( roughly -$2.8^\circ{\rm degree}$ resolution). - + Global configuration, on latitude longitude grid with 128x64x5 grid + points ($2.8^\circ{\rm degree}$ resolution). + +\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} 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{sec:eg-carbon-ad}. + 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{solid-body.cs-32x32x1} Solid body rotation test for cube sphere -grid. + +\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} @@ -278,47 +384,52 @@ \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} -\item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to the -``execution environment'' part of the code. The default version is located -in \textit{eesupp/inc}. - -\item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to the -``numerical model'' part of the code. The default version is located in -\textit{model/inc}. - -\item \textit{code/SIZE.h}: declares size of underlying computational grid. -The default version is located in \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. - -\item \textit{input}: contains the input data files required to run the -example. At a minimum, the \textit{input} directory contains the following -files: - -\begin{itemize} -\item \textit{input/data}: this file, written as a namelist, specifies the -main parameters for the experiment. - -\item \textit{input/data.pkg}: contains parameters relative to the packages -used in the experiment. - -\item \textit{input/eedata}: this file contains ``execution environment'' -data. At present, this consists of a specification of the number of threads -to use in $X$ and $Y$ under multithreaded execution. -\end{itemize} - -In addition, you will also find in this directory the forcing and topography -files as well as the files describing the initial state of the experiment. -This varies from experiment to experiment. See 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. + \begin{itemize} + \item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to + the ``execution environment'' part of the code. The default + version is located in \textit{eesupp/inc}. + + \item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to + the ``numerical model'' part of the code. The default version is + located in \textit{model/inc}. + + \item \textit{code/SIZE.h}: declares size of underlying + computational grid. The default version is located in + \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. + +\item \textit{input}: contains the input data files required to run + the example. At a minimum, the \textit{input} directory contains the + following files: + + \begin{itemize} + \item \textit{input/data}: this file, written as a namelist, + specifies the main parameters for the experiment. + + \item \textit{input/data.pkg}: contains parameters relative to the + packages used in the experiment. + + \item \textit{input/eedata}: this file contains ``execution + environment'' data. At present, this consists of a specification + of the number of threads to use in $X$ and $Y$ under multithreaded + execution. + \end{itemize} + +In addition, you will also find in this directory the forcing and +topography files as well as the files describing the initial state of +the experiment. This varies from experiment to experiment. See +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 @@ -330,44 +441,63 @@ 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 -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 dependencies and compile the code. +dependencies. We supply a script ({\em genmake2}), described in +section \ref{sect:genmake}, that automatically creates the {\em + 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 -do this but here let's build the code in +\textit{verification/exp2}. The are multiple ways and places to +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 -to use the following options when invoking \textit{genmake}: +On many systems, the {\em genmake2} program will be able to +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 dependencies: +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 -which other files depend. The purpose of this is to reduce -re-compilation if and when you start to modify the code. {\tt make -depend} also created links from the model source to this directory. +This modifies the {\em Makefile} by attaching a [long] list of files +upon which other files depend. The purpose of this is to reduce +re-compilation if and when you start to modify the code. The {\tt make + 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: @@ -385,17 +515,18 @@ 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 -source and data. +The following sections outline some possible methods of organizing +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} @@ -424,7 +555,7 @@ % cd verification/exp2 % mkdir build % cd build -% ../../../tools/genmake -mods=../code +% ../../../tools/genmake2 -mods=../code % make depend % make \end{verbatim} @@ -446,7 +577,7 @@ % ./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 @@ -454,7 +585,8 @@ 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} @@ -470,7 +602,8 @@ % 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 ../ @@ -481,107 +614,166 @@ -\subsection{\textit{genmake}} +\subsection{Using \textit{genmake2}} \label{sect:genmake} -To compile the code, use the script \textit{genmake} located in the \textit{% -tools} directory. \textit{genmake} is a script that generates the makefile. -It has been written so that the code can be compiled on a wide diversity of -machines and systems. However, if it doesn't work the first time on your -platform, you might need to edit certain lines of \textit{genmake} in the -section containing the setups for the different machines. The file is -structured like this: -\begin{verbatim} - . - . - . -general instructions (machine independent) - . - . - . - - setup machine 1 - - setup machine 2 - - setup machine 3 - - setup machine 4 - etc - . - . - . -\end{verbatim} - -For example, the setup corresponding to a DEC alpha machine is reproduced -here: -\begin{verbatim} - case OSF1+mpi: - echo "Configuring for DEC Alpha" - set CPP = ( '/usr/bin/cpp -P' ) - set DEFINES = ( ${DEFINES} '-DTARGET_DEC -DWORDLENGTH=1' ) - set KPP = ( 'kapf' ) - set KPPFILES = ( 'main.F' ) - set KFLAGS1 = ( '-scan=132 -noconc -cmp=' ) - set FC = ( 'f77' ) - set FFLAGS = ( '-convert big_endian -r8 -extend_source -automatic -call_shared -notransform_loops -align dcommons' ) - set FOPTIM = ( '-O5 -fast -tune host -inline all' ) - set NOOPTFLAGS = ( '-O0' ) - set LIBS = ( '-lfmpi -lmpi -lkmp_osfp10 -pthread' ) - set NOOPTFILES = ( 'barrier.F different_multiple.F external_fields_load.F') - set RMFILES = ( '*.p.out' ) - breaksw -\end{verbatim} - -Typically, these are the lines that you might need to edit to make \textit{% -genmake} work on your platform if it doesn't work the first time. \textit{% -genmake} understands several options that are described here: - -\begin{itemize} -\item -rootdir=dir - -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{% -bin} directory (which is the default compilation directory) or within the -\textit{verification} tree. - -\item -mods=dir1,dir2,... - -indicates the relative or absolute paths directories where the sources -should take precedence over the default versions (located in \textit{model}, -\textit{eesupp},...). Typically, this option is used when running the -examples, see below. - -\item -enable=pkg1,pkg2,... - -enables packages source code \textit{pkg1}, \textit{pkg2},... when creating -the makefile. - -\item -disable=pkg1,pkg2,... - -disables packages source code \textit{pkg1}, \textit{pkg2},... when creating -the makefile. - -\item -platform=machine - -specifies the platform for which you want the makefile. In general, you -won't need this option. \textit{genmake} will select the right machine for -you (the one you're working on!). However, this option is useful if you have -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). +To compile the code, first use the program \texttt{genmake2} (located +in the \textit{tools} directory) to generate a Makefile. +\texttt{genmake2} is a shell script written to work with all +``sh''--compatible shells including bash v1, bash v2, and Bourne. +Internally, \texttt{genmake2} determines the locations of needed +files, the compiler, compiler options, libraries, and Unix tools. It +relies upon a number of ``optfiles'' located in the {\em + tools/build\_options} directory. + +The purpose of the optfiles is to provide all the compilation options +for particular ``platforms'' (where ``platform'' roughly means the +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 +optfiles shipped with the code is +\begin{center} + {\bf OS\_HARDWARE\_COMPILER } +\end{center} +where +\begin{description} +\item[OS] is the name of the operating system (generally the + lower-case output of the {\tt 'uname'} command) +\item[HARDWARE] is a string that describes the CPU type and + corresponds to output from the {\tt 'uname -m'} command: + \begin{description} + \item[ia32] is for ``x86'' machines such as i386, i486, i586, i686, + and athlon + \item[ia64] is for Intel IA64 systems (eg. Itanium, Itanium2) + \item[amd64] is AMD x86\_64 systems + \item[ppc] is for Mac PowerPC systems + \end{description} +\item[COMPILER] is the compiler name (generally, the name of the + FORTRAN executable) +\end{description} + +In many cases, the default optfiles are sufficient and will result in +usable Makefiles. However, for some machines or code configurations, +new ``optfiles'' must be written. To create a new optfile, it is +generally best to start with one of the defaults and modify it to suit +your needs. Like \texttt{genmake2}, the optfiles are all written +using a simple ``sh''--compatible syntax. While nearly all variables +used within \texttt{genmake2} may be specified in the optfiles, the +critical ones that should be defined are: + +\begin{description} +\item[FC] the FORTRAN compiler (executable) to use +\item[DEFINES] the command-line DEFINE options passed to the compiler +\item[CPP] the C pre-processor to use +\item[NOOPTFLAGS] options flags for special files that should not be + optimized +\end{description} + +For example, the optfile for a typical Red Hat Linux machine (``ia32'' +architecture) using the GCC (g77) compiler is +\begin{verbatim} +FC=g77 +DEFINES='-D_BYTESWAPIO -DWORDLENGTH=4' +CPP='cpp -traditional -P' +NOOPTFLAGS='-O0' +# For IEEE, use the "-ffloat-store" option +if test "x$IEEE" = x ; then + FFLAGS='-Wimplicit -Wunused -Wuninitialized' + FOPTIM='-O3 -malign-double -funroll-loops' +else + FFLAGS='-Wimplicit -Wunused -ffloat-store' + FOPTIM='-O0 -malign-double' +fi +\end{verbatim} + +If you write an optfile for an unrepresented machine or compiler, you +are strongly encouraged to submit the optfile to the MITgcm project +for inclusion. Please send the file to the +\begin{rawhtml} \end{rawhtml} +\begin{center} + MITgcm-support@mitgcm.org +\end{center} +\begin{rawhtml} \end{rawhtml} +mailing list. -\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 -under jam (see section on parallel computation for more details). -\end{itemize} +\end{description} -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} @@ -804,43 +996,70 @@ \item time-discretization \end{itemize} -The time steps are set through the real variables \textbf{deltaTMom }and -\textbf{deltaTtracer }(in s) which represent the time step for the momentum -and tracer equations, respectively. For synchronous integrations, simply set -the two variables to the same value (or you can prescribe one time step only -through the variable \textbf{deltaT}). The Adams-Bashforth stabilizing -parameter is set through the variable \textbf{abEps }(dimensionless). The -stagger baroclinic time stepping can be activated by setting the logical -variable \textbf{staggerTimeStep }to '.\texttt{TRUE}.'. +The time steps are set through the real variables \textbf{deltaTMom} +and \textbf{deltaTtracer} (in s) which represent the time step for the +momentum and tracer equations, respectively. For synchronous +integrations, simply set the two variables to the same value (or you +can prescribe one time step only through the variable +\textbf{deltaT}). The Adams-Bashforth stabilizing parameter is set +through the variable \textbf{abEps} (dimensionless). The stagger +baroclinic time stepping can be activated by setting the logical +variable \textbf{staggerTimeStep} to '.\texttt{TRUE}.'. \subsection{Equation of state} -First, because the model equations are written in terms of perturbations, a -reference thermodynamic state needs to be specified. This is done through -the 1D arrays \textbf{tRef}\textit{\ }and \textbf{sRef}. \textbf{tRef }% -specifies the reference potential temperature profile (in $^{o}$C for -the ocean and $^{o}$K for the atmosphere) starting from the level -k=1. Similarly, \textbf{sRef}\textit{\ }specifies the reference salinity -profile (in ppt) for the ocean or the reference specific humidity profile -(in g/kg) for the atmosphere. - -The form of the equation of state is controlled by the character variables -\textbf{buoyancyRelation}\textit{\ }and \textbf{eosType}\textit{. }\textbf{% -buoyancyRelation}\textit{\ }is set to '\texttt{OCEANIC}' by default and -needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. In -this case, \textbf{eosType}\textit{\ }must be set to '\texttt{IDEALGAS}'. -For the ocean, two forms of the equation of state are available: linear (set -\textbf{eosType}\textit{\ }to '\texttt{LINEAR}') and a polynomial -approximation to the full nonlinear equation ( set \textbf{eosType}\textit{\ -}to '\texttt{POLYNOMIAL}'). In the linear case, you need to specify the -thermal and haline expansion coefficients represented by the variables -\textbf{tAlpha}\textit{\ }(in K$^{-1}$) and \textbf{sBeta}\textit{\ }(in ppt$% -^{-1}$). For the nonlinear case, you need to generate a file of polynomial -coefficients called \textit{POLY3.COEFFS. }To do this, use the program -\textit{utils/knudsen2/knudsen2.f }under the model tree (a Makefile is -available in the same directory and you will need to edit the number and the -values of the vertical levels in \textit{knudsen2.f }so that they match -those of your configuration). \textit{\ } +First, because the model equations are written in terms of +perturbations, a reference thermodynamic state needs to be specified. +This is done through the 1D arrays \textbf{tRef} and \textbf{sRef}. +\textbf{tRef} specifies the reference potential temperature profile +(in $^{o}$C for the ocean and $^{o}$K for the atmosphere) starting +from the level k=1. Similarly, \textbf{sRef} specifies the reference +salinity profile (in ppt) for the ocean or the reference specific +humidity profile (in g/kg) for the atmosphere. + +The form of the equation of state is controlled by the character +variables \textbf{buoyancyRelation} and \textbf{eosType}. +\textbf{buoyancyRelation} is set to '\texttt{OCEANIC}' by default and +needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. +In this case, \textbf{eosType} must be set to '\texttt{IDEALGAS}'. +For the ocean, two forms of the equation of state are available: +linear (set \textbf{eosType} to '\texttt{LINEAR}') and a polynomial +approximation to the full nonlinear equation ( set +\textbf{eosType}\textit{\ }to '\texttt{POLYNOMIAL}'). In the linear +case, you need to specify the thermal and haline expansion +coefficients represented by the variables \textbf{tAlpha}\textit{\ + }(in K$^{-1}$) and \textbf{sBeta} (in ppt$^{-1}$). For the nonlinear +case, you need to generate a file of polynomial coefficients called +\textit{POLY3.COEFFS}. To do this, use the program +\textit{utils/knudsen2/knudsen2.f} under the model tree (a Makefile is +available in the same directory and you will need to edit the number +and the values of the vertical levels in \textit{knudsen2.f} so that +they match those of your configuration). + +There there are also higher polynomials for the equation of state: +\begin{description} +\item['\texttt{UNESCO}':] The UNESCO equation of state formula of + Fofonoff and Millard \cite{fofonoff83}. This equation of state + assumes in-situ temperature, which is not a model variable; \emph{its use + is therefore discouraged, and it is only listed for completeness}. +\item['\texttt{JMD95Z}':] A modified UNESCO formula by Jackett and + McDougall \cite{jackett95}, which uses the model variable potential + temperature as input. The '\texttt{Z}' indicates that this equation + of state uses a horizontally and temporally constant pressure + $p_{0}=-g\rho_{0}z$. +\item['\texttt{JMD95P}':] A modified UNESCO formula by Jackett and + McDougall \cite{jackett95}, which uses the model variable potential + temperature as input. The '\texttt{P}' indicates that this equation + of state uses the actual hydrostatic pressure of the last time + step. Lagging the pressure in this way requires an additional pickup + file for restarts. +\item['\texttt{MDJWF}':] The new, more accurate and less expensive + equation of state by McDougall et~al. \cite{mcdougall03}. It also + requires lagging the pressure and therefore an additional pickup + file for restarts. +\end{description} +For none of these options an reference profile of temperature or +salinity is required. \subsection{Momentum equations} @@ -1073,3 +1292,8 @@ The precision with which to write the binary data is controlled by the integer variable w\textbf{riteBinaryPrec }(set it to \texttt{32} or \texttt{% 64}). + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: