/[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.4 by adcroft, Mon Oct 15 19:35:11 2001 UTC revision 1.11 by adcroft, Tue Dec 4 18:08:34 2001 UTC
# Line 36  A mail to the email list will reach all Line 36  A mail to the email list will reach all
36  on the newsgroup. A users email list will be established at some time  on the newsgroup. A users email list will be established at some time
37  in the future.  in the future.
38    
   
39  \section{Obtaining the code}  \section{Obtaining the code}
40  \label{sect:obtainingCode}  \label{sect:obtainingCode}
41    
42    MITgcm can be downloaded from our system by following
43    the instructions below. As a courtesy we ask that you send e-mail to us at
44    \begin{rawhtml} <A href=mailto:support@mitgcm.org> \end{rawhtml}
45    support@mitgcm.org
46    \begin{rawhtml} </A> \end{rawhtml}
47    to enable us to keep track of who's using the model and in what application.
48    You can download the model two ways:
49    
50    \begin{enumerate}
51    \item Using CVS software. CVS is a freely available source code management
52    tool. To use CVS you need to have the software installed. Many systems
53    come with CVS pre-installed, otherwise good places to look for
54    the software for a particular platform are
55    \begin{rawhtml} <A href=http://www.cvshome.org/ target="idontexist"> \end{rawhtml}
56    cvshome.org
57    \begin{rawhtml} </A> \end{rawhtml}
58    and
59    \begin{rawhtml} <A href=http://www.wincvs.org/ target="idontexist"> \end{rawhtml}
60    wincvs.org
61    \begin{rawhtml} </A> \end{rawhtml}
62    .
63    
64    \item Using a tar file. This method is simple and does not
65    require any special software. However, this method does not
66    provide easy support for maintenance updates.
67    
68    \end{enumerate}
69    
70  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
71  provides an efficient and elegant way of organizing your code and keeping  provides an efficient and elegant way of organizing your code and keeping
72  track of your changes. If CVS is not available on your machine, you can also  track of your changes. If CVS is not available on your machine, you can also
# Line 49  Before you can use CVS, the following en Line 76  Before you can use CVS, the following en
76  your .cshrc or .tcshrc:  your .cshrc or .tcshrc:
77  \begin{verbatim}  \begin{verbatim}
78  % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/u0/gcmpack  % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/u0/gcmpack
79    \end{verbatim}
80    
81    To start using CVS, register with the MITgcm CVS server using command:
82    \begin{verbatim}
83  % cvs login ( CVS password: cvsanon )  % cvs login ( CVS password: cvsanon )
84  \end{verbatim}  \end{verbatim}
85    You only need to do ``cvs login'' once.
86    
87  You only need to do ``cvs login'' once. To obtain the source for the release:  To obtain the sources for release1 type:
88  \begin{verbatim}  \begin{verbatim}
89  % cvs co -d directory -P -r release1 MITgcmUV  % cvs co -d directory -P -r release1_beta1 MITgcm
90  \end{verbatim}  \end{verbatim}
91    
92  This creates a directory called \textit{directory}. If \textit{directory}  This creates a directory called \textit{directory}. If \textit{directory}
93  exists this command updates your code based on the repository. Each  exists this command updates your code based on the repository. Each
94  directory in the source tree contains a directory \textit{CVS}. This  directory in the source tree contains a directory \textit{CVS}. This
95  information is required by CVS to keep track of your file versions with  information is required by CVS to keep track of your file versions with
96  respect to the repository. Don't edit the files in \textit{CVS}! To obtain a  respect to the repository. Don't edit the files in \textit{CVS}!
97  different \textit{version} that is not the latest source:  You can also use CVS to download code updates.  More extensive
98  \begin{verbatim}  information on using CVS for maintaining MITgcm code can be found
99  % cvs co -d directory -P -r version MITgcm  \begin{rawhtml} <A href=http://mitgcm.org/usingcvstoget.html target="idontexist"> \end{rawhtml}
100  \end{verbatim}  here
101  or the latest development version:  \begin{rawhtml} </A> \end{rawhtml}
102  \begin{verbatim}  .
103  % cvs co -d directory -P MITgcm  
 \end{verbatim}  
104    
105  \paragraph*{Conventional download method}  \paragraph*{Conventional download method}
106  \label{sect:conventionalDownload}  \label{sect:conventionalDownload}
107    
108  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
109  tar file from the reference web site at:  tar file from the reference web site at:
110    \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
111  \begin{verbatim}  \begin{verbatim}
112  http://mitgcm.org/download/  http://mitgcm.org/download/
113  \end{verbatim}  \end{verbatim}
114    \begin{rawhtml} </A> \end{rawhtml}
115  The tar file still contains CVS information which we urge you not to  The tar file still contains CVS information which we urge you not to
116  delete; even if you do not use CVS yourself the information can help  delete; even if you do not use CVS yourself the information can help
117  us if you should need to send us your copy of the code.  us if you should need to send us your copy of the code.
# Line 106  directory in which to compile the code. Line 139  directory in which to compile the code.
139    
140  \item \textit{diags}: contains the code relative to time-averaged  \item \textit{diags}: contains the code relative to time-averaged
141  diagnostics. It is subdivided into two subdirectories \textit{inc} and  diagnostics. It is subdivided into two subdirectories \textit{inc} and
142  \textit{src} that contain include files (*.\textit{h} files) and fortran  \textit{src} that contain include files (*.\textit{h} files) and Fortran
143  subroutines (*.\textit{F} files), respectively.  subroutines (*.\textit{F} files), respectively.
144    
145  \item \textit{doc}: contains brief documentation notes.  \item \textit{doc}: contains brief documentation notes.
# Line 147  section \ref{sect:modelExamples}. Line 180  section \ref{sect:modelExamples}.
180  \section{Example experiments}  \section{Example experiments}
181  \label{sect:modelExamples}  \label{sect:modelExamples}
182    
183  Now that you have successfully downloaded the model code we recommend that  The MITgcm distribution comes with a set of twenty-four pre-configured
184  you first try to run the examples provided with the base version. You will  numerical experiments. Some of these examples experiments are tests of
185  probably want to run the example that is the closest to the configuration  individual parts of the model code, but many are fully fledged numerical
186  you will use eventually. The examples are located in subdirectories under  simulations. A few of the examples are used for tutorial documentation
187  the directory \textit{verification} and are briefly described below (a full  in sections \ref{sect:eg-baro} - \ref{sect:eg-global}. The other examples
188  description is given in section 2):  follow the same general structure as the tutorial examples. However,
189    they only include brief instructions in a text file called {\it README}.
190    The examples are located in subdirectories under
191    the directory \textit{verification}. Each
192    example is briefly described below.
193    
194  \subsection{List of model examples}  \subsection{Full list of model examples}
195    
196  \begin{itemize}  \begin{enumerate}
197  \item \textit{exp0} - single layer, ocean double gyre (barotropic with  \item \textit{exp0} - single layer, ocean double gyre (barotropic with
198  free-surface).  free-surface). This experiment is described in detail in section
199    \ref{sect:eg-baro}.
200    
201  \item \textit{exp1} - 4 layers, ocean double gyre.  \item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section
202    \ref{sect:eg-baroc}.
203    
204  \item \textit{exp2} - 4x4 degree global ocean simulation with steady  \item \textit{exp2} - 4x4 degree global ocean simulation with steady
205  climatological forcing.  climatological forcing. This experiment is described in detail in section
206    \ref{sect:eg-global}.
207    
208  \item \textit{exp4} - flow over a Gaussian bump in open-water or channel  \item \textit{exp4} - Flow over a Gaussian bump in open-water or channel
209  with open boundaries.  with open boundaries.
210    
211  \item \textit{exp5} - inhomogenously forced ocean convection in a doubly  \item \textit{exp5} - Inhomogenously forced ocean convection in a doubly
212  periodic box.  periodic box.
213    
214  \item \textit{front\_relax} - relaxation of an ocean thermal front (test for  \item \textit{front\_relax} - Relaxation of an ocean thermal front (test for
215  Gent/McWilliams scheme). 2D (Y-Z).  Gent/McWilliams scheme). 2D (Y-Z).
216    
217  \item \textit{internal wave} - ocean internal wave forced by open boundary  \item \textit{internal wave} - Ocean internal wave forced by open boundary
218  conditions.  conditions.
219    
220  \item \textit{natl\_box} - eastern subtropical North Atlantic with KPP  \item \textit{natl\_box} - Eastern subtropical North Atlantic with KPP
221  scheme; 1 month integration  scheme; 1 month integration
222    
223  \item \textit{hs94.1x64x5} - zonal averaged atmosphere using Held and Suarez  \item \textit{hs94.1x64x5} - Zonal averaged atmosphere using Held and Suarez
224  '94 forcing.  '94 forcing.
225    
226  \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez  \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez
# Line 189  scheme; 1 month integration Line 229  scheme; 1 month integration
229  \item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and  \item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
230  Suarez '94 forcing on the cubed sphere.  Suarez '94 forcing on the cubed sphere.
231    
232  \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics, 5 layers  \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. Global
233  Molteni physics package. Global Zonal Mean configuration, 1x64x5 resolution.  Zonal Mean configuration, 1x64x5 resolution.
234    
235  \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric  \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric
236  physics, 5 layers Molteni physics package. Equatorial Slice configuration.  physics, equatorial Slice configuration.
237  2D (X-Z).  2D (X-Z).
238    
239  \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric  \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
240  physics, 5 layers Molteni physics package. 3D Equatorial Channel  physics. 3D Equatorial Channel configuration.
 configuration (not completely tested).  
241    
242  \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics, 5 layers  \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics.
243  Molteni physics package. Global configuration, 128x64x5 resolution.  Global configuration, on latitude longitude grid with 128x64x5 grid points
244    ($2.8^\circ{\rm degree}$ resolution).
245    
246  \item \textit{adjustment.128x64x1}  \item \textit{adjustment.128x64x1} Barotropic adjustment
247    problem on latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm degree}$ resolution).
248    
249  \item \textit{adjustment.cs-32x32x1}  \item \textit{adjustment.cs-32x32x1}
250  \end{itemize}  Barotropic adjustment
251    problem on cube sphere grid with 32x32 points per face ( roughly
252    $2.8^\circ{\rm degree}$ resolution).
253    
254    \item \textit{advect\_cs} Two-dimensional passive advection test on
255    cube sphere grid.
256    
257    \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection
258    test on Cartesian grid.
259    
260    \item \textit{advect\_yz} Two-dimensional (vertical plane) passive advection test on Cartesian grid.
261    
262    \item \textit{carbon} Simple passive tracer experiment. Includes derivative
263    calculation. Described in detail in section \ref{sect:eg-carbon-ad}.
264    
265    \item \textit{flt\_example} Example of using float package.
266    
267    \item \textit{global\_ocean.90x40x15} Global circulation with
268    GM, flux boundary conditions and poles.
269    
270    \item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube sphere
271    grid.
272    
273    \end{enumerate}
274    
275  \subsection{Directory structure of model examples}  \subsection{Directory structure of model examples}
276    
# Line 233  In addition, other include files and sub Line 297  In addition, other include files and sub
297  code} depending on the particular experiment. See section 2 for more details.  code} depending on the particular experiment. See section 2 for more details.
298    
299  \item \textit{input}: contains the input data files required to run the  \item \textit{input}: contains the input data files required to run the
300  example. At a mimimum, the \textit{input} directory contains the following  example. At a minimum, the \textit{input} directory contains the following
301  files:  files:
302    
303  \begin{itemize}  \begin{itemize}
# Line 266  the code. Line 330  the code.
330  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
331  ({\em Makefile}) that allows us to pre-process source files, specify  ({\em Makefile}) that allows us to pre-process source files, specify
332  compiler and optimization options and also figures out any file  compiler and optimization options and also figures out any file
333  dependancies. We supply a script ({\em genmake}), described in section  dependencies. We supply a script ({\em genmake}), described in section
334  \ref{sect:genmake}, that automatically creates the {\em Makefile} for  \ref{sect:genmake}, that automatically creates the {\em Makefile} for
335  you. You then need to build the dependancies and compile the code.  you. You then need to build the dependencies and compile the code.
336    
337  As an example, let's assume that you want to build and run experiment  As an example, let's assume that you want to build and run experiment
338  \textit{verification/exp2}. The are multiple ways and places to actually  \textit{verification/exp2}. The are multiple ways and places to actually
# Line 290  to use the following options when invoki Line 354  to use the following options when invoki
354  % ../../../tools/genmake  -mods=../code  % ../../../tools/genmake  -mods=../code
355  \end{verbatim}  \end{verbatim}
356    
357  Next, create the dependancies:  Next, create the dependencies:
358  \begin{verbatim}  \begin{verbatim}
359  % make depend  % make depend
360  \end{verbatim}  \end{verbatim}
# Line 342  files must be in the same place. If you Line 406  files must be in the same place. If you
406  % cp ../code/mitgcmuv ./  % cp ../code/mitgcmuv ./
407  % ./mitgcmuv > output.txt  % ./mitgcmuv > output.txt
408  \end{verbatim}  \end{verbatim}
409  or if you will be making muliple runs with the same executable:  or if you will be making multiple runs with the same executable:
410  \begin{verbatim}  \begin{verbatim}
411  % cd ../  % cd ../
412  % cp -r input run1  % cp -r input run1
# Line 354  or if you will be making muliple runs wi Line 418  or if you will be making muliple runs wi
418  \subsubsection{Building from a new directory}  \subsubsection{Building from a new directory}
419    
420  Since the {\em input} directory contains input files it is often more  Since the {\em input} directory contains input files it is often more
421  useful to keep {\em input} prestine and build in a new directory  useful to keep {\em input} pristine and build in a new directory
422  within {\em verification/exp2/}:  within {\em verification/exp2/}:
423  \begin{verbatim}  \begin{verbatim}
424  % cd verification/exp2  % cd verification/exp2
# Line 639  relative to the ''numerical model'' part Line 703  relative to the ''numerical model'' part
703  the ''execution environment'' part is covered in the parallel implementation  the ''execution environment'' part is covered in the parallel implementation
704  section) and on the variables and parameters that you are likely to change.  section) and on the variables and parameters that you are likely to change.
705    
706  \subsection{\protect\bigskip Configuration and setup}  \subsection{Configuration and setup}
707    
708  The CPP keys relative to the ''numerical model'' part of the code are all  The CPP keys relative to the ''numerical model'' part of the code are all
709  defined and set in the file \textit{CPP\_OPTIONS.h }in the directory \textit{%  defined and set in the file \textit{CPP\_OPTIONS.h }in the directory \textit{%
Legend:
Removed from v.1.4  
changed lines
  Added in v.1.11
  ViewVC Help
Powered by ViewVC 1.1.22