/[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.37 by molod, Wed Jun 28 16:48:19 2006 UTC revision 1.43 by jmc, Fri May 28 21:04:18 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 104  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/viewvc/MITgcm/MITgcm/" target="idontexist"> \end{rawhtml}
106  \begin{verbatim}  \begin{verbatim}
107  http://mitgcm.org/source_code.html  http://mitgcm.org/viewvc/MITgcm/MITgcm/
108  \end{verbatim}  \end{verbatim}
109  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
110    
# Line 141  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/public/using_cvs.html" target="idontexist"> \end{rawhtml}
143  here  here
144  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
145  .  .
# Line 225  with. So please be sure you understand w Line 223  with. So please be sure you understand w
223    
224  If you do not have CVS on your system, you can download the model as a  If you do not have CVS on your system, you can download the model as a
225  tar file from the web site at:  tar file from the web site at:
226  \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}  \begin{rawhtml} <A href=http://mitgcm.org/download/ target="idontexist"> \end{rawhtml}
227  \begin{verbatim}  \begin{verbatim}
228  http://mitgcm.org/download/  http://mitgcm.org/download/
229  \end{verbatim}  \end{verbatim}
# Line 521  To compile the code, first use the progr Line 519  To compile the code, first use the progr
519  in the \texttt{tools} directory) to generate a Makefile.  in the \texttt{tools} directory) to generate a Makefile.
520  \texttt{genmake2} is a shell script written to work with all  \texttt{genmake2} is a shell script written to work with all
521  ``sh''--compatible shells including bash v1, bash v2, and Bourne.  ``sh''--compatible shells including bash v1, bash v2, and Bourne.
522  Internally, \texttt{genmake2} determines the locations of needed  %Internally, \texttt{genmake2} determines the locations of needed
523  files, the compiler, compiler options, libraries, and Unix tools.  It  %files, the compiler, compiler options, libraries, and Unix tools.  It
524  relies upon a number of ``optfiles'' located in the  %relies upon a number of ``optfiles'' located in the
525  \texttt{tools/build\_options} directory.  %\texttt{tools/build\_options} directory.
526    \texttt{genmake2} parses information from the following sources:
527    \begin{description}
528    \item[-] a {\em gemake\_local} file if one is found in the current
529      directory
530    \item[-] command-line options
531    \item[-] an "options file" as specified by the command-line option
532      \texttt{--optfile=/PATH/FILENAME}
533    \item[-] a {\em packages.conf} file (if one is found) with the
534      specific list of packages to compile. The search path for
535      file {\em packages.conf} is, first, the current directory and
536      then each of the "MODS" directories in the given order (see below).
537    \end{description}
538    
539    \subsubsection{Optfiles in \texttt{tools/build\_options} directory:}
540    
541  The purpose of the optfiles is to provide all the compilation options  The purpose of the optfiles is to provide all the compilation options
542  for particular ``platforms'' (where ``platform'' roughly means the  for particular ``platforms'' (where ``platform'' roughly means the
# Line 597  for inclusion.  Please send the file to Line 609  for inclusion.  Please send the file to
609  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
610  mailing list.  mailing list.
611    
612    \subsubsection{Command-line options:}
613    
614  In addition to the optfiles, \texttt{genmake2} supports a number of  In addition to the optfiles, \texttt{genmake2} supports a number of
615  helpful command-line options.  A complete list of these options can be  helpful command-line options.  A complete list of these options can be
616  obtained from:  obtained from:
# Line 619  The most important command-line options Line 633  The most important command-line options
633    the user's path.  When these three items have been identified,    the user's path.  When these three items have been identified,
634    genmake2 will try to find an optfile that has a matching name.    genmake2 will try to find an optfile that has a matching name.
635        
636  \item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default  \item[\texttt{--mods='DIR1 DIR2 DIR3 ...'}] specifies a list of
637    set of packages to be used.  The normal order of precedence for    directories containing ``modifications''.  These directories contain
638    packages is as follows:    files with names that may (or may not) exist in the main MITgcm
639    \begin{enumerate}    source tree but will be overridden by any identically-named sources
640    \item If available, the command line (\texttt{--pdefault}) settings    within the ``MODS'' directories.
641      over-rule any others.    
642      The order of precedence for this "name-hiding" is as follows:
643    \item Next, \texttt{genmake2} will look for a file named    \begin{itemize}
644      ``\texttt{packages.conf}'' in the local directory or in any of the    \item ``MODS'' directories (in the order given)
645      directories specified with the \texttt{--mods} option.    \item Packages either explicitly specified or provided by default
646            (in the order given)
647    \item Finally, if neither of the above are available,    \item Packages included due to package dependencies (in the order
648      \texttt{genmake2} will use the \texttt{/pkg/pkg\_default} file.      that that package dependencies are parsed)
649    \end{enumerate}    \item The "standard dirs" (which may have been specified by the
650        ``-standarddirs'' option)
651      \end{itemize}
652        
653    \item[\texttt{--pgroups=/PATH/FILENAME}] specifies the file
654      where package groups are defined. If not set, the package-groups
655      definition will be read from {\em pkg/pkg\_groups}.
656      It also contains the default list of packages (defined
657      as the group ``{\it default\_pkg\_list}'' which is used
658      when no specific package list ({\em packages.conf})
659      is found in current directory or in any "MODS" directory.
660    
661  \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file  \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file
662    used for packages.    used for packages.
663        
# Line 658  The most important command-line options Line 682  The most important command-line options
682    "STAF" compiler.  As with any compilers, it is helpful to have their    "STAF" compiler.  As with any compilers, it is helpful to have their
683    directories listed in your {\tt \$PATH} environment variable.    directories listed in your {\tt \$PATH} environment variable.
684        
 \item[\texttt{--mods='DIR1 DIR2 DIR3 ...'}] specifies a list of  
   directories containing ``modifications''.  These directories contain  
   files with names that may (or may not) exist in the main MITgcm  
   source tree but will be overridden by any identically-named sources  
   within the ``MODS'' directories.  
     
   The order of precedence for this "name-hiding" is as follows:  
   \begin{itemize}  
   \item ``MODS'' directories (in the order given)  
   \item Packages either explicitly specified or provided by default  
     (in the order given)  
   \item Packages included due to package dependencies (in the order  
     that that package dependencies are parsed)  
   \item The "standard dirs" (which may have been specified by the  
     ``-standarddirs'' option)  
   \end{itemize}  
     
685  \item[\texttt{--mpi}] This option enables certain MPI features (using  \item[\texttt{--mpi}] This option enables certain MPI features (using
686    CPP \texttt{\#define}s) within the code and is necessary for MPI    CPP \texttt{\#define}s) within the code and is necessary for MPI
687    builds (see Section \ref{sect:mpi-build}).    builds (see Section \ref{sect:mpi-build}).
# Line 717  The steps for building MITgcm with MPI s Line 724  The steps for building MITgcm with MPI s
724    libraries and put them into an options file as described in Section    libraries and put them into an options file as described in Section
725    \ref{sect:genmake}.  One can start with one of the examples in:    \ref{sect:genmake}.  One can start with one of the examples in:
726    \begin{rawhtml} <A    \begin{rawhtml} <A
727      href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/tools/build_options/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">
728    \end{rawhtml}    \end{rawhtml}
729    \begin{center}    \begin{center}
730      \texttt{MITgcm/tools/build\_options/}      \texttt{MITgcm/tools/build\_options/}
# Line 768  The steps for building MITgcm with MPI s Line 775  The steps for building MITgcm with MPI s
775    library and a job scheduling and queueing system such as PBS,    library and a job scheduling and queueing system such as PBS,
776    LoadLeveller, Condor, or any of a number of similar tools.  A few    LoadLeveller, Condor, or any of a number of similar tools.  A few
777    example scripts (those used for our \begin{rawhtml} <A    example scripts (those used for our \begin{rawhtml} <A
778      href="http://mitgcm.org/testing.html"> \end{rawhtml}regular      href="http://mitgcm.org/public/testing.html"> \end{rawhtml}regular
779    verification runs\begin{rawhtml} </A> \end{rawhtml}) are available    verification runs\begin{rawhtml} </A> \end{rawhtml}) are available
780    at:    at:
781    \begin{rawhtml} <A    \begin{rawhtml} <A
782      href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
783      \end{rawhtml}
784      {\footnotesize \tt
785        http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example\_scripts/ }
786      \begin{rawhtml} </A> \end{rawhtml}
787      or at:
788      \begin{rawhtml} <A
789        href="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
790    \end{rawhtml}    \end{rawhtml}
791    {\footnotesize \tt    {\footnotesize \tt
792      http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm\_contrib/test\_scripts/ }      http://mitgcm.org/viewvc/MITgcm/MITgcm\_contrib/test\_scripts/ }
793    \begin{rawhtml} </A> \end{rawhtml}    \begin{rawhtml} </A> \end{rawhtml}
794    
795  \end{enumerate}  \end{enumerate}
# Line 894  as the pickup files but are named differ Line 908  as the pickup files but are named differ
908  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
909  output to save disk space during long integrations.  output to save disk space during long integrations.
910    
   
   
911  \subsubsection{MNC output files}  \subsubsection{MNC output files}
912    
913  Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output  Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output
914  is usually (though not necessarily) placed within a subdirectory with  is usually (though not necessarily) placed within a subdirectory with
915  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}  
   
916    
917  \subsection{Looking at the output}  \subsection{Looking at the output}
918    
# Line 970  Some examples of reading and visualizing Line 948  Some examples of reading and visualizing
948  Similar scripts for netCDF output (\texttt{rdmnc.m}) are available and  Similar scripts for netCDF output (\texttt{rdmnc.m}) are available and
949  they are described in Section \ref{sec:pkg:mnc}.  they are described in Section \ref{sec:pkg:mnc}.
950    
951    The MNC output files are all in the ``self-describing'' netCDF
952    format and can thus be browsed and/or plotted using tools such as:
953    \begin{itemize}
954    \item \texttt{ncdump} is a utility which is typically included
955      with every netCDF install:
956      \begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}
957    \begin{verbatim}
958    http://www.unidata.ucar.edu/packages/netcdf/
959    \end{verbatim}
960      \begin{rawhtml} </A> \end{rawhtml} and it converts the netCDF
961      binaries into formatted ASCII text files.
962    
963    \item \texttt{ncview} utility is a very convenient and quick way
964      to plot netCDF data and it runs on most OSes:
965      \begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml}
966    \begin{verbatim}
967    http://meteora.ucsd.edu/~pierce/ncview_home_page.html
968    \end{verbatim}
969      \begin{rawhtml} </A> \end{rawhtml}
970      
971    \item MatLAB(c) and other common post-processing environments provide
972      various netCDF interfaces including:
973      \begin{rawhtml} <A href="http://mexcdf.sourceforge.net/"> \end{rawhtml}
974    \begin{verbatim}
975    http://mexcdf.sourceforge.net/
976    \end{verbatim}
977      \begin{rawhtml} </A> \end{rawhtml}
978      \begin{rawhtml} <A href="http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html"> \end{rawhtml}
979    \begin{verbatim}
980    http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html
981    \end{verbatim}
982      \begin{rawhtml} </A> \end{rawhtml}
983    \end{itemize}
984    
Legend:
Removed from v.1.37  
changed lines
  Added in v.1.43
  ViewVC Help
Powered by ViewVC 1.1.22