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