/[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.36 by molod, Tue Jun 27 19:08:22 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 21  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 40  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 125  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 162  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 175  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 262  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 286  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 311  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 327  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    \item \texttt{jobs}: contains sample job scripts for running MITgcm.
307      
308    \item \texttt{lsopt}: Line search code used for optimization.
309      
310    \item \texttt{optim}: Interface between MITgcm and line search code.
311      
312  \end{itemize}  \end{itemize}
313    
314  \section[Building MITgcm]{Building the code}  \section[Building MITgcm]{Building the code}
# Line 739  The steps for building MITgcm with MPI s Line 716  The steps for building MITgcm with MPI s
716    libraries and put them into an options file as described in Section    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:    \ref{sect:genmake}.  One can start with one of the examples in:
718    \begin{rawhtml} <A    \begin{rawhtml} <A
719      href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/tools/build_options/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">
720    \end{rawhtml}    \end{rawhtml}
721    \begin{center}    \begin{center}
722      \texttt{MITgcm/tools/build\_options/}      \texttt{MITgcm/tools/build\_options/}
# Line 790  The steps for building MITgcm with MPI s Line 767  The steps for building MITgcm with MPI s
767    library and a job scheduling and queueing system such as PBS,    library and a job scheduling and queueing system such as PBS,
768    LoadLeveller, Condor, or any of a number of similar tools.  A few    LoadLeveller, Condor, or any of a number of similar tools.  A few
769    example scripts (those used for our \begin{rawhtml} <A    example scripts (those used for our \begin{rawhtml} <A
770      href="http://mitgcm.org/testing.html"> \end{rawhtml}regular      href="http://mitgcm.org/public/testing.html"> \end{rawhtml}regular
771    verification runs\begin{rawhtml} </A> \end{rawhtml}) are available    verification runs\begin{rawhtml} </A> \end{rawhtml}) are available
772    at:    at:
773    \begin{rawhtml} <A    \begin{rawhtml} <A
774      href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
775    \end{rawhtml}    \end{rawhtml}
776    {\footnotesize \tt    {\footnotesize \tt
777      http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm\_contrib/test\_scripts/ }      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}    \begin{rawhtml} </A> \end{rawhtml}
786    
787  \end{enumerate}  \end{enumerate}
# Line 916  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://mexcdf.sourceforge.net/"> \end{rawhtml}  
 \begin{verbatim}  
 http://mexcdf.sourceforge.net/  
 \end{verbatim}  
   \begin{rawhtml} </A> \end{rawhtml}  
   \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 992  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.36  
changed lines
  Added in v.1.41
  ViewVC Help
Powered by ViewVC 1.1.22