/[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.40 by jmc, Thu Jan 21 19:20:08 2010 UTC revision 1.45 by jmc, Wed May 11 18:58:02 2011 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 92  You only need to do a ``cvs login'' once Line 92  You only need to do a ``cvs login'' once
92    
93  To obtain the latest sources type:  To obtain the latest sources type:
94  \begin{verbatim}  \begin{verbatim}
95  % cvs co MITgcm  % cvs co -P MITgcm
96  \end{verbatim}  \end{verbatim}
97  or to get a specific release type:  or to get a specific release type:
98  \begin{verbatim}  \begin{verbatim}
99  % cvs co -P -r checkpoint52i_post  MITgcm  % cvs co -P -r checkpoint52i_post MITgcm
100  \end{verbatim}  \end{verbatim}
101    The CVS command ``\texttt{cvs co}'' is the abreviation of the full-name
102    ``\texttt{cvs checkout}'' command and using the option ``-P'' (\texttt{cvs co -P})
103    will prevent to download unnecessary empty directories.
104    
105  The MITgcm web site contains further directions concerning the source  The MITgcm web site contains further directions concerning the source
106  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
107  that one may easily view the state of files, revisions, and other  that one may easily view the state of files, revisions, and other
108  development milestones:  development milestones:
 %\begin{rawhtml} <A href="http://mitgcm.org/download" target="idontexist"> \end{rawhtml}  
109  \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}
110  \begin{verbatim}  \begin{verbatim}
111  http://mitgcm.org/source_code.html  http://mitgcm.org/viewvc/MITgcm/MITgcm/
112  \end{verbatim}  \end{verbatim}
113  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
114    
# Line 140  track of your file versions with respect Line 143  track of your file versions with respect
143  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
144  updates.  More extensive information on using CVS for maintaining  updates.  More extensive information on using CVS for maintaining
145  MITgcm code can be found  MITgcm code can be found
146  \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}
147  here  here
148  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
149  .  .
# Line 149  It is important to note that the CVS ali Line 152  It is important to note that the CVS ali
152  \texttt{-d DIRNAME} option.  However, the \texttt{MITgcm} directories  \texttt{-d DIRNAME} option.  However, the \texttt{MITgcm} directories
153  they create can be changed to a different name following the check-out:  they create can be changed to a different name following the check-out:
154  \begin{verbatim}  \begin{verbatim}
155     %  cvs co MITgcm_verif_basic     %  cvs co -P MITgcm_verif_basic
156     %  mv MITgcm MITgcm_verif_basic     %  mv MITgcm MITgcm_verif_basic
157  \end{verbatim}  \end{verbatim}
158    
# Line 163  your copy instead of downloading the ent Line 166  your copy instead of downloading the ent
166  \end{verbatim}  \end{verbatim}
167  and then issue the cvs update command such as:  and then issue the cvs update command such as:
168  \begin{verbatim}  \begin{verbatim}
169  % cvs -q update -r checkpoint52i_post -d -P  % cvs -q update -d -P -r checkpoint52i_post
170  \end{verbatim}  \end{verbatim}
171  This will update the ``tag'' to ``checkpoint52i\_post'', add any new  This will update the ``tag'' to ``checkpoint52i\_post'', add any new
172  directories (-d) and remove any empty directories (-P). The -q option  directories (-d) and remove any empty directories (-P). The -q option
# Line 209  have run into a problem for which ``we h Line 212  have run into a problem for which ``we h
212  latest code'' and we haven't made a ``tag'' or ``release'' since that  latest code'' and we haven't made a ``tag'' or ``release'' since that
213  patch then you'll need to get the latest code:  patch then you'll need to get the latest code:
214  \begin{verbatim}  \begin{verbatim}
215  % cvs -q update -A -d -P  % cvs -q update -d -P -A
216  \end{verbatim}  \end{verbatim}
217  Unlike, the ``check-out'' and ``update'' procedures above, there is no  Unlike, the ``check-out'' and ``update'' procedures above, there is no
218  ``tag'' or release name. The -A tells CVS to upgrade to the  ``tag'' or release name. The -A tells CVS to upgrade to the
# Line 220  also means we can't tell what version of Line 223  also means we can't tell what version of
223  with. So please be sure you understand what you're doing.  with. So please be sure you understand what you're doing.
224    
225  \subsection{Method 2 - Tar file download}  \subsection{Method 2 - Tar file download}
226  \label{sect:conventionalDownload}  \label{sec:conventionalDownload}
227    
228  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
229  tar file from the web site at:  tar file from the web site at:
# Line 277  structure). Line 280  structure).
280    package corresponds to a subdirectory. For example, \texttt{gmredi}    package corresponds to a subdirectory. For example, \texttt{gmredi}
281    contains the code related to the Gent-McWilliams/Redi scheme,    contains the code related to the Gent-McWilliams/Redi scheme,
282    \texttt{aim} the code relative to the atmospheric intermediate    \texttt{aim} the code relative to the atmospheric intermediate
283    physics. The packages are described in detail in chapter \ref{chap.packagesI}.    physics. The packages are described in detail in chapter \ref{chap:packagesI}.
284        
285  \item \texttt{tools}: this directory contains various useful tools.  \item \texttt{tools}: this directory contains various useful tools.
286    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 304  structure).
304    decompositions.    decompositions.
305        
306  \item \texttt{verification}: this directory contains the model  \item \texttt{verification}: this directory contains the model
307    examples. See section \ref{sect:modelExamples}.    examples. See section \ref{sec:modelExamples}.
308    
309  \item \texttt{jobs}: contains sample job scripts for running MITgcm.  \item \texttt{jobs}: contains sample job scripts for running MITgcm.
310        
# Line 312  structure). Line 315  structure).
315  \end{itemize}  \end{itemize}
316    
317  \section[Building MITgcm]{Building the code}  \section[Building MITgcm]{Building the code}
318  \label{sect:buildingCode}  \label{sec:buildingCode}
319  \begin{rawhtml}  \begin{rawhtml}
320  <!-- CMIREDIR:buildingCode: -->  <!-- CMIREDIR:buildingCode: -->
321  \end{rawhtml}  \end{rawhtml}
# Line 321  To compile the code, we use the \texttt{ Line 324  To compile the code, we use the \texttt{
324  file (\texttt{Makefile}) that allows us to pre-process source files,  file (\texttt{Makefile}) that allows us to pre-process source files,
325  specify compiler and optimization options and also figures out any  specify compiler and optimization options and also figures out any
326  file dependencies. We supply a script (\texttt{genmake2}), described  file dependencies. We supply a script (\texttt{genmake2}), described
327  in section \ref{sect:genmake}, that automatically creates the  in section \ref{sec:genmake}, that automatically creates the
328  \texttt{Makefile} for you. You then need to build the dependencies and  \texttt{Makefile} for you. You then need to build the dependencies and
329  compile the code.  compile the code.
330    
# Line 396  where the ``2'' can be replaced with a n Line 399  where the ``2'' can be replaced with a n
399  number of CPUs available.  number of CPUs available.
400    
401  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
402  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
403  first creating links to all the input files:  first creating links to all the input files:
404  \begin{verbatim}  \begin{verbatim}
405  ln -s ../input/* .  ln -s ../input/* .
# Line 410  where we are re-directing the stream of Line 413  where we are re-directing the stream of
413    
414  \subsection{Building/compiling the code elsewhere}  \subsection{Building/compiling the code elsewhere}
415    
416  In the example above (section \ref{sect:buildingCode}) we built the  In the example above (section \ref{sec:buildingCode}) we built the
417  executable in the {\em input} directory of the experiment for  executable in the {\em input} directory of the experiment for
418  convenience. You can also configure and compile the code in other  convenience. You can also configure and compile the code in other
419  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 517  the one experiment:
517    
518    
519  \subsection{Using \texttt{genmake2}}  \subsection{Using \texttt{genmake2}}
520  \label{sect:genmake}  \label{sec:genmake}
521    
522  To compile the code, first use the program \texttt{genmake2} (located  To compile the code, first use the program \texttt{genmake2} (located
523  in the \texttt{tools} directory) to generate a Makefile.  in the \texttt{tools} directory) to generate a Makefile.
524  \texttt{genmake2} is a shell script written to work with all  \texttt{genmake2} is a shell script written to work with all
525  ``sh''--compatible shells including bash v1, bash v2, and Bourne.  ``sh''--compatible shells including bash v1, bash v2, and Bourne.
526  Internally, \texttt{genmake2} determines the locations of needed  %Internally, \texttt{genmake2} determines the locations of needed
527  files, the compiler, compiler options, libraries, and Unix tools.  It  %files, the compiler, compiler options, libraries, and Unix tools.  It
528  relies upon a number of ``optfiles'' located in the  %relies upon a number of ``optfiles'' located in the
529  \texttt{tools/build\_options} directory.  %\texttt{tools/build\_options} directory.
530    \texttt{genmake2} parses information from the following sources:
531    \begin{description}
532    \item[-] a {\em gemake\_local} file if one is found in the current
533      directory
534    \item[-] command-line options
535    \item[-] an "options file" as specified by the command-line option
536      \texttt{--optfile=/PATH/FILENAME}
537    \item[-] a {\em packages.conf} file (if one is found) with the
538      specific list of packages to compile. The search path for
539      file {\em packages.conf} is, first, the current directory and
540      then each of the "MODS" directories in the given order (see below).
541    \end{description}
542    
543    \subsubsection{Optfiles in \texttt{tools/build\_options} directory:}
544    
545  The purpose of the optfiles is to provide all the compilation options  The purpose of the optfiles is to provide all the compilation options
546  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 613  for inclusion.  Please send the file to
613  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
614  mailing list.  mailing list.
615    
616    \subsubsection{Command-line options:}
617    
618  In addition to the optfiles, \texttt{genmake2} supports a number of  In addition to the optfiles, \texttt{genmake2} supports a number of
619  helpful command-line options.  A complete list of these options can be  helpful command-line options.  A complete list of these options can be
620  obtained from:  obtained from:
# Line 618  The most important command-line options Line 637  The most important command-line options
637    the user's path.  When these three items have been identified,    the user's path.  When these three items have been identified,
638    genmake2 will try to find an optfile that has a matching name.    genmake2 will try to find an optfile that has a matching name.
639        
640  \item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default  \item[\texttt{--mods='DIR1 DIR2 DIR3 ...'}] specifies a list of
641    set of packages to be used.  The normal order of precedence for    directories containing ``modifications''.  These directories contain
642    packages is as follows:    files with names that may (or may not) exist in the main MITgcm
643    \begin{enumerate}    source tree but will be overridden by any identically-named sources
644    \item If available, the command line (\texttt{--pdefault}) settings    within the ``MODS'' directories.
645      over-rule any others.    
646      The order of precedence for this "name-hiding" is as follows:
647    \item Next, \texttt{genmake2} will look for a file named    \begin{itemize}
648      ``\texttt{packages.conf}'' in the local directory or in any of the    \item ``MODS'' directories (in the order given)
649      directories specified with the \texttt{--mods} option.    \item Packages either explicitly specified or provided by default
650            (in the order given)
651    \item Finally, if neither of the above are available,    \item Packages included due to package dependencies (in the order
652      \texttt{genmake2} will use the \texttt{/pkg/pkg\_default} file.      that that package dependencies are parsed)
653    \end{enumerate}    \item The "standard dirs" (which may have been specified by the
654        ``-standarddirs'' option)
655      \end{itemize}
656        
657    \item[\texttt{--pgroups=/PATH/FILENAME}] specifies the file
658      where package groups are defined. If not set, the package-groups
659      definition will be read from {\em pkg/pkg\_groups}.
660      It also contains the default list of packages (defined
661      as the group ``{\it default\_pkg\_list}'' which is used
662      when no specific package list ({\em packages.conf})
663      is found in current directory or in any "MODS" directory.
664    
665  \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file  \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file
666    used for packages.    used for packages.
667        
# Line 657  The most important command-line options Line 686  The most important command-line options
686    "STAF" compiler.  As with any compilers, it is helpful to have their    "STAF" compiler.  As with any compilers, it is helpful to have their
687    directories listed in your {\tt \$PATH} environment variable.    directories listed in your {\tt \$PATH} environment variable.
688        
 \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}  
     
689  \item[\texttt{--mpi}] This option enables certain MPI features (using  \item[\texttt{--mpi}] This option enables certain MPI features (using
690    CPP \texttt{\#define}s) within the code and is necessary for MPI    CPP \texttt{\#define}s) within the code and is necessary for MPI
691    builds (see Section \ref{sect:mpi-build}).    builds (see Section \ref{sec:mpi-build}).
692        
693  \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of  \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of
694    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 711  The most important command-line options
711    
712    
713  \subsection{Building with MPI}  \subsection{Building with MPI}
714  \label{sect:mpi-build}  \label{sec:mpi-build}
715    
716  Building MITgcm to use MPI libraries can be complicated due to the  Building MITgcm to use MPI libraries can be complicated due to the
717  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 726  The steps for building MITgcm with MPI s
726        
727  \item Determine the locations of your MPI-enabled compiler and/or MPI  \item Determine the locations of your MPI-enabled compiler and/or MPI
728    libraries and put them into an options file as described in Section    libraries and put them into an options file as described in Section
729    \ref{sect:genmake}.  One can start with one of the examples in:    \ref{sec:genmake}.  One can start with one of the examples in:
730    \begin{rawhtml} <A    \begin{rawhtml} <A
731      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/build_options/">
732    \end{rawhtml}    \end{rawhtml}
# Line 749  The steps for building MITgcm with MPI s Line 761  The steps for building MITgcm with MPI s
761    \end{itemize}    \end{itemize}
762        
763  \item Build the code with the \texttt{genmake2} \texttt{-mpi} option  \item Build the code with the \texttt{genmake2} \texttt{-mpi} option
764    (see Section \ref{sect:genmake}) using commands such as:    (see Section \ref{sec:genmake}) using commands such as:
765  {\footnotesize \begin{verbatim}  {\footnotesize \begin{verbatim}
766    %  ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE    %  ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE
767    %  make depend    %  make depend
# Line 767  The steps for building MITgcm with MPI s Line 779  The steps for building MITgcm with MPI s
779    library and a job scheduling and queueing system such as PBS,    library and a job scheduling and queueing system such as PBS,
780    LoadLeveller, Condor, or any of a number of similar tools.  A few    LoadLeveller, Condor, or any of a number of similar tools.  A few
781    example scripts (those used for our \begin{rawhtml} <A    example scripts (those used for our \begin{rawhtml} <A
782      href="http://mitgcm.org/testing.html"> \end{rawhtml}regular      href="http://mitgcm.org/public/testing.html"> \end{rawhtml}regular
783    verification runs\begin{rawhtml} </A> \end{rawhtml}) are available    verification runs\begin{rawhtml} </A> \end{rawhtml}) are available
784    at:    at:
785    \begin{rawhtml} <A    \begin{rawhtml} <A
786        href="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
787      \end{rawhtml}
788      {\footnotesize \tt
789        http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example\_scripts/ }
790      \begin{rawhtml} </A> \end{rawhtml}
791      or at:
792      \begin{rawhtml} <A
793      href="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">      href="http://mitgcm.org/viewvc/MITgcm/MITgcm_contrib/test_scripts/">
794    \end{rawhtml}    \end{rawhtml}
795    {\footnotesize \tt    {\footnotesize \tt
# Line 796  the GNU g77 compiler and the mpich MPI l Line 815  the GNU g77 compiler and the mpich MPI l
815  \end{verbatim} }  \end{verbatim} }
816    
817  \section[Running MITgcm]{Running the model in prognostic mode}  \section[Running MITgcm]{Running the model in prognostic mode}
818  \label{sect:runModel}  \label{sec:runModel}
819  \begin{rawhtml}  \begin{rawhtml}
820  <!-- CMIREDIR:runModel: -->  <!-- CMIREDIR:runModel: -->
821  \end{rawhtml}  \end{rawhtml}
822    
823  If compilation finished succesfully (section \ref{sect:buildingCode})  If compilation finished succesfully (section \ref{sec:buildingCode})
824  then an executable called \texttt{mitgcmuv} will now exist in the  then an executable called \texttt{mitgcmuv} will now exist in the
825  local directory.  local directory.
826    
Legend:
Removed from v.1.40  
changed lines
  Added in v.1.45
  ViewVC Help
Powered by ViewVC 1.1.22