/[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.41 by jmc, Fri Jan 22 00:38:16 2010 UTC revision 1.44 by jmc, Mon Aug 30 23:09:20 2010 UTC
# Line 14  are described more fully in chapters \re Line 14  are described more fully in chapters \re
14  \ref{chap:sarch}.  \ref{chap:sarch}.
15    
16  \section{Where to find information}  \section{Where to find information}
17  \label{sect:whereToFindInfo}  \label{sec:whereToFindInfo}
18  \begin{rawhtml}  \begin{rawhtml}
19  <!-- CMIREDIR:whereToFindInfo: -->  <!-- CMIREDIR:whereToFindInfo: -->
20  \end{rawhtml}  \end{rawhtml}
# Line 29  http://mitgcm.org/pipermail/mitgcm-suppo Line 29  http://mitgcm.org/pipermail/mitgcm-suppo
29  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
30    
31  \section{Obtaining the code}  \section{Obtaining the code}
32  \label{sect:obtainingCode}  \label{sec:obtainingCode}
33  \begin{rawhtml}  \begin{rawhtml}
34  <!-- CMIREDIR:obtainingCode: -->  <!-- CMIREDIR:obtainingCode: -->
35  \end{rawhtml}  \end{rawhtml}
# Line 63  provide easy support for maintenance upd Line 63  provide easy support for maintenance upd
63  \end{enumerate}  \end{enumerate}
64    
65  \subsection{Method 1 - Checkout from CVS}  \subsection{Method 1 - Checkout from CVS}
66  \label{sect:cvs_checkout}  \label{sec:cvs_checkout}
67    
68  If CVS is available on your system, we strongly encourage you to use it. CVS  If CVS is available on your system, we strongly encourage you to use it. CVS
69  provides an efficient and elegant way of organizing your code and keeping  provides an efficient and elegant way of organizing your code and keeping
# Line 102  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:
 %\begin{rawhtml} <A href="http://mitgcm.org/download" target="idontexist"> \end{rawhtml}  
105  \begin{rawhtml} <A href="http://mitgcm.org/viewvc/MITgcm/MITgcm/" 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 220  also means we can't tell what version of Line 219  also means we can't tell what version of
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}  \subsection{Method 2 - Tar file download}
222  \label{sect:conventionalDownload}  \label{sec:conventionalDownload}
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:
# Line 277  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 chapter \ref{chap.packagesI}.    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)
# Line 301  structure). Line 300  structure).
300    decompositions.    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{sec:modelExamples}.
304    
305  \item \texttt{jobs}: contains sample job scripts for running MITgcm.  \item \texttt{jobs}: contains sample job scripts for running MITgcm.
306        
# Line 312  structure). Line 311  structure).
311  \end{itemize}  \end{itemize}
312    
313  \section[Building MITgcm]{Building the code}  \section[Building MITgcm]{Building the code}
314  \label{sect:buildingCode}  \label{sec:buildingCode}
315  \begin{rawhtml}  \begin{rawhtml}
316  <!-- CMIREDIR:buildingCode: -->  <!-- CMIREDIR:buildingCode: -->
317  \end{rawhtml}  \end{rawhtml}
# Line 321  To compile the code, we use the \texttt{ Line 320  To compile the code, we use the \texttt{
320  file (\texttt{Makefile}) that allows us to pre-process source files,  file (\texttt{Makefile}) that allows us to pre-process source files,
321  specify compiler and optimization options and also figures out any  specify compiler and optimization options and also figures out any
322  file dependencies. We supply a script (\texttt{genmake2}), described  file dependencies. We supply a script (\texttt{genmake2}), described
323  in section \ref{sect:genmake}, that automatically creates the  in section \ref{sec:genmake}, that automatically creates the
324  \texttt{Makefile} for you. You then need to build the dependencies and  \texttt{Makefile} for you. You then need to build the dependencies and
325  compile the code.  compile the code.
326    
# Line 396  where the ``2'' can be replaced with a n Line 395  where the ``2'' can be replaced with a n
395  number of CPUs available.  number of CPUs available.
396    
397  Now you are ready to run the model. General instructions for doing so are  Now you are ready to run the model. General instructions for doing so are
398  given in section \ref{sect:runModel}. Here, we can run the model by  given in section \ref{sec:runModel}. Here, we can run the model by
399  first creating links to all the input files:  first creating links to all the input files:
400  \begin{verbatim}  \begin{verbatim}
401  ln -s ../input/* .  ln -s ../input/* .
# Line 410  where we are re-directing the stream of Line 409  where we are re-directing the stream of
409    
410  \subsection{Building/compiling the code elsewhere}  \subsection{Building/compiling the code elsewhere}
411    
412  In the example above (section \ref{sect:buildingCode}) we built the  In the example above (section \ref{sec:buildingCode}) we built the
413  executable in the {\em input} directory of the experiment for  executable in the {\em input} directory of the experiment for
414  convenience. You can also configure and compile the code in other  convenience. You can also configure and compile the code in other
415  locations, for example on a scratch disk with out having to copy the  locations, for example on a scratch disk with out having to copy the
# Line 514  the one experiment: Line 513  the one experiment:
513    
514    
515  \subsection{Using \texttt{genmake2}}  \subsection{Using \texttt{genmake2}}
516  \label{sect:genmake}  \label{sec:genmake}
517    
518  To compile the code, first use the program \texttt{genmake2} (located  To compile the code, first use the program \texttt{genmake2} (located
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 596  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 618  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 657  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{sec:mpi-build}).
688        
689  \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of  \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of
690    soft-links and other bugs common with the \texttt{make} versions    soft-links and other bugs common with the \texttt{make} versions
# Line 699  The most important command-line options Line 707  The most important command-line options
707    
708    
709  \subsection{Building with MPI}  \subsection{Building with MPI}
710  \label{sect:mpi-build}  \label{sec:mpi-build}
711    
712  Building MITgcm to use MPI libraries can be complicated due to the  Building MITgcm to use MPI libraries can be complicated due to the
713  variety of different MPI implementations available, their dependencies  variety of different MPI implementations available, their dependencies
# Line 714  The steps for building MITgcm with MPI s Line 722  The steps for building MITgcm with MPI s
722        
723  \item Determine the locations of your MPI-enabled compiler and/or MPI  \item Determine the locations of your MPI-enabled compiler and/or MPI
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{sec:genmake}.  One can start with one of the examples in:
726    \begin{rawhtml} <A    \begin{rawhtml} <A
727      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">
728    \end{rawhtml}    \end{rawhtml}
# Line 749  The steps for building MITgcm with MPI s Line 757  The steps for building MITgcm with MPI s
757    \end{itemize}    \end{itemize}
758        
759  \item Build the code with the \texttt{genmake2} \texttt{-mpi} option  \item Build the code with the \texttt{genmake2} \texttt{-mpi} option
760    (see Section \ref{sect:genmake}) using commands such as:    (see Section \ref{sec:genmake}) using commands such as:
761  {\footnotesize \begin{verbatim}  {\footnotesize \begin{verbatim}
762    %  ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE    %  ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE
763    %  make depend    %  make depend
# Line 803  the GNU g77 compiler and the mpich MPI l Line 811  the GNU g77 compiler and the mpich MPI l
811  \end{verbatim} }  \end{verbatim} }
812    
813  \section[Running MITgcm]{Running the model in prognostic mode}  \section[Running MITgcm]{Running the model in prognostic mode}
814  \label{sect:runModel}  \label{sec:runModel}
815  \begin{rawhtml}  \begin{rawhtml}
816  <!-- CMIREDIR:runModel: -->  <!-- CMIREDIR:runModel: -->
817  \end{rawhtml}  \end{rawhtml}
818    
819  If compilation finished succesfully (section \ref{sect:buildingCode})  If compilation finished succesfully (section \ref{sec:buildingCode})
820  then an executable called \texttt{mitgcmuv} will now exist in the  then an executable called \texttt{mitgcmuv} will now exist in the
821  local directory.  local directory.
822    
Legend:
Removed from v.1.41  
changed lines
  Added in v.1.44
  ViewVC Help
Powered by ViewVC 1.1.22