/[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.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 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 175  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 262  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 286  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 311  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 327  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    \item \texttt{jobs}: contains sample job scripts for running MITgcm.
306      
307    \item \texttt{lsopt}: Line search code used for optimization.
308      
309    \item \texttt{optim}: Interface between MITgcm and line search code.
310      
311  \end{itemize}  \end{itemize}
312    
313  \section[Building MITgcm]{Building the code}  \section[Building MITgcm]{Building the code}
# Line 916  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://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}  
   
900    
901  \subsection{Looking at the output}  \subsection{Looking at the output}
902    
# Line 992  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.36  
changed lines
  Added in v.1.39
  ViewVC Help
Powered by ViewVC 1.1.22