/[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.20 by edhill, Mon Feb 16 02:42:10 2004 UTC revision 1.26 by cnh, Wed Oct 13 05:06:25 2004 UTC
# Line 324  structure). Line 324  structure).
324    
325  \end{itemize}  \end{itemize}
326    
327  \section{Example experiments}  \section[MITgcm Example Experiments]{Example experiments}
328  \label{sect:modelExamples}  \label{sect:modelExamples}
329    
330  %% a set of twenty-four pre-configured numerical experiments  %% a set of twenty-four pre-configured numerical experiments
# Line 484  Each example directory has the following Line 484  Each example directory has the following
484  Once you have chosen the example you want to run, you are ready to  Once you have chosen the example you want to run, you are ready to
485  compile the code.  compile the code.
486    
487  \section{Building the code}  \section[Building MITgcm]{Building the code}
488  \label{sect:buildingCode}  \label{sect:buildingCode}
489    
490  To compile the code, we use the {\em make} program. This uses a file  To compile the code, we use the {\em make} program. This uses a file
# Line 666  the one experiment: Line 666  the one experiment:
666  \end{verbatim}  \end{verbatim}
667    
668    
669    \subsection{Using \texttt{genmake2}}
 \subsection{Using \textit{genmake2}}  
670  \label{sect:genmake}  \label{sect:genmake}
671    
672  To compile the code, first use the program \texttt{genmake2} (located  To compile the code, first use the program \texttt{genmake2} (located
673  in the \textit{tools} directory) to generate a Makefile.  in the \texttt{tools} directory) to generate a Makefile.
674  \texttt{genmake2} is a shell script written to work with all  \texttt{genmake2} is a shell script written to work with all
675  ``sh''--compatible shells including bash v1, bash v2, and Bourne.  ``sh''--compatible shells including bash v1, bash v2, and Bourne.
676  Internally, \texttt{genmake2} determines the locations of needed  Internally, \texttt{genmake2} determines the locations of needed
677  files, the compiler, compiler options, libraries, and Unix tools.  It  files, the compiler, compiler options, libraries, and Unix tools.  It
678  relies upon a number of ``optfiles'' located in the {\em  relies upon a number of ``optfiles'' located in the
679    tools/build\_options} directory.  \texttt{tools/build\_options} directory.
680    
681  The purpose of the optfiles is to provide all the compilation options  The purpose of the optfiles is to provide all the compilation options
682  for particular ``platforms'' (where ``platform'' roughly means the  for particular ``platforms'' (where ``platform'' roughly means the
# Line 772  The most important command-line options Line 771  The most important command-line options
771    the user's path.  When these three items have been identified,    the user's path.  When these three items have been identified,
772    genmake2 will try to find an optfile that has a matching name.    genmake2 will try to find an optfile that has a matching name.
773        
774    \item[\texttt{--pdefault='PKG1 PKG2 PKG3 ...'}] specifies the default
775      set of packages to be used.  The normal order of precedence for
776      packages is as follows:
777      \begin{enumerate}
778      \item If available, the command line (\texttt{--pdefault}) settings
779        over-rule any others.
780    
781      \item Next, \texttt{genmake2} will look for a file named
782        ``\texttt{packages.conf}'' in the local directory or in any of the
783        directories specified with the \texttt{--mods} option.
784        
785      \item Finally, if neither of the above are available,
786        \texttt{genmake2} will use the \texttt{/pkg/pkg\_default} file.
787      \end{enumerate}
788      
789  \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file  \item[\texttt{--pdepend=/PATH/FILENAME}] specifies the dependency file
790    used for packages.    used for packages.
791        
# Line 784  The most important command-line options Line 798  The most important command-line options
798    assumed that the two packages are compatible and will function    assumed that the two packages are compatible and will function
799    either with or without each other.    either with or without each other.
800        
 \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}  
     
801  \item[\texttt{--adof=/path/to/file}] specifies the "adjoint" or  \item[\texttt{--adof=/path/to/file}] specifies the "adjoint" or
802    automatic differentiation options file to be used.  The file is    automatic differentiation options file to be used.  The file is
803    analogous to the ``optfile'' defined above but it specifies    analogous to the ``optfile'' defined above but it specifies
# Line 819  The most important command-line options Line 827  The most important command-line options
827      ``-standarddirs'' option)      ``-standarddirs'' option)
828    \end{itemize}    \end{itemize}
829        
830    \item[\texttt{--mpi}] This option enables certain MPI features (using
831      CPP \texttt{\#define}s) within the code and is necessary for MPI
832      builds (see Section \ref{sect:mpi-build}).
833      
834  \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of  \item[\texttt{--make=/path/to/gmake}] Due to the poor handling of
835    soft-links and other bugs common with the \texttt{make} versions    soft-links and other bugs common with the \texttt{make} versions
836    provided by commercial Unix vendors, GNU \texttt{make} (sometimes    provided by commercial Unix vendors, GNU \texttt{make} (sometimes
837    called \texttt{gmake}) should be preferred.  This option provides a    called \texttt{gmake}) should be preferred.  This option provides a
838    means for specifying the make executable to be used.    means for specifying the make executable to be used.
839      
840    \item[\texttt{--bash=/path/to/sh}] On some (usually older UNIX)
841      machines, the ``bash'' shell is unavailable.  To run on these
842      systems, \texttt{genmake2} can be invoked using an ``sh'' (that is,
843      a Bourne, POSIX, or compatible) shell.  The syntax in these
844      circumstances is:
845      \begin{center}
846        \texttt{\%  /bin/sh genmake2 -bash=/bin/sh [...options...]}
847      \end{center}
848      where \texttt{/bin/sh} can be replaced with the full path and name
849      of the desired shell.
850    
851  \end{description}  \end{description}
852    
853    
854    \subsection{Building with MPI}
855    \label{sect:mpi-build}
856    
857    Building MITgcm to use MPI libraries can be complicated due to the
858    variety of different MPI implementations available, their dependencies
859    or interactions with different compilers, and their often ad-hoc
860    locations within file systems.  For these reasons, its generally a
861    good idea to start by finding and reading the documentation for your
862    machine(s) and, if necessary, seeking help from your local systems
863    administrator.
864    
865    The steps for building MITgcm with MPI support are:
866    \begin{enumerate}
867      
868    \item Determine the locations of your MPI-enabled compiler and/or MPI
869      libraries and put them into an options file as described in Section
870      \ref{sect:genmake}.  One can start with one of the examples in:
871      \begin{rawhtml} <A
872        href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/tools/build_options/">
873      \end{rawhtml}
874      \begin{center}
875        \texttt{MITgcm/tools/build\_options/}
876      \end{center}
877      \begin{rawhtml} </A> \end{rawhtml}
878      such as \texttt{linux\_ia32\_g77+mpi\_cg01} or
879      \texttt{linux\_ia64\_efc+mpi} and then edit it to suit the machine at
880      hand.  You may need help from your user guide or local systems
881      administrator to determine the exact location of the MPI libraries.
882      If libraries are not installed, MPI implementations and related
883      tools are available including:
884      \begin{itemize}
885      \item \begin{rawhtml} <A
886          href="http://www-unix.mcs.anl.gov/mpi/mpich/">
887        \end{rawhtml}
888        MPICH
889        \begin{rawhtml} </A> \end{rawhtml}
890    
891      \item \begin{rawhtml} <A
892          href="http://www.lam-mpi.org/">
893        \end{rawhtml}
894        LAM/MPI
895        \begin{rawhtml} </A> \end{rawhtml}
896    
897      \item \begin{rawhtml} <A
898          href="http://www.osc.edu/~pw/mpiexec/">
899        \end{rawhtml}
900        MPIexec
901        \begin{rawhtml} </A> \end{rawhtml}
902      \end{itemize}
903      
904    \item Build the code with the \texttt{genmake2} \texttt{-mpi} option
905      (see Section \ref{sect:genmake}) using commands such as:
906    {\footnotesize \begin{verbatim}
907      %  ../../../tools/genmake2 -mods=../code -mpi -of=YOUR_OPTFILE
908      %  make depend
909      %  make
910    \end{verbatim} }
911      
912    \item Run the code with the appropriate MPI ``run'' or ``exec''
913      program provided with your particular implementation of MPI.
914      Typical MPI packages such as MPICH will use something like:
915    \begin{verbatim}
916      %  mpirun -np 4 -machinefile mf ./mitgcmuv
917    \end{verbatim}
918      Sightly more complicated scripts may be needed for many machines
919      since execution of the code may be controlled by both the MPI
920      library and a job scheduling and queueing system such as PBS,
921      LoadLeveller, Condor, or any of a number of similar tools.  A few
922      example scripts (those used for our \begin{rawhtml} <A
923        href="http://mitgcm.org/testing.html"> \end{rawhtml}regular
924      verification runs\begin{rawhtml} </A> \end{rawhtml}) are available
925      at:
926      \begin{rawhtml} <A
927        href="http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm_contrib/test_scripts/">
928      \end{rawhtml}
929      {\footnotesize \tt
930        http://mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm\_contrib/test\_scripts/ }
931      \begin{rawhtml} </A> \end{rawhtml}
932    
933    \end{enumerate}
934    
935  \section{Running the model}  An example of the above process on the MITgcm cluster (``cg01'') using
936    the GNU g77 compiler and the mpich MPI library is:
937    
938    {\footnotesize \begin{verbatim}
939      %  cd MITgcm/verification/exp5
940      %  mkdir build
941      %  cd build
942      %  ../../../tools/genmake2 -mpi -mods=../code \
943           -of=../../../tools/build_options/linux_ia32_g77+mpi_cg01
944      %  make depend
945      %  make
946      %  cd ../input
947      %  /usr/local/pkg/mpi/mpi-1.2.4..8a-gm-1.5/g77/bin/mpirun.ch_gm \
948           -machinefile mf --gm-kill 5 -v -np 2  ../build/mitgcmuv
949    \end{verbatim} }
950    
951    
952    
953    \section[Running MITgcm]{Running the model in prognostic mode}
954  \label{sect:runModel}  \label{sect:runModel}
955    
956  If compilation finished succesfuully (section \ref{sect:buildModel})  If compilation finished succesfuully (section \ref{sect:buildingCode})
957  then an executable called {\em mitgcmuv} will now exist in the local  then an executable called \texttt{mitgcmuv} will now exist in the
958  directory.  local directory.
959    
960  To run the model as a single process (ie. not in parallel) simply  To run the model as a single process (ie. not in parallel) simply
961  type:  type:
# Line 938  Some examples of reading and visualizing Line 1059  Some examples of reading and visualizing
1059  >> for n=1:11; imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end  >> for n=1:11; imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
1060  \end{verbatim}  \end{verbatim}
1061    
1062  \section{Doing it yourself: customizing the code}  \section[Customizing MITgcm]{Doing it yourself: customizing the code}
1063    
1064  When you are ready to run the model in the configuration you want, the  When you are ready to run the model in the configuration you want, the
1065  easiest thing is to use and adapt the setup of the case studies  easiest thing is to use and adapt the setup of the case studies
Legend:
Removed from v.1.20  
changed lines
  Added in v.1.26
  ViewVC Help
Powered by ViewVC 1.1.22