--- manual/s_getstarted/text/getting_started.tex	2004/01/29 19:22:35	1.18
+++ manual/s_getstarted/text/getting_started.tex	2004/04/08 02:24:23	1.23
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.18 2004/01/29 19:22:35 edhill Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.23 2004/04/08 02:24:23 edhill Exp $
 % $Name:  $
 
 %\section{Getting started}
@@ -79,6 +79,9 @@
 
 \end{enumerate}
 
+\subsubsection{Checkout from CVS}
+\label{sect: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
 track of your changes. If CVS is not available on your machine, you can also
@@ -93,7 +96,7 @@
 \begin{verbatim}
 % export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
 \end{verbatim}
-in your .profile or .bashrc file.
+in your \texttt{.profile} or \texttt{.bashrc} file.
 
 
 To get MITgcm through CVS, first register with the MITgcm CVS server
@@ -121,6 +124,28 @@
 \end{verbatim}
 \begin{rawhtml} </A> \end{rawhtml}
 
+As a convenience, the MITgcm CVS server contains aliases which are
+named subsets of the codebase.  These aliases can be especially
+helpful when used over slow internet connections or on machines with
+restricted storage space.  Table \ref{tab:cvsModules} contains a list
+of CVS aliases
+\begin{table}[htb]
+  \centering
+  \begin{tabular}[htb]{|lp{3.25in}|}\hline
+    \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}, 
+    \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.  \\
+    \texttt{MITgcm\_verif\_all}    &  Source code plus all of the
+    verification examples. \\\hline
+  \end{tabular}
+  \caption{MITgcm CVS Modules}
+  \label{tab:cvsModules}
+\end{table}
 
 The checkout process creates a directory called \textit{MITgcm}. If
 the directory \textit{MITgcm} exists this command updates your code
@@ -134,9 +159,17 @@
 here
 \begin{rawhtml} </A> \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
+   %  mv MITgcm MITgcm_verif_basic
+\end{verbatim}
 
 
-\paragraph*{Conventional download method}
+\subsubsection{Conventional download method}
 \label{sect:conventionalDownload}
 
 If you do not have CVS on your system, you can download the model as a
@@ -156,7 +189,7 @@
 \begin{rawhtml} </A> \end{rawhtml}
 mailing list.
 
-\paragraph*{Upgrading from an earlier version}
+\subsubsection{Upgrading from an earlier version}
 
 If you already have an earlier version of the code you can ``upgrade''
 your copy instead of downloading the entire repository again. First,
@@ -633,7 +666,6 @@
 \end{verbatim}
 
 
-
 \subsection{Using \textit{genmake2}}
 \label{sect:genmake}
 
@@ -739,6 +771,21 @@
   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{--pdepend=/PATH/FILENAME}] specifies the dependency file
   used for packages.
   
@@ -751,12 +798,6 @@
   assumed that the two packages are compatible and will function
   either with or without each other.
   
-\item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default
-  set of packages to be used.
-  
-  If not set, the default package list will be read from {\em
-    pkg/pkg\_default}
-  
 \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
@@ -786,22 +827,109 @@
     ``-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}).
+  
 \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,
+  a Bourne, POSIX, or compatible) shell.  The syntax in these
+  circumstances is:
+  \begin{center}
+    \texttt{\%  /bin/sh genmake2 -bash=/bin/sh [...options...]}
+  \end{center}
+  where \texttt{/bin/sh} can be replaced with the full path and name
+  of the desired shell.
 
 \end{description}
 
 
+\subsection{Building with MPI}
+\label{sect:mpi-build}
+
+Building MITgcm to use MPI libraries can be complicated due to the
+variety of different MPI implementations available, their dependencies
+or interactions with different compilers, and their often ad-hoc
+locations within file systems.  For these reasons, its generally a
+good idea to start by finding and reading the documentation for your
+machine(s) and, if necessary, seeking help from your local systems
+administrator.
+
+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:
+  \begin{rawhtml} <A
+    href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/tools/build_options/">
+  \end{rawhtml}
+  \begin{center}
+    \texttt{MITgcm/tools/build\_options/}
+  \end{center}
+  \begin{rawhtml} </A> \end{rawhtml}
+  such as \texttt{linux\_ia32\_g77+mpi\_cg01} or
+  \texttt{linux\_ia64\_efc+mpi} and then edit it to suit the machine at
+  hand.  You may need help from your user guide or local systems
+  administrator to determine the exact location of the MPI libraries.
+  If libraries are not installed, MPI implementations and related
+  tools are available including:
+  \begin{itemize}
+  \item \begin{rawhtml} <A
+      href="http://www-unix.mcs.anl.gov/mpi/mpich/">
+    \end{rawhtml}
+    MPICH
+    \begin{rawhtml} </A> \end{rawhtml}
+
+  \item \begin{rawhtml} <A
+      href="http://www.lam-mpi.org/">
+    \end{rawhtml}
+    LAM/MPI
+    \begin{rawhtml} </A> \end{rawhtml}
+
+  \item \begin{rawhtml} <A
+      href="http://www.osc.edu/~pw/mpiexec/">
+    \end{rawhtml}
+    MPIexec
+    \begin{rawhtml} </A> \end{rawhtml}
+  \end{itemize}
+  
+\item Build the code with the \texttt{genmake2} \texttt{-mpi} option
+  (see Section \ref{sect: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:
+\begin{verbatim}
+  %  mpirun -np 4 -machinefile mf ./mitgcmuv
+\end{verbatim}
+  Sightly more complicated scripts may be needed for many machines
+  since execution of the code may be controlled by both the MPI
+  library and a job scheduling and queueing system such as PBS,
+  LoadLeveller, Condor, or any of a number of similar tools.
+
+\end{enumerate}
+
+
 
 \section{Running the model}
 \label{sect:runModel}
 
-If compilation finished succesfuully (section \ref{sect:buildModel})
-then an executable called {\em mitgcmuv} will now exist in the local
-directory.
+If compilation finished succesfuully (section \ref{sect:buildingCode})
+then an executable called \texttt{mitgcmuv} will now exist in the
+local directory.
 
 To run the model as a single process (ie. not in parallel) simply
 type:
