--- manual/s_getstarted/text/getting_started.tex 2010/01/21 19:20:08 1.40 +++ manual/s_getstarted/text/getting_started.tex 2018/01/09 01:02:48 1.47 @@ -1,4 +1,4 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.40 2010/01/21 19:20:08 jmc Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.47 2018/01/09 01:02:48 jmc Exp $ % $Name: $ %\section{Getting started} @@ -8,28 +8,33 @@ version. Information on how to obtain, compile, and run the code is found here as well as a brief description of the model structure directory and the case study examples. Information is also provided -here on how to customize the code when you are ready to try implementing +here on how to customize the code when you are ready to try implementing the configuration you have in mind. The code and algorithm -are described more fully in chapters \ref{chap:discretization} and -\ref{chap:sarch}. +are described more fully in chapters \ref{chap:discretization} and +\ref{chap:sarch}. \section{Where to find information} -\label{sect:whereToFindInfo} +\label{sec:whereToFindInfo} \begin{rawhtml} \end{rawhtml} There is a web-archived support mailing list for the model that -you can email at \texttt{MITgcm-support@mitgcm.org} or browse at: -\begin{rawhtml} \end{rawhtml} +you can email at \texttt{MITgcm-support@mitgcm.org} after subscribing to: +\begin{rawhtml} \end{rawhtml} \begin{verbatim} -http://mitgcm.org/mailman/listinfo/mitgcm-support/ -http://mitgcm.org/pipermail/mitgcm-support/ +http://mailman.mitgcm.org/mailman/listinfo/mitgcm-support/ +\end{verbatim} +\begin{rawhtml} \end{rawhtml} +or browse at: +\begin{rawhtml} \end{rawhtml} +\begin{verbatim} +http://mailman.mitgcm.org/pipermail/mitgcm-support/ \end{verbatim} \begin{rawhtml} \end{rawhtml} \section{Obtaining the code} -\label{sect:obtainingCode} +\label{sec:obtainingCode} \begin{rawhtml} \end{rawhtml} @@ -63,7 +68,7 @@ \end{enumerate} \subsection{Method 1 - Checkout from CVS} -\label{sect:cvs_checkout} +\label{sec:cvs_checkout} If CVS is available on your system, we strongly encourage you to use it. CVS provides an efficient and elegant way of organizing your code and keeping @@ -71,7 +76,7 @@ download a tar file. Before you can use CVS, the following environment variable(s) should -be set within your shell. For a csh or tcsh shell, put the following +be set within your shell. For a csh or tcsh shell, put the following \begin{verbatim} % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/gcmpack \end{verbatim} @@ -82,7 +87,6 @@ \end{verbatim} in your \texttt{.profile} or \texttt{.bashrc} file. - To get MITgcm through CVS, first register with the MITgcm CVS server using command: \begin{verbatim} @@ -92,20 +96,23 @@ To obtain the latest sources type: \begin{verbatim} -% cvs co MITgcm +% cvs co -P MITgcm \end{verbatim} or to get a specific release type: \begin{verbatim} -% cvs co -P -r checkpoint52i_post MITgcm +% cvs co -P -r checkpoint52i_post MITgcm \end{verbatim} +The CVS command ``\texttt{cvs co}'' is the abreviation of the full-name +``\texttt{cvs checkout}'' command and using the option ``-P'' (\texttt{cvs co -P}) +will prevent to download unnecessary empty directories. + The MITgcm web site contains further directions concerning the source code and CVS. It also contains a web interface to our CVS archive so that one may easily view the state of files, revisions, and other development milestones: -%\begin{rawhtml} \end{rawhtml} \begin{rawhtml} \end{rawhtml} \begin{verbatim} -http://mitgcm.org/source_code.html +http://mitgcm.org/viewvc/MITgcm/MITgcm/ \end{verbatim} \begin{rawhtml} \end{rawhtml} @@ -120,8 +127,8 @@ \textbf{Alias Name} & \textbf{Information (directories) Contained} \\\hline \texttt{MITgcm\_code} & Only the source code -- none of the verification examples. \\ \texttt{MITgcm\_verif\_basic} - & Source code plus a small set of the verification examples - (\texttt{global\_ocean.90x40x15}, \texttt{aim.5l\_cs}, \texttt{hs94.128x64x5}, + & Source code plus a small set of the verification examples + (\texttt{global\_ocean.90x40x15}, \texttt{aim.5l\_cs}, \texttt{hs94.128x64x5}, \texttt{front\_relax}, and \texttt{plume\_on\_slope}). \\ \texttt{MITgcm\_verif\_atmos} & Source code plus all of the atmospheric examples. \\ \texttt{MITgcm\_verif\_ocean} & Source code plus all of the oceanic examples. \\ @@ -140,19 +147,25 @@ the files in \texttt{CVS}! You can also use CVS to download code updates. More extensive information on using CVS for maintaining MITgcm code can be found -\begin{rawhtml} \end{rawhtml} +\begin{rawhtml} \end{rawhtml} here -\begin{rawhtml} \end{rawhtml} -. +\begin{rawhtml} \end{rawhtml}. It is important to note that the CVS aliases in Table \ref{tab:cvsModules} cannot be used in conjunction with the CVS \texttt{-d DIRNAME} option. However, the \texttt{MITgcm} directories they create can be changed to a different name following the check-out: \begin{verbatim} - % cvs co MITgcm_verif_basic + % cvs co -P MITgcm_verif_basic % mv MITgcm MITgcm_verif_basic \end{verbatim} +Note that it is possible to checkout code without ``cvs login'' and without +setting any shell environment variables by specifying the pserver name and +password in one line, for example: +\begin{verbatim} + % cvs -d :pserver:cvsanon:cvsanon@mitgcm.org:/u/gcmpack co -P MITgcm +\end{verbatim} + \subsubsection{Upgrading from an earlier version} If you already have an earlier version of the code you can ``upgrade'' @@ -163,7 +176,7 @@ \end{verbatim} and then issue the cvs update command such as: \begin{verbatim} -% cvs -q update -r checkpoint52i_post -d -P +% cvs -q update -d -P -r checkpoint52i_post \end{verbatim} This will update the ``tag'' to ``checkpoint52i\_post'', add any new directories (-d) and remove any empty directories (-P). The -q option @@ -209,7 +222,7 @@ latest code'' and we haven't made a ``tag'' or ``release'' since that patch then you'll need to get the latest code: \begin{verbatim} -% cvs -q update -A -d -P +% cvs -q update -d -P -A \end{verbatim} Unlike, the ``check-out'' and ``update'' procedures above, there is no ``tag'' or release name. The -A tells CVS to upgrade to the @@ -220,7 +233,7 @@ with. So please be sure you understand what you're doing. \subsection{Method 2 - Tar file download} -\label{sect:conventionalDownload} +\label{sec:conventionalDownload} If you do not have CVS on your system, you can download the model as a tar file from the web site at: @@ -233,7 +246,7 @@ 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 +the \begin{rawhtml} \end{rawhtml} MITgcm-support@mitgcm.org \begin{rawhtml} \end{rawhtml} @@ -264,21 +277,21 @@ \begin{itemize} \item \texttt{doc}: contains brief documentation notes. - + \item \texttt{eesupp}: contains the execution environment source code. Also subdivided into two subdirectories \texttt{inc} and \texttt{src}. - + \item \texttt{model}: this directory contains the main source code. Also subdivided into two subdirectories \texttt{inc} and \texttt{src}. - + \item \texttt{pkg}: contains the source code for the packages. Each package corresponds to a subdirectory. For example, \texttt{gmredi} contains the code related to the Gent-McWilliams/Redi scheme, \texttt{aim} the code relative to the atmospheric intermediate - physics. The packages are described in detail in chapter \ref{chap.packagesI}. - + physics. The packages are described in detail in chapter \ref{chap:packagesI}. + \item \texttt{tools}: this directory contains various useful tools. For example, \texttt{genmake2} is a script written in csh (C-shell) that should be used to generate your makefile. The directory @@ -288,7 +301,7 @@ This directory also contains the subdirectory build\_options, which contains the `optfiles' with the compiler options for the different compilers and machines that can run MITgcm. - + \item \texttt{utils}: this directory contains various utilities. The subdirectory \texttt{knudsen2} contains code and a makefile that compute coefficients of the polynomial approximation to the knudsen @@ -299,20 +312,20 @@ model output. The subdirectory exch2 contains the code needed for the exch2 package to work with different combinations of domain decompositions. - + \item \texttt{verification}: this directory contains the model - examples. See section \ref{sect:modelExamples}. + examples. See section \ref{sec:modelExamples}. \item \texttt{jobs}: contains sample job scripts for running MITgcm. - + \item \texttt{lsopt}: Line search code used for optimization. - + \item \texttt{optim}: Interface between MITgcm and line search code. - + \end{itemize} \section[Building MITgcm]{Building the code} -\label{sect:buildingCode} +\label{sec:buildingCode} \begin{rawhtml} \end{rawhtml} @@ -321,7 +334,7 @@ file (\texttt{Makefile}) that allows us to pre-process source files, specify compiler and optimization options and also figures out any file dependencies. We supply a script (\texttt{genmake2}), described -in section \ref{sect:genmake}, that automatically creates the +in section \ref{sec:genmake}, that automatically creates the \texttt{Makefile} for you. You then need to build the dependencies and compile the code. @@ -353,7 +366,7 @@ Through the MITgcm-support list, the MITgcm developers are willing to provide help writing or modifing ``optfiles''. And we encourage users to post new ``optfiles'' (particularly ones for new machines or -architectures) to the +architectures) to the \begin{rawhtml} \end{rawhtml} MITgcm-support@mitgcm.org \begin{rawhtml} \end{rawhtml} @@ -396,7 +409,7 @@ number of CPUs available. Now you are ready to run the model. General instructions for doing so are -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 first creating links to all the input files: \begin{verbatim} ln -s ../input/* . @@ -410,7 +423,7 @@ \subsection{Building/compiling the code elsewhere} -In the example above (section \ref{sect:buildingCode}) we built the +In the example above (section \ref{sec:buildingCode}) we built the executable in the {\em input} directory of the experiment for convenience. You can also configure and compile the code in other locations, for example on a scratch disk with out having to copy the @@ -512,18 +525,31 @@ % ./mitgcmuv > output.txt \end{verbatim} - \subsection{Using \texttt{genmake2}} -\label{sect:genmake} +\label{sec:genmake} To compile the code, first use the program \texttt{genmake2} (located in the \texttt{tools} directory) to generate a Makefile. \texttt{genmake2} is a shell script written to work with all ``sh''--compatible shells including bash v1, bash v2, and Bourne. -Internally, \texttt{genmake2} determines the locations of needed -files, the compiler, compiler options, libraries, and Unix tools. It -relies upon a number of ``optfiles'' located in the -\texttt{tools/build\_options} directory. +%Internally, \texttt{genmake2} determines the locations of needed +%files, the compiler, compiler options, libraries, and Unix tools. It +%relies upon a number of ``optfiles'' located in the +%\texttt{tools/build\_options} directory. +\texttt{genmake2} parses information from the following sources: +\begin{description} +\item[-] a {\em gemake\_local} file if one is found in the current + directory +\item[-] command-line options +\item[-] an "options file" as specified by the command-line option + \texttt{--optfile=/PATH/FILENAME} +\item[-] a {\em packages.conf} file (if one is found) with the + specific list of packages to compile. The search path for + file {\em packages.conf} is, first, the current directory and + then each of the "MODS" directories in the given order (see below). +\end{description} + +\subsubsection{Optfiles in \texttt{tools/build\_options} directory:} The purpose of the optfiles is to provide all the compilation options for particular ``platforms'' (where ``platform'' roughly means the @@ -596,6 +622,8 @@ \begin{rawhtml} \end{rawhtml} mailing list. +\subsubsection{Command-line options:} + In addition to the optfiles, \texttt{genmake2} supports a number of helpful command-line options. A complete list of these options can be obtained from: @@ -605,10 +633,10 @@ The most important command-line options are: \begin{description} - + \item[\texttt{--optfile=/PATH/FILENAME}] specifies the optfile that should be used for a particular build. - + If no "optfile" is specified (either through the command line or the MITGCM\_OPTFILE environment variable), genmake2 will try to make a reasonable guess from the list provided in {\em @@ -617,25 +645,35 @@ (eg. "linux\_ia32") and then find a working FORTRAN compiler within the user's path. When these three items have been identified, genmake2 will try to find an optfile that has a matching name. - -\item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default - set of packages to be used. The normal order of precedence for - packages is as follows: - \begin{enumerate} - \item If available, the command line (\texttt{--pdefault}) settings - over-rule any others. - - \item Next, \texttt{genmake2} will look for a file named - ``\texttt{packages.conf}'' in the local directory or in any of the - directories specified with the \texttt{--mods} option. - - \item Finally, if neither of the above are available, - \texttt{genmake2} will use the \texttt{/pkg/pkg\_default} file. - \end{enumerate} - + +\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} + +\item[\texttt{--pgroups=/PATH/FILENAME}] specifies the file + where package groups are defined. If not set, the package-groups + definition will be read from {\em pkg/pkg\_groups}. + It also contains the default list of packages (defined + as the group ``{\it default\_pkg\_list}'' which is used + when no specific package list ({\em packages.conf}) + is found in current directory or in any "MODS" directory. + \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file used for packages. - + If not specified, the default dependency file {\em pkg/pkg\_depend} is used. The syntax for this file is parsed on a line-by-line basis where each line containes either a comment ("\#") or a simple @@ -644,46 +682,29 @@ relationship, respectively. If no rule is specified, then it is assumed that the two packages are compatible and will function either with or without each other. - + \item[\texttt{--adof=/path/to/file}] specifies the "adjoint" or automatic differentiation options file to be used. The file is analogous to the ``optfile'' defined above but it specifies information for the AD build process. - + The default file is located in {\em tools/adjoint\_options/adjoint\_default} and it defines the "TAF" and "TAMC" compilers. An alternate version is also available at {\em tools/adjoint\_options/adjoint\_staf} that selects the newer "STAF" compiler. As with any compilers, it is helpful to have their directories listed in your {\tt \$PATH} environment variable. - -\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} - + \item[\texttt{--mpi}] This option enables certain MPI features (using CPP \texttt{\#define}s) within the code and is necessary for MPI - builds (see Section \ref{sect:mpi-build}). - + builds (see Section \ref{sec:mpi-build}). + \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of soft-links and other bugs common with the \texttt{make} versions provided by commercial Unix vendors, GNU \texttt{make} (sometimes called \texttt{gmake}) should be preferred. This option provides a means for specifying the make executable to be used. - + \item[\texttt{--bash=/path/to/sh}] On some (usually older UNIX) machines, the ``bash'' shell is unavailable. To run on these systems, \texttt{genmake2} can be invoked using an ``sh'' (that is, @@ -697,9 +718,8 @@ \end{description} - \subsection{Building with MPI} -\label{sect:mpi-build} +\label{sec:mpi-build} Building MITgcm to use MPI libraries can be complicated due to the variety of different MPI implementations available, their dependencies @@ -711,10 +731,10 @@ The steps for building MITgcm with MPI support are: \begin{enumerate} - + \item Determine the locations of your MPI-enabled compiler and/or MPI libraries and put them into an options file as described in Section - \ref{sect:genmake}. One can start with one of the examples in: + \ref{sec:genmake}. One can start with one of the examples in: \begin{rawhtml} \end{rawhtml} @@ -747,15 +767,15 @@ MPIexec \begin{rawhtml} \end{rawhtml} \end{itemize} - + \item Build the code with the \texttt{genmake2} \texttt{-mpi} option - (see Section \ref{sect:genmake}) using commands such as: + (see Section \ref{sec:genmake}) using commands such as: {\footnotesize \begin{verbatim} % ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE % make depend % make \end{verbatim} } - + \item Run the code with the appropriate MPI ``run'' or ``exec'' program provided with your particular implementation of MPI. Typical MPI packages such as MPICH will use something like: @@ -767,10 +787,17 @@ library and a job scheduling and queueing system such as PBS, LoadLeveller, Condor, or any of a number of similar tools. A few example scripts (those used for our \begin{rawhtml} \end{rawhtml}regular + href="http://mitgcm.org/public/testing.html"> \end{rawhtml}regular verification runs\begin{rawhtml} \end{rawhtml}) are available at: \begin{rawhtml} + \end{rawhtml} + {\footnotesize \tt + http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example\_scripts/ } + \begin{rawhtml} \end{rawhtml} + or at: + \begin{rawhtml} \end{rawhtml} {\footnotesize \tt @@ -796,12 +823,12 @@ \end{verbatim} } \section[Running MITgcm]{Running the model in prognostic mode} -\label{sect:runModel} +\label{sec:runModel} \begin{rawhtml} \end{rawhtml} -If compilation finished succesfully (section \ref{sect:buildingCode}) +If compilation finished succesfully (section \ref{sec:buildingCode}) then an executable called \texttt{mitgcmuv} will now exist in the local directory. @@ -829,8 +856,6 @@ compare your \texttt{output.txt} with the corresponding one for that experiment to check that the set-up works. - - \subsection{Output files} The model produces various output files and, when using \texttt{mnc}, @@ -840,7 +865,6 @@ flags set (in \texttt{input/data.pkg}), the following output may appear. - \subsubsection{MDSIO output files} The ``traditional'' output files are generated by the \texttt{mdsio} @@ -888,7 +912,7 @@ containing the D-grid velocity data and that has to be written out as well in order to restart the integration. Rolling checkpoint files are the same -as the pickup files but are named differently. Their name contain the chain +as the pickup files but are named differently. Their name contain the chain \texttt{ckptA} or \texttt{ckptB} instead of \texttt{00000nIter}. They can be used to restart the model but are overwritten every other time they are output to save disk space during long integrations. @@ -897,7 +921,7 @@ Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output is usually (though not necessarily) placed within a subdirectory with -a name such as \texttt{mnc\_test\_\${DATE}\_\${SEQ}}. +a name such as \texttt{mnc\_test\_\${DATE}\_\${SEQ}}. \subsection{Looking at the output} @@ -952,7 +976,7 @@ http://meteora.ucsd.edu/~pierce/ncview_home_page.html \end{verbatim} \begin{rawhtml} \end{rawhtml} - + \item MatLAB(c) and other common post-processing environments provide various netCDF interfaces including: \begin{rawhtml} \end{rawhtml}