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

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

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

revision 1.31 by edhill, Tue Aug 9 21:52:09 2005 UTC revision 1.39 by molod, Fri Jun 30 15:56:52 2006 UTC
# Line 3  Line 3 
3    
4  %\section{Getting started}  %\section{Getting started}
5    
6  In this section, we describe how to use the model. In the first  We believe the best way to familiarize yourself with the
 section, we provide enough information to help you get started with  
 the model. We believe the best way to familiarize yourself with the  
7  model is to run the case study examples provided with the base  model is to run the case study examples provided with the base
8  version. Information on how to obtain, compile, and run the code is  version. Information on how to obtain, compile, and run the code is
9  found there as well as a brief description of the model structure  found here as well as a brief description of the model structure
10  directory and the case study examples.  The latter and the code  directory and the case study examples. Information is also provided
11  structure are described more fully in chapters  here on how to customize the code when you are ready to try implementing
12  \ref{chap:discretization} and \ref{chap:sarch}, respectively. Here, in  the configuration you have in mind.  The code and algorithm
13  this section, we provide information on how to customize the code when  are described more fully in chapters \ref{chap:discretization} and
14  you are ready to try implementing the configuration you have in mind.  \ref{chap:sarch}.
   
15    
16  \section{Where to find information}  \section{Where to find information}
17  \label{sect:whereToFindInfo}  \label{sect:whereToFindInfo}
# Line 22  you are ready to try implementing the co Line 19  you are ready to try implementing the co
19  <!-- CMIREDIR:whereToFindInfo: -->  <!-- CMIREDIR:whereToFindInfo: -->
20  \end{rawhtml}  \end{rawhtml}
21    
22  A web site is maintained for release 2 (``Pelican'') of MITgcm:  There is a web-archived support mailing list for the model that
 \begin{rawhtml} <A href=http://mitgcm.org/pelican/ target="idontexist"> \end{rawhtml}  
 \begin{verbatim}  
 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.  
   
 There is also a web-archived support mailing list for the model that  
23  you can email at \texttt{MITgcm-support@mitgcm.org} or browse at:  you can email at \texttt{MITgcm-support@mitgcm.org} or browse at:
24  \begin{rawhtml} <A href=http://mitgcm.org/mailman/listinfo/mitgcm-support/ target="idontexist"> \end{rawhtml}  \begin{rawhtml} <A href=http://mitgcm.org/mailman/listinfo/mitgcm-support/ target="idontexist"> \end{rawhtml}
25  \begin{verbatim}  \begin{verbatim}
# Line 41  http://mitgcm.org/mailman/listinfo/mitgc Line 27  http://mitgcm.org/mailman/listinfo/mitgc
27  http://mitgcm.org/pipermail/mitgcm-support/  http://mitgcm.org/pipermail/mitgcm-support/
28  \end{verbatim}  \end{verbatim}
29  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \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} <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  
   
   
30    
31  \section{Obtaining the code}  \section{Obtaining the code}
32  \label{sect:obtainingCode}  \label{sect:obtainingCode}
# Line 126  The MITgcm web site contains further dir Line 102  The MITgcm web site contains further dir
102  code and CVS.  It also contains a web interface to our CVS archive so  code and CVS.  It also contains a web interface to our CVS archive so
103  that one may easily view the state of files, revisions, and other  that one may easily view the state of files, revisions, and other
104  development milestones:  development milestones:
105  \begin{rawhtml} <A href=''http://mitgcm.org/download'' target="idontexist"> \end{rawhtml}  \begin{rawhtml} <A href="http://mitgcm.org/download" target="idontexist"> \end{rawhtml}
106  \begin{verbatim}  \begin{verbatim}
107  http://mitgcm.org/source_code.html  http://mitgcm.org/source_code.html
108  \end{verbatim}  \end{verbatim}
# Line 163  track of your file versions with respect Line 139  track of your file versions with respect
139  the files in \texttt{CVS}!  You can also use CVS to download code  the files in \texttt{CVS}!  You can also use CVS to download code
140  updates.  More extensive information on using CVS for maintaining  updates.  More extensive information on using CVS for maintaining
141  MITgcm code can be found  MITgcm code can be found
142  \begin{rawhtml} <A href=''http://mitgcm.org/usingcvstoget.html'' target="idontexist"> \end{rawhtml}  \begin{rawhtml} <A href="http://mitgcm.org/usingcvstoget.html" target="idontexist"> \end{rawhtml}
143  here  here
144  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
145  .  .
# Line 176  they create can be changed to a differen Line 152  they create can be changed to a differen
152     %  mv MITgcm MITgcm_verif_basic     %  mv MITgcm MITgcm_verif_basic
153  \end{verbatim}  \end{verbatim}
154    
   
 \subsection{Method 2 - Tar file download}  
 \label{sect:conventionalDownload}  
   
 If you do not have CVS on your system, you can download the model as a  
 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/  
 \end{verbatim}  
 \begin{rawhtml} </A> \end{rawhtml}  
 The tar file still contains CVS information which we urge you not to  
 delete; even if you do not use CVS yourself the information can help  
 us if you should need to send us your copy of the code.  If a recent  
 tar file does not exist, then please contact the developers through  
 the  
 \begin{rawhtml} <A href=''mailto:MITgcm-support@mitgcm.org"> \end{rawhtml}  
 MITgcm-support@mitgcm.org  
 \begin{rawhtml} </A> \end{rawhtml}  
 mailing list.  
   
155  \subsubsection{Upgrading from an earlier version}  \subsubsection{Upgrading from an earlier version}
156    
157  If you already have an earlier version of the code you can ``upgrade''  If you already have an earlier version of the code you can ``upgrade''
# Line 263  that you may only have part of a patch. Line 218  that you may only have part of a patch.
218  also means we can't tell what version of the code you are working  also means we can't tell what version of the code you are working
219  with. So please be sure you understand what you're doing.  with. So please be sure you understand what you're doing.
220    
221    \subsection{Method 2 - Tar file download}
222    \label{sect:conventionalDownload}
223    
224    If you do not have CVS on your system, you can download the model as a
225    tar file from the web site at:
226    \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
227    \begin{verbatim}
228    http://mitgcm.org/download/
229    \end{verbatim}
230    \begin{rawhtml} </A> \end{rawhtml}
231    The tar file still contains CVS information which we urge you not to
232    delete; even if you do not use CVS yourself the information can help
233    us if you should need to send us your copy of the code.  If a recent
234    tar file does not exist, then please contact the developers through
235    the
236    \begin{rawhtml} <A href="mailto:MITgcm-support@mitgcm.org"> \end{rawhtml}
237    MITgcm-support@mitgcm.org
238    \begin{rawhtml} </A> \end{rawhtml}
239    mailing list.
240    
241  \section{Model and directory structure}  \section{Model and directory structure}
242  \begin{rawhtml}  \begin{rawhtml}
243  <!-- CMIREDIR:directory_structure: -->  <!-- CMIREDIR:directory_structure: -->
# Line 287  structure). Line 262  structure).
262    
263  \begin{itemize}  \begin{itemize}
264    
 \item \texttt{bin}: this directory is initially empty. It is the  
   default directory in which to compile the code.  
     
 \item \texttt{diags}: contains the code relative to time-averaged  
   diagnostics. It is subdivided into two subdirectories \texttt{inc}  
   and \texttt{src} that contain include files (\texttt{*.h} files) and  
   Fortran subroutines (\texttt{*.F} files), respectively.  
   
265  \item \texttt{doc}: contains brief documentation notes.  \item \texttt{doc}: contains brief documentation notes.
266        
267  \item \texttt{eesupp}: contains the execution environment source code.  \item \texttt{eesupp}: contains the execution environment source code.
268    Also subdivided into two subdirectories \texttt{inc} and    Also subdivided into two subdirectories \texttt{inc} and
269    \texttt{src}.    \texttt{src}.
270        
 \item \texttt{exe}: this directory is initially empty. It is the  
   default directory in which to execute the code.  
     
271  \item \texttt{model}: this directory contains the main source code.  \item \texttt{model}: this directory contains the main source code.
272    Also subdivided into two subdirectories \texttt{inc} and    Also subdivided into two subdirectories \texttt{inc} and
273    \texttt{src}.    \texttt{src}.
# Line 312  structure). Line 276  structure).
276    package corresponds to a subdirectory. For example, \texttt{gmredi}    package corresponds to a subdirectory. For example, \texttt{gmredi}
277    contains the code related to the Gent-McWilliams/Redi scheme,    contains the code related to the Gent-McWilliams/Redi scheme,
278    \texttt{aim} the code relative to the atmospheric intermediate    \texttt{aim} the code relative to the atmospheric intermediate
279    physics. The packages are described in detail in section 3.    physics. The packages are described in detail in chapter \ref{chap.packagesI}.
280        
281  \item \texttt{tools}: this directory contains various useful tools.  \item \texttt{tools}: this directory contains various useful tools.
282    For example, \texttt{genmake2} is a script written in csh (C-shell)    For example, \texttt{genmake2} is a script written in csh (C-shell)
283    that should be used to generate your makefile. The directory    that should be used to generate your makefile. The directory
284    \texttt{adjoint} contains the makefile specific to the Tangent    \texttt{adjoint} contains the makefile specific to the Tangent
285    linear and Adjoint Compiler (TAMC) that generates the adjoint code.    linear and Adjoint Compiler (TAMC) that generates the adjoint code.
286    The latter is described in details in part V.    The latter is described in detail in part \ref{chap.ecco}.
287      This directory also contains the subdirectory build\_options, which
288      contains the `optfiles' with the compiler options for the different
289      compilers and machines that can run MITgcm.
290        
291  \item \texttt{utils}: this directory contains various utilities. The  \item \texttt{utils}: this directory contains various utilities. The
292    subdirectory \texttt{knudsen2} contains code and a makefile that    subdirectory \texttt{knudsen2} contains code and a makefile that
# Line 328  structure). Line 295  structure).
295    \texttt{matlab} subdirectory contains matlab scripts for reading    \texttt{matlab} subdirectory contains matlab scripts for reading
296    model output directly into matlab. \texttt{scripts} contains C-shell    model output directly into matlab. \texttt{scripts} contains C-shell
297    post-processing scripts for joining processor-based and tiled-based    post-processing scripts for joining processor-based and tiled-based
298    model output.    model output. The subdirectory exch2 contains the code needed for
299      the exch2 package to work with different combinations of domain
300      decompositions.
301        
302  \item \texttt{verification}: this directory contains the model  \item \texttt{verification}: this directory contains the model
303    examples. See section \ref{sect:modelExamples}.    examples. See section \ref{sect:modelExamples}.
304    
305  \end{itemize}  \item \texttt{jobs}: contains sample job scripts for running MITgcm.
   
 \section[MITgcm Example Experiments]{Example experiments}  
 \label{sect:modelExamples}  
 \begin{rawhtml}  
 <!-- CMIREDIR:modelExamples: -->  
 \end{rawhtml}  
   
 %% 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 \texttt{verification}. Each example is briefly described  
 below.  
   
 \subsection{Full list of model examples}  
   
 \begin{enumerate}  
     
 \item \texttt{exp0} - single layer, ocean double gyre (barotropic with  
   free-surface). This experiment is described in detail in section  
   \ref{sect:eg-baro}.  
   
 \item \texttt{exp1} - Four layer, ocean double gyre. This experiment  
   is described in detail in section \ref{sect:eg-baroc}.  
     
 \item \texttt{exp2} - 4x4 degree global ocean simulation with steady  
   climatological forcing. This experiment is described in detail in  
   section \ref{sect:eg-global}.  
     
 \item \texttt{exp4} - Flow over a Gaussian bump in open-water or  
   channel with open boundaries.  
     
 \item \texttt{exp5} - Inhomogenously forced ocean convection in a  
   doubly periodic box.  
   
 \item \texttt{front\_relax} - Relaxation of an ocean thermal front (test for  
 Gent/McWilliams scheme). 2D (Y-Z).  
   
 \item \texttt{internal wave} - Ocean internal wave forced by open  
   boundary conditions.  
     
 \item \texttt{natl\_box} - Eastern subtropical North Atlantic with KPP  
   scheme; 1 month integration  
306        
307  \item \texttt{hs94.1x64x5} - Zonal averaged atmosphere using Held and  \item \texttt{lsopt}: Line search code used for optimization.
   Suarez '94 forcing.  
308        
309  \item \texttt{hs94.128x64x5} - 3D atmosphere dynamics using Held and  \item \texttt{optim}: Interface between MITgcm and line search code.
   Suarez '94 forcing.  
     
 \item \texttt{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and  
   Suarez '94 forcing on the cubed sphere.  
     
 \item \texttt{aim.5l\_zon-ave} - Intermediate Atmospheric physics.  
   Global Zonal Mean configuration, 1x64x5 resolution.  
     
 \item \texttt{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate  
   Atmospheric physics, equatorial Slice configuration.  2D (X-Z).  
     
 \item \texttt{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric  
   physics. 3D Equatorial Channel configuration.  
     
 \item \texttt{aim.5l\_LatLon} - Intermediate Atmospheric physics.  
   Global configuration, on latitude longitude grid with 128x64x5 grid  
   points ($2.8^\circ{\rm degree}$ resolution).  
     
 \item \texttt{adjustment.128x64x1} Barotropic adjustment problem on  
   latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm  
     degree}$ resolution).  
     
 \item \texttt{adjustment.cs-32x32x1} Barotropic adjustment problem on  
   cube sphere grid with 32x32 points per face ( roughly $2.8^\circ{\rm  
     degree}$ resolution).  
     
 \item \texttt{advect\_cs} Two-dimensional passive advection test on  
   cube sphere grid.  
     
 \item \texttt{advect\_xy} Two-dimensional (horizontal plane) passive  
   advection test on Cartesian grid.  
     
 \item \texttt{advect\_yz} Two-dimensional (vertical plane) passive  
   advection test on Cartesian grid.  
     
 \item \texttt{carbon} Simple passive tracer experiment. Includes  
   derivative calculation. Described in detail in section  
   \ref{sect:eg-carbon-ad}.  
   
 \item \texttt{flt\_example} Example of using float package.  
     
 \item \texttt{global\_ocean.90x40x15} Global circulation with GM, flux  
   boundary conditions and poles.  
   
 \item \texttt{global\_ocean\_pressure} Global circulation in pressure  
   coordinate (non-Boussinesq ocean model). Described in detail in  
   section \ref{sect:eg-globalpressure}.  
310        
 \item \texttt{solid-body.cs-32x32x1} Solid body rotation test for cube  
   sphere grid.  
   
 \end{enumerate}  
   
 \subsection{Directory structure of model examples}  
   
 Each example directory has the following subdirectories:  
   
 \begin{itemize}  
 \item \texttt{code}: contains the code particular to the example. At a  
   minimum, this directory includes the following files:  
   
   \begin{itemize}  
   \item \texttt{code/packages.conf}: declares the list of packages or  
     package groups to be used.  If not included, the default version  
     is located in \texttt{pkg/pkg\_default}.  Package groups are  
     simply convenient collections of commonly used packages which are  
     defined in \texttt{pkg/pkg\_default}.  Some packages may require  
     other packages or may require their absence (that is, they are  
     incompatible) and these package dependencies are listed in  
     \texttt{pkg/pkg\_depend}.  
   
   \item \texttt{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to  
     the ``execution environment'' part of the code. The default  
     version is located in \texttt{eesupp/inc}.  
     
   \item \texttt{code/CPP\_OPTIONS.h}: declares CPP keys relative to  
     the ``numerical model'' part of the code. The default version is  
     located in \texttt{model/inc}.  
     
   \item \texttt{code/SIZE.h}: declares size of underlying  
     computational grid.  The default version is located in  
     \texttt{model/inc}.  
   \end{itemize}  
     
   In addition, other include files and subroutines might be present in  
   \texttt{code} depending on the particular experiment. See Section 2  
   for more details.  
     
 \item \texttt{input}: contains the input data files required to run  
   the example. At a minimum, the \texttt{input} directory contains the  
   following files:  
   
   \begin{itemize}  
   \item \texttt{input/data}: this file, written as a namelist,  
     specifies the main parameters for the experiment.  
     
   \item \texttt{input/data.pkg}: contains parameters relative to the  
     packages used in the experiment.  
     
   \item \texttt{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 \texttt{results}: this directory contains the output file  
   \texttt{output.txt} produced by the simulation example. This file is  
   useful for comparison with your own output when you run the  
   experiment.  
311  \end{itemize}  \end{itemize}
312    
 Once you have chosen the example you want to run, you are ready to  
 compile the code.  
   
313  \section[Building MITgcm]{Building the code}  \section[Building MITgcm]{Building the code}
314  \label{sect:buildingCode}  \label{sect:buildingCode}
315  \begin{rawhtml}  \begin{rawhtml}
# Line 550  Through the MITgcm-support list, the MIT Line 353  Through the MITgcm-support list, the MIT
353  provide help writing or modifing ``optfiles''.  And we encourage users  provide help writing or modifing ``optfiles''.  And we encourage users
354  to post new ``optfiles'' (particularly ones for new machines or  to post new ``optfiles'' (particularly ones for new machines or
355  architectures) to the  architectures) to the
356  \begin{rawhtml} <A href=''mailto:MITgcm-support@mitgcm.org"> \end{rawhtml}  \begin{rawhtml} <A href="mailto:MITgcm-support@mitgcm.org"> \end{rawhtml}
357  MITgcm-support@mitgcm.org  MITgcm-support@mitgcm.org
358  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
359  list.  list.
# Line 604  and then calling the executable with: Line 407  and then calling the executable with:
407  where we are re-directing the stream of text output to the file  where we are re-directing the stream of text output to the file
408  \texttt{output.txt}.  \texttt{output.txt}.
409    
410    \subsection{Building/compiling the code elsewhere}
411    
412    In the example above (section \ref{sect:buildingCode}) we built the
413    executable in the {\em input} directory of the experiment for
414    convenience. You can also configure and compile the code in other
415    locations, for example on a scratch disk with out having to copy the
416    entire source tree. The only requirement to do so is you have {\tt
417      genmake2} in your path or you know the absolute path to {\tt
418      genmake2}.
419    
420    The following sections outline some possible methods of organizing
421    your source and data.
422    
423    \subsubsection{Building from the {\em ../code directory}}
424    
425    This is just as simple as building in the {\em input/} directory:
426    \begin{verbatim}
427    % cd verification/exp2/code
428    % ../../../tools/genmake2
429    % make depend
430    % make
431    \end{verbatim}
432    However, to run the model the executable ({\em mitgcmuv}) and input
433    files must be in the same place. If you only have one calculation to make:
434    \begin{verbatim}
435    % cd ../input
436    % cp ../code/mitgcmuv ./
437    % ./mitgcmuv > output.txt
438    \end{verbatim}
439    or if you will be making multiple runs with the same executable:
440    \begin{verbatim}
441    % cd ../
442    % cp -r input run1
443    % cp code/mitgcmuv run1
444    % cd run1
445    % ./mitgcmuv > output.txt
446    \end{verbatim}
447    
448    \subsubsection{Building from a new directory}
449    
450    Since the {\em input} directory contains input files it is often more
451    useful to keep {\em input} pristine and build in a new directory
452    within {\em verification/exp2/}:
453    \begin{verbatim}
454    % cd verification/exp2
455    % mkdir build
456    % cd build
457    % ../../../tools/genmake2 -mods=../code
458    % make depend
459    % make
460    \end{verbatim}
461    This builds the code exactly as before but this time you need to copy
462    either the executable or the input files or both in order to run the
463    model. For example,
464    \begin{verbatim}
465    % cp ../input/* ./
466    % ./mitgcmuv > output.txt
467    \end{verbatim}
468    or if you tend to make multiple runs with the same executable then
469    running in a new directory each time might be more appropriate:
470    \begin{verbatim}
471    % cd ../
472    % mkdir run1
473    % cp build/mitgcmuv run1/
474    % cp input/* run1/
475    % cd run1
476    % ./mitgcmuv > output.txt
477    \end{verbatim}
478    
479    \subsubsection{Building on a scratch disk}
480    
481    Model object files and output data can use up large amounts of disk
482    space so it is often the case that you will be operating on a large
483    scratch disk. Assuming the model source is in {\em ~/MITgcm} then the
484    following commands will build the model in {\em /scratch/exp2-run1}:
485    \begin{verbatim}
486    % cd /scratch/exp2-run1
487    % ~/MITgcm/tools/genmake2 -rootdir=~/MITgcm \
488      -mods=~/MITgcm/verification/exp2/code
489    % make depend
490    % make
491    \end{verbatim}
492    To run the model here, you'll need the input files:
493    \begin{verbatim}
494    % cp ~/MITgcm/verification/exp2/input/* ./
495    % ./mitgcmuv > output.txt
496    \end{verbatim}
497    
498    As before, you could build in one directory and make multiple runs of
499    the one experiment:
500    \begin{verbatim}
501    % cd /scratch/exp2
502    % mkdir build
503    % cd build
504    % ~/MITgcm/tools/genmake2 -rootdir=~/MITgcm \
505      -mods=~/MITgcm/verification/exp2/code
506    % make depend
507    % make
508    % cd ../
509    % cp -r ~/MITgcm/verification/exp2/input run2
510    % cd run2
511    % ./mitgcmuv > output.txt
512    \end{verbatim}
513    
514    
515    \subsection{Using \texttt{genmake2}}
516    \label{sect:genmake}
517    
518    To compile the code, first use the program \texttt{genmake2} (located
519    in the \texttt{tools} directory) to generate a Makefile.
520    \texttt{genmake2} is a shell script written to work with all
521    ``sh''--compatible shells including bash v1, bash v2, and Bourne.
522    Internally, \texttt{genmake2} determines the locations of needed
523    files, the compiler, compiler options, libraries, and Unix tools.  It
524    relies upon a number of ``optfiles'' located in the
525    \texttt{tools/build\_options} directory.
526    
527    The purpose of the optfiles is to provide all the compilation options
528    for particular ``platforms'' (where ``platform'' roughly means the
529    combination of the hardware and the compiler) and code configurations.
530    Given the combinations of possible compilers and library dependencies
531    ({\it eg.}  MPI and NetCDF) there may be numerous optfiles available
532    for a single machine.  The naming scheme for the majority of the
533    optfiles shipped with the code is
534    \begin{center}
535      {\bf OS\_HARDWARE\_COMPILER }
536    \end{center}
537    where
538    \begin{description}
539    \item[OS] is the name of the operating system (generally the
540      lower-case output of the {\tt 'uname'} command)
541    \item[HARDWARE] is a string that describes the CPU type and
542      corresponds to output from the  {\tt 'uname -m'} command:
543      \begin{description}
544      \item[ia32] is for ``x86'' machines such as i386, i486, i586, i686,
545        and athlon
546      \item[ia64] is for Intel IA64 systems (eg. Itanium, Itanium2)
547      \item[amd64] is AMD x86\_64 systems
548      \item[ppc] is for Mac PowerPC systems
549      \end{description}
550    \item[COMPILER] is the compiler name (generally, the name of the
551      FORTRAN executable)
552    \end{description}
553    
554    In many cases, the default optfiles are sufficient and will result in
555    usable Makefiles.  However, for some machines or code configurations,
556    new ``optfiles'' must be written. To create a new optfile, it is
557    generally best to start with one of the defaults and modify it to suit
558    your needs.  Like \texttt{genmake2}, the optfiles are all written
559    using a simple ``sh''--compatible syntax.  While nearly all variables
560    used within \texttt{genmake2} may be specified in the optfiles, the
561    critical ones that should be defined are:
562    
563    \begin{description}
564    \item[FC] the FORTRAN compiler (executable) to use
565    \item[DEFINES] the command-line DEFINE options passed to the compiler
566    \item[CPP] the C pre-processor to use
567    \item[NOOPTFLAGS] options flags for special files that should not be
568      optimized
569    \end{description}
570    
571    For example, the optfile for a typical Red Hat Linux machine (``ia32''
572    architecture) using the GCC (g77) compiler is
573    \begin{verbatim}
574    FC=g77
575    DEFINES='-D_BYTESWAPIO -DWORDLENGTH=4'
576    CPP='cpp  -traditional -P'
577    NOOPTFLAGS='-O0'
578    #  For IEEE, use the "-ffloat-store" option
579    if test "x$IEEE" = x ; then
580        FFLAGS='-Wimplicit -Wunused -Wuninitialized'
581        FOPTIM='-O3 -malign-double -funroll-loops'
582    else
583        FFLAGS='-Wimplicit -Wunused -ffloat-store'
584        FOPTIM='-O0 -malign-double'
585    fi
586    \end{verbatim}
587    
588    If you write an optfile for an unrepresented machine or compiler, you
589    are strongly encouraged to submit the optfile to the MITgcm project
590    for inclusion.  Please send the file to the
591    \begin{rawhtml} <A href="mail-to:MITgcm-support@mitgcm.org"> \end{rawhtml}
592    \begin{center}
593      MITgcm-support@mitgcm.org
594    \end{center}
595    \begin{rawhtml} </A> \end{rawhtml}
596    mailing list.
597    
598    In addition to the optfiles, \texttt{genmake2} supports a number of
599    helpful command-line options.  A complete list of these options can be
600    obtained from:
601    \begin{verbatim}
602    % genmake2 -h
603    \end{verbatim}
604    
605    The most important command-line options are:
606    \begin{description}
607      
608    \item[\texttt{--optfile=/PATH/FILENAME}] specifies the optfile that
609      should be used for a particular build.
610      
611      If no "optfile" is specified (either through the command line or the
612      MITGCM\_OPTFILE environment variable), genmake2 will try to make a
613      reasonable guess from the list provided in {\em
614        tools/build\_options}.  The method used for making this guess is
615      to first determine the combination of operating system and hardware
616      (eg. "linux\_ia32") and then find a working FORTRAN compiler within
617      the user's path.  When these three items have been identified,
618      genmake2 will try to find an optfile that has a matching name.
619      
620    \item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default
621      set of packages to be used.  The normal order of precedence for
622      packages is as follows:
623      \begin{enumerate}
624      \item If available, the command line (\texttt{--pdefault}) settings
625        over-rule any others.
626    
627      \item Next, \texttt{genmake2} will look for a file named
628        ``\texttt{packages.conf}'' in the local directory or in any of the
629        directories specified with the \texttt{--mods} option.
630        
631      \item Finally, if neither of the above are available,
632        \texttt{genmake2} will use the \texttt{/pkg/pkg\_default} file.
633      \end{enumerate}
634      
635    \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file
636      used for packages.
637      
638      If not specified, the default dependency file {\em pkg/pkg\_depend}
639      is used.  The syntax for this file is parsed on a line-by-line basis
640      where each line containes either a comment ("\#") or a simple
641      "PKGNAME1 (+|-)PKGNAME2" pairwise rule where the "+" or "-" symbol
642      specifies a "must be used with" or a "must not be used with"
643      relationship, respectively.  If no rule is specified, then it is
644      assumed that the two packages are compatible and will function
645      either with or without each other.
646      
647    \item[\texttt{--adof=/path/to/file}] specifies the "adjoint" or
648      automatic differentiation options file to be used.  The file is
649      analogous to the ``optfile'' defined above but it specifies
650      information for the AD build process.
651      
652      The default file is located in {\em
653        tools/adjoint\_options/adjoint\_default} and it defines the "TAF"
654      and "TAMC" compilers.  An alternate version is also available at
655      {\em tools/adjoint\_options/adjoint\_staf} that selects the newer
656      "STAF" compiler.  As with any compilers, it is helpful to have their
657      directories listed in your {\tt \$PATH} environment variable.
658      
659    \item[\texttt{--mods='DIR1 DIR2 DIR3 ...'}] specifies a list of
660      directories containing ``modifications''.  These directories contain
661      files with names that may (or may not) exist in the main MITgcm
662      source tree but will be overridden by any identically-named sources
663      within the ``MODS'' directories.
664      
665      The order of precedence for this "name-hiding" is as follows:
666      \begin{itemize}
667      \item ``MODS'' directories (in the order given)
668      \item Packages either explicitly specified or provided by default
669        (in the order given)
670      \item Packages included due to package dependencies (in the order
671        that that package dependencies are parsed)
672      \item The "standard dirs" (which may have been specified by the
673        ``-standarddirs'' option)
674      \end{itemize}
675      
676    \item[\texttt{--mpi}] This option enables certain MPI features (using
677      CPP \texttt{\#define}s) within the code and is necessary for MPI
678      builds (see Section \ref{sect:mpi-build}).
679      
680    \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of
681      soft-links and other bugs common with the \texttt{make} versions
682      provided by commercial Unix vendors, GNU \texttt{make} (sometimes
683      called \texttt{gmake}) should be preferred.  This option provides a
684      means for specifying the make executable to be used.
685      
686    \item[\texttt{--bash=/path/to/sh}] On some (usually older UNIX)
687      machines, the ``bash'' shell is unavailable.  To run on these
688      systems, \texttt{genmake2} can be invoked using an ``sh'' (that is,
689      a Bourne, POSIX, or compatible) shell.  The syntax in these
690      circumstances is:
691      \begin{center}
692        \texttt{\%  /bin/sh genmake2 -bash=/bin/sh [...options...]}
693      \end{center}
694      where \texttt{/bin/sh} can be replaced with the full path and name
695      of the desired shell.
696    
697    \end{description}
698    
699    
700    \subsection{Building with MPI}
701    \label{sect:mpi-build}
702    
703    Building MITgcm to use MPI libraries can be complicated due to the
704    variety of different MPI implementations available, their dependencies
705    or interactions with different compilers, and their often ad-hoc
706    locations within file systems.  For these reasons, its generally a
707    good idea to start by finding and reading the documentation for your
708    machine(s) and, if necessary, seeking help from your local systems
709    administrator.
710    
711    The steps for building MITgcm with MPI support are:
712    \begin{enumerate}
713      
714    \item Determine the locations of your MPI-enabled compiler and/or MPI
715      libraries and put them into an options file as described in Section
716      \ref{sect:genmake}.  One can start with one of the examples in:
717      \begin{rawhtml} <A
718        href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/tools/build_options/">
719      \end{rawhtml}
720      \begin{center}
721        \texttt{MITgcm/tools/build\_options/}
722      \end{center}
723      \begin{rawhtml} </A> \end{rawhtml}
724      such as \texttt{linux\_ia32\_g77+mpi\_cg01} or
725      \texttt{linux\_ia64\_efc+mpi} and then edit it to suit the machine at
726      hand.  You may need help from your user guide or local systems
727      administrator to determine the exact location of the MPI libraries.
728      If libraries are not installed, MPI implementations and related
729      tools are available including:
730      \begin{itemize}
731      \item \begin{rawhtml} <A
732          href="http://www-unix.mcs.anl.gov/mpi/mpich/">
733        \end{rawhtml}
734        MPICH
735        \begin{rawhtml} </A> \end{rawhtml}
736    
737      \item \begin{rawhtml} <A
738          href="http://www.lam-mpi.org/">
739        \end{rawhtml}
740        LAM/MPI
741        \begin{rawhtml} </A> \end{rawhtml}
742    
743      \item \begin{rawhtml} <A
744          href="http://www.osc.edu/~pw/mpiexec/">
745        \end{rawhtml}
746        MPIexec
747        \begin{rawhtml} </A> \end{rawhtml}
748      \end{itemize}
749      
750    \item Build the code with the \texttt{genmake2} \texttt{-mpi} option
751      (see Section \ref{sect:genmake}) using commands such as:
752    {\footnotesize \begin{verbatim}
753      %  ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE
754      %  make depend
755      %  make
756    \end{verbatim} }
757      
758    \item Run the code with the appropriate MPI ``run'' or ``exec''
759      program provided with your particular implementation of MPI.
760      Typical MPI packages such as MPICH will use something like:
761    \begin{verbatim}
762      %  mpirun -np 4 -machinefile mf ./mitgcmuv
763    \end{verbatim}
764      Sightly more complicated scripts may be needed for many machines
765      since execution of the code may be controlled by both the MPI
766      library and a job scheduling and queueing system such as PBS,
767      LoadLeveller, Condor, or any of a number of similar tools.  A few
768      example scripts (those used for our \begin{rawhtml} <A
769        href="http://mitgcm.org/testing.html"> \end{rawhtml}regular
770      verification runs\begin{rawhtml} </A> \end{rawhtml}) are available
771      at:
772      \begin{rawhtml} <A
773        href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
774      \end{rawhtml}
775      {\footnotesize \tt
776        http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm\_contrib/test\_scripts/ }
777      \begin{rawhtml} </A> \end{rawhtml}
778    
779    \end{enumerate}
780    
781    An example of the above process on the MITgcm cluster (``cg01'') using
782    the GNU g77 compiler and the mpich MPI library is:
783    
784    {\footnotesize \begin{verbatim}
785      %  cd MITgcm/verification/exp5
786      %  mkdir build
787      %  cd build
788      %  ../../../tools/genmake2 -mpi -mods=../code \
789           -of=../../../tools/build_options/linux_ia32_g77+mpi_cg01
790      %  make depend
791      %  make
792      %  cd ../input
793      %  /usr/local/pkg/mpi/mpi-1.2.4..8a-gm-1.5/g77/bin/mpirun.ch_gm \
794           -machinefile mf --gm-kill 5 -v -np 2  ../build/mitgcmuv
795    \end{verbatim} }
796    
797  \section[Running MITgcm]{Running the model in prognostic mode}  \section[Running MITgcm]{Running the model in prognostic mode}
798  \label{sect:runModel}  \label{sect:runModel}
# Line 658  package.  At a minimum, the instantaneou Line 847  package.  At a minimum, the instantaneou
847  written out, which is made of the following files:  written out, which is made of the following files:
848    
849  \begin{itemize}  \begin{itemize}
850  \item \texttt{U.00000nIter} - zonal component of velocity field (m/s and $>  \item \texttt{U.00000nIter} - zonal component of velocity field (m/s
851  0 $ eastward).    and positive eastward).
852    
853  \item \texttt{V.00000nIter} - meridional component of velocity field (m/s  \item \texttt{V.00000nIter} - meridional component of velocity field
854  and $> 0$ northward).    (m/s and positive northward).
855    
856  \item \texttt{W.00000nIter} - vertical component of velocity field (ocean:  \item \texttt{W.00000nIter} - vertical component of velocity field
857  m/s and $> 0$ upward, atmosphere: Pa/s and $> 0$ towards increasing pressure    (ocean: m/s and positive upward, atmosphere: Pa/s and positive
858  i.e. downward).    towards increasing pressure i.e. downward).
859    
860  \item \texttt{T.00000nIter} - potential temperature (ocean: $^{0}$C,  \item \texttt{T.00000nIter} - potential temperature (ocean:
861  atmosphere: $^{0}$K).    $^{\circ}\mathrm{C}$, atmosphere: $^{\circ}\mathrm{K}$).
862    
863  \item \texttt{S.00000nIter} - ocean: salinity (psu), atmosphere: water vapor  \item \texttt{S.00000nIter} - ocean: salinity (psu), atmosphere: water
864  (g/kg).    vapor (g/kg).
865    
866  \item \texttt{Eta.00000nIter} - ocean: surface elevation (m), atmosphere:  \item \texttt{Eta.00000nIter} - ocean: surface elevation (m),
867  surface pressure anomaly (Pa).    atmosphere: surface pressure anomaly (Pa).
868  \end{itemize}  \end{itemize}
869    
870  The chain \texttt{00000nIter} consists of ten figures that specify the  The chain \texttt{00000nIter} consists of ten figures that specify the
871  iteration number at which the output is written out. For example, \texttt{%  iteration number at which the output is written out. For example,
872  U.0000000300} is the zonal velocity at iteration 300.  \texttt{U.0000000300} is the zonal velocity at iteration 300.
873    
874  In addition, a ``pickup'' or ``checkpoint'' file called:  In addition, a ``pickup'' or ``checkpoint'' file called:
875    
# Line 703  as the pickup files but are named differ Line 892  as the pickup files but are named differ
892  used to restart the model but are overwritten every other time they are  used to restart the model but are overwritten every other time they are
893  output to save disk space during long integrations.  output to save disk space during long integrations.
894    
   
   
895  \subsubsection{MNC output files}  \subsubsection{MNC output files}
896    
897  Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output  Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output
898  is usually (though not necessarily) placed within a subdirectory with  is usually (though not necessarily) placed within a subdirectory with
899  a name such as \texttt{mnc\_test\_\${DATE}\_\${SEQ}}.  The files  a name such as \texttt{mnc\_test\_\${DATE}\_\${SEQ}}.  
 within this subdirectory are all in the ``self-describing'' netCDF  
 format and can thus be browsed and/or plotted using tools such as:  
 \begin{itemize}  
 \item \texttt{ncdump} is a utility which is typically included  
   with every netCDF install:  
   \begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}  
 \begin{verbatim}  
      http://www.unidata.ucar.edu/packages/netcdf/  
 \end{verbatim}  
   \begin{rawhtml} </A> \end{rawhtml} and it converts the netCDF  
   binaries into formatted ASCII text files.  
   
 \item \texttt{ncview} utility is a very convenient and quick way  
   to plot netCDF data and it runs on most OSes:  
   \begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml}  
 \begin{verbatim}  
      http://meteora.ucsd.edu/~pierce/ncview_home_page.html  
 \end{verbatim}  
   \begin{rawhtml} </A> \end{rawhtml}  
     
 \item MatLAB(c) and other common post-processing environments provide  
   various netCDF interfaces including:  
   \begin{rawhtml} <A href="http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html"> \end{rawhtml}  
 \begin{verbatim}  
 http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html  
 \end{verbatim}  
   \begin{rawhtml} </A> \end{rawhtml}  
 \end{itemize}  
   
900    
901  \subsection{Looking at the output}  \subsection{Looking at the output}
902    
# Line 774  Some examples of reading and visualizing Line 932  Some examples of reading and visualizing
932  Similar scripts for netCDF output (\texttt{rdmnc.m}) are available and  Similar scripts for netCDF output (\texttt{rdmnc.m}) are available and
933  they are described in Section \ref{sec:pkg:mnc}.  they are described in Section \ref{sec:pkg:mnc}.
934    
935    The MNC output files are all in the ``self-describing'' netCDF
936    format and can thus be browsed and/or plotted using tools such as:
937    \begin{itemize}
938    \item \texttt{ncdump} is a utility which is typically included
939      with every netCDF install:
940      \begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}
941    \begin{verbatim}
942    http://www.unidata.ucar.edu/packages/netcdf/
943    \end{verbatim}
944      \begin{rawhtml} </A> \end{rawhtml} and it converts the netCDF
945      binaries into formatted ASCII text files.
946    
947    \item \texttt{ncview} utility is a very convenient and quick way
948      to plot netCDF data and it runs on most OSes:
949      \begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml}
950    \begin{verbatim}
951    http://meteora.ucsd.edu/~pierce/ncview_home_page.html
952    \end{verbatim}
953      \begin{rawhtml} </A> \end{rawhtml}
954      
955    \item MatLAB(c) and other common post-processing environments provide
956      various netCDF interfaces including:
957      \begin{rawhtml} <A href="http://mexcdf.sourceforge.net/"> \end{rawhtml}
958    \begin{verbatim}
959    http://mexcdf.sourceforge.net/
960    \end{verbatim}
961      \begin{rawhtml} </A> \end{rawhtml}
962      \begin{rawhtml} <A href="http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html"> \end{rawhtml}
963    \begin{verbatim}
964    http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html
965    \end{verbatim}
966      \begin{rawhtml} </A> \end{rawhtml}
967    \end{itemize}
968    
Legend:
Removed from v.1.31  
changed lines
  Added in v.1.39
  ViewVC Help
Powered by ViewVC 1.1.22