/[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.1.1.1 by adcroft, Wed Aug 8 16:15:31 2001 UTC revision 1.15 by edhill, Wed Jan 28 20:50:14 2004 UTC
# Line 1  Line 1 
1  % $Header$  % $Header$
2  % $Name$  % $Name$
3    
4    %\section{Getting started}
5    
6  \begin{center}  In this section, we describe how to use the model. In the first
7  {\Large \textbf{Using the model}}  section, we provide enough information to help you get started with
8    the model. We believe the best way to familiarize yourself with the
9    model is to run the case study examples provided with the base
10    version. Information on how to obtain, compile, and run the code is
11    found there as well as a brief description of the model structure
12    directory and the case study examples.  The latter and the code
13    structure are described more fully in chapters
14    \ref{chap:discretization} and \ref{chap:sarch}, respectively. Here, in
15    this section, we provide information on how to customize the code when
16    you are ready to try implementing the configuration you have in mind.
17    
18  \vspace*{4mm}  \section{Where to find information}
19    \label{sect:whereToFindInfo}
20    
21  \vspace*{3mm} {\large July 2001}  A web site is maintained for release 2 (``Pelican'') of MITgcm:
22  \end{center}  \begin{rawhtml} <A href=http://mitgcm.org/pelican/ target="idontexist"> \end{rawhtml}
23    \begin{verbatim}
24    http://mitgcm.org/pelican
25    \end{verbatim}
26    \begin{rawhtml} </A> \end{rawhtml}
27    Here you will find an on-line version of this document, a
28    ``browsable'' copy of the code and a searchable database of the model
29    and site, as well as links for downloading the model and
30    documentation, to data-sources, and other related sites.
31    
32    There is also a web-archived support mailing list for the model that
33    you can email at \texttt{MITgcm-support@mitgcm.org} or browse at:
34    \begin{rawhtml} <A href=http://mitgcm.org/mailman/listinfo/mitgcm-support/ target="idontexist"> \end{rawhtml}
35    \begin{verbatim}
36    http://mitgcm.org/mailman/listinfo/mitgcm-support/
37    http://mitgcm.org/pipermail/mitgcm-support/
38    \end{verbatim}
39    \begin{rawhtml} </A> \end{rawhtml}
40    Essentially all of the MITgcm web pages can be searched using a
41    popular web crawler such as Google or through our own search facility:
42    \begin{verbatim}
43    http://mitgcm.org/htdig/
44    \end{verbatim}
45    \begin{rawhtml} </A> \end{rawhtml}
46    %%% http://www.google.com/search?q=hydrostatic+site%3Amitgcm.org
47    
 In this part, we describe how to use the model. In the first section, we  
 provide enough information to help you get started with the model. We  
 believe the best way to familiarize yourself with the model is to run the  
 case study examples provided with the base version. Information on how to  
 obtain, compile, and run the code is found there as well as a brief  
 description of the model structure directory and the case study examples.  
 The latter and the code structure are described more fully in sections 2 and  
 3, respectively. In section 4, we provide information on how to customize  
 the code when you are ready to try implementing the configuration you have  
 in mind.  
48    
 \section{Getting started}  
49    
50  \subsection{Obtaining the code}  \section{Obtaining the code}
51    \label{sect:obtainingCode}
52    
53  The reference web site for the model is:  MITgcm can be downloaded from our system by following
54  \begin{verbatim}  the instructions below. As a courtesy we ask that you send e-mail to us at
55  http://mitgcm.org  \begin{rawhtml} <A href=mailto:MITgcm-support@mitgcm.org> \end{rawhtml}
56  \end{verbatim}  MITgcm-support@mitgcm.org
57    \begin{rawhtml} </A> \end{rawhtml}
58    to enable us to keep track of who's using the model and in what application.
59    You can download the model two ways:
60    
61    \begin{enumerate}
62    \item Using CVS software. CVS is a freely available source code management
63    tool. To use CVS you need to have the software installed. Many systems
64    come with CVS pre-installed, otherwise good places to look for
65    the software for a particular platform are
66    \begin{rawhtml} <A href=http://www.cvshome.org/ target="idontexist"> \end{rawhtml}
67    cvshome.org
68    \begin{rawhtml} </A> \end{rawhtml}
69    and
70    \begin{rawhtml} <A href=http://www.wincvs.org/ target="idontexist"> \end{rawhtml}
71    wincvs.org
72    \begin{rawhtml} </A> \end{rawhtml}
73    .
74    
75    \item Using a tar file. This method is simple and does not
76    require any special software. However, this method does not
77    provide easy support for maintenance updates.
78    
79  On this site, you can download the model as well as find useful information,  \end{enumerate}
 some of which might overlap with what is written here. There is also a  
 support news group for the model located at (send your message to \texttt{%  
 support@mitgcm.org}):  
 \begin{verbatim}  
 news://mitgcm.org/mitgcm.support  
 \end{verbatim}  
80    
81  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
82  provides an efficient and elegant way of organizing your code and keeping  provides an efficient and elegant way of organizing your code and keeping
83  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
84  download a tar file.  download a tar file.
85    
86  \subsubsection{using CVS}  Before you can use CVS, the following environment variable(s) should
87    be set within your shell.  For a csh or tcsh shell, put the following
88    \begin{verbatim}
89    % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/gcmpack
90    \end{verbatim}
91    in your .cshrc or .tcshrc file.  For bash or sh shells, put:
92    \begin{verbatim}
93    % export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack'
94    \end{verbatim}
95    in your .profile or .bashrc file.
96    
97    
98  Before you can use CVS, the following environment variable has to be set in  To get MITgcm through CVS, first register with the MITgcm CVS server
99  your .cshrc or .tcshrc:  using command:
100  \begin{verbatim}  \begin{verbatim}
 % setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/u0/gcmpack  
101  % cvs login ( CVS password: cvsanon )  % cvs login ( CVS password: cvsanon )
102  \end{verbatim}  \end{verbatim}
103    You only need to do a ``cvs login'' once.
104    
105  You only need to do ``cvs login'' once. To obtain the latest source:  To obtain the latest sources type:
106  \begin{verbatim}  \begin{verbatim}
107  % cvs co -d directory models/MITgcmUV  % cvs co MITgcm
108  \end{verbatim}  \end{verbatim}
109    or to get a specific release type:
110  This creates a directory called \textit{directory}. If \textit{directory}  \begin{verbatim}
111  exists this command updates your code based on the repository. Each  % cvs co -d directory -P -r release1_beta1 MITgcm
112  directory in the source tree contains a directory \textit{CVS}. This  \end{verbatim}
113  information is required by CVS to keep track of your file versions with  The MITgcm web site contains further directions concerning the source
114  respect to the repository. Don't edit the files in \textit{CVS}! To obtain a  code and CVS.  It also contains a web interface to our CVS archive so
115  specific \textit{version} that is not the latest source:  that one may easily view the state of files, revisions, and other
116    development milestones:
117    \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
118  \begin{verbatim}  \begin{verbatim}
119  % cvs co -d directory -r version models/MITgcmUV  http://mitgcm.org/source_code.html
120  \end{verbatim}  \end{verbatim}
121    \begin{rawhtml} </A> \end{rawhtml}
122    
 \subsubsection{other methods}  
123    
124  You can download the model as a tar file from the reference web site at:  The checkout process creates a directory called \textit{MITgcm}. If
125    the directory \textit{MITgcm} exists this command updates your code
126    based on the repository. Each directory in the source tree contains a
127    directory \textit{CVS}. This information is required by CVS to keep
128    track of your file versions with respect to the repository. Don't edit
129    the files in \textit{CVS}!  You can also use CVS to download code
130    updates.  More extensive information on using CVS for maintaining
131    MITgcm code can be found
132    \begin{rawhtml} <A href=http://mitgcm.org/usingcvstoget.html target="idontexist"> \end{rawhtml}
133    here
134    \begin{rawhtml} </A> \end{rawhtml}
135    .
136    
137    
138    \paragraph*{Conventional download method}
139    \label{sect:conventionalDownload}
140    
141    If you do not have CVS on your system, you can download the model as a
142    tar file from the web site at:
143    \begin{rawhtml} <A href=http://mitgcm.org/download target="idontexist"> \end{rawhtml}
144  \begin{verbatim}  \begin{verbatim}
145  http://mitgcm.org/download/  http://mitgcm.org/download/
146  \end{verbatim}  \end{verbatim}
147    \begin{rawhtml} </A> \end{rawhtml}
148  \subsection{Model and directory structure}  The tar file still contains CVS information which we urge you not to
149    delete; even if you do not use CVS yourself the information can help
150  The ``numerical'' model is contained within a execution environment support  us if you should need to send us your copy of the code.  If a recent
151  wrapper. This wrapper is designed to provide a general framework for  tar file does not exist, then please contact the developers through
152  grid-point models. MITgcmUV is a specific numerical model that uses the  the MITgcm-support list.
153  framework. Under this structure the model is split into execution  
154  environment support code and conventional numerical model code. The  \paragraph*{Upgrading from an earlier version}
155  execution environment support code is held under the \textit{eesupp}  
156  directory. The grid point model code is held under the \textit{model}  If you already have an earlier version of the code you can ``upgrade''
157  directory. Code execution actually starts in the \textit{eesupp} routines  your copy instead of downloading the entire repository again. First,
158  and not in the \textit{model} routines. For this reason the top-level  ``cd'' (change directory) to the top of your working copy:
159    \begin{verbatim}
160    % cd MITgcm
161    \end{verbatim}
162    and then issue the cvs update command such as:
163    \begin{verbatim}
164    % cvs -q update -r release1_beta1 -d -P
165    \end{verbatim}
166    This will update the ``tag'' to ``release1\_beta1'', add any new
167    directories (-d) and remove any empty directories (-P). The -q option
168    means be quiet which will reduce the number of messages you'll see in
169    the terminal. If you have modified the code prior to upgrading, CVS
170    will try to merge your changes with the upgrades. If there is a
171    conflict between your modifications and the upgrade, it will report
172    that file with a ``C'' in front, e.g.:
173    \begin{verbatim}
174    C model/src/ini_parms.F
175    \end{verbatim}
176    If the list of conflicts scrolled off the screen, you can re-issue the
177    cvs update command and it will report the conflicts. Conflicts are
178    indicated in the code by the delimites ``$<<<<<<<$'', ``======='' and
179    ``$>>>>>>>$''. For example,
180    \begin{verbatim}
181    <<<<<<< ini_parms.F
182         & bottomDragLinear,myOwnBottomDragCoefficient,
183    =======
184         & bottomDragLinear,bottomDragQuadratic,
185    >>>>>>> 1.18
186    \end{verbatim}
187    means that you added ``myOwnBottomDragCoefficient'' to a namelist at
188    the same time and place that we added ``bottomDragQuadratic''. You
189    need to resolve this conflict and in this case the line should be
190    changed to:
191    \begin{verbatim}
192         & bottomDragLinear,bottomDragQuadratic,myOwnBottomDragCoefficient,
193    \end{verbatim}
194    and the lines with the delimiters ($<<<<<<$,======,$>>>>>>$) be deleted.
195    Unless you are making modifications which exactly parallel
196    developments we make, these types of conflicts should be rare.
197    
198    \paragraph*{Upgrading to the current pre-release version}
199    
200    We don't make a ``release'' for every little patch and bug fix in
201    order to keep the frequency of upgrades to a minimum. However, if you
202    have run into a problem for which ``we have already fixed in the
203    latest code'' and we haven't made a ``tag'' or ``release'' since that
204    patch then you'll need to get the latest code:
205    \begin{verbatim}
206    % cvs -q update -A -d -P
207    \end{verbatim}
208    Unlike, the ``check-out'' and ``update'' procedures above, there is no
209    ``tag'' or release name. The -A tells CVS to upgrade to the
210    very latest version. As a rule, we don't recommend this since you
211    might upgrade while we are in the processes of checking in the code so
212    that you may only have part of a patch. Using this method of updating
213    also means we can't tell what version of the code you are working
214    with. So please be sure you understand what you're doing.
215    
216    \section{Model and directory structure}
217    
218    The ``numerical'' model is contained within a execution environment
219    support wrapper. This wrapper is designed to provide a general
220    framework for grid-point models. MITgcmUV is a specific numerical
221    model that uses the framework. Under this structure the model is split
222    into execution environment support code and conventional numerical
223    model code. The execution environment support code is held under the
224    \textit{eesupp} directory. The grid point model code is held under the
225    \textit{model} directory. Code execution actually starts in the
226    \textit{eesupp} routines and not in the \textit{model} routines. For
227    this reason the top-level
228  \textit{MAIN.F} is in the \textit{eesupp/src} directory. In general,  \textit{MAIN.F} is in the \textit{eesupp/src} directory. In general,
229  end-users should not need to worry about this level. The top-level routine  end-users should not need to worry about this level. The top-level routine
230  for the numerical part of the code is in \textit{model/src/THE\_MODEL\_MAIN.F%  for the numerical part of the code is in \textit{model/src/THE\_MODEL\_MAIN.F%
# Line 97  directory in which to compile the code. Line 237  directory in which to compile the code.
237    
238  \item \textit{diags}: contains the code relative to time-averaged  \item \textit{diags}: contains the code relative to time-averaged
239  diagnostics. It is subdivided into two subdirectories \textit{inc} and  diagnostics. It is subdivided into two subdirectories \textit{inc} and
240  \textit{src} that contain include files (*.\textit{h} files) and fortran  \textit{src} that contain include files (*.\textit{h} files) and Fortran
241  subroutines (*.\textit{F} files), respectively.  subroutines (*.\textit{F} files), respectively.
242    
243  \item \textit{doc}: contains brief documentation notes.  \item \textit{doc}: contains brief documentation notes.
# Line 118  relative to the atmospheric intermediate Line 258  relative to the atmospheric intermediate
258  in detail in section 3.  in detail in section 3.
259    
260  \item \textit{tools}: this directory contains various useful tools. For  \item \textit{tools}: this directory contains various useful tools. For
261  example, \textit{genmake} is a script written in csh (C-shell) that should  example, \textit{genmake2} is a script written in csh (C-shell) that should
262  be used to generate your makefile. The directory \textit{adjoint} contains  be used to generate your makefile. The directory \textit{adjoint} contains
263  the makefile specific to the Tangent linear and Adjoint Compiler (TAMC) that  the makefile specific to the Tangent linear and Adjoint Compiler (TAMC) that
264  generates the adjoint code. The latter is described in details in part V.  generates the adjoint code. The latter is described in details in part V.
265    
266  \item \textit{utils}: this directory contains various utilities. The  \item \textit{utils}: this directory contains various utilities. The
267  subdirectory \textit{knudsen2} contains code and a makefile that compute  subdirectory \textit{knudsen2} contains code and a makefile that
268  coefficients of the polynomial approximation to the knudsen formula for an  compute coefficients of the polynomial approximation to the knudsen
269  ocean nonlinear equation of state. The \textit{matlab} subdirectory contains  formula for an ocean nonlinear equation of state. The \textit{matlab}
270  matlab scripts for reading model output directly into matlab. \textit{scripts%  subdirectory contains matlab scripts for reading model output directly
271  } contains C-shell post-processing scripts for joining processor-based and  into matlab. \textit{scripts} contains C-shell post-processing
272  tiled-based model output.  scripts for joining processor-based and tiled-based model output.
273    
274  \item \textit{verification}: this directory contains the model examples. See  \item \textit{verification}: this directory contains the model examples. See
275  below.  section \ref{sect:modelExamples}.
276  \end{itemize}  \end{itemize}
277    
278  \subsection{Model examples}  \section{Example experiments}
279    \label{sect:modelExamples}
280    
281  Now that you have successfully downloaded the model code we recommend that  %% a set of twenty-four pre-configured numerical experiments
 you first try to run the examples provided with the base version. You will  
 probably want to run the example that is the closest to the configuration  
 you will use eventually. The examples are located in subdirectories under  
 the directory \textit{verification} and are briefly described below (a full  
 description is given in section 2):  
282    
283  \subsubsection{List of model examples}  The MITgcm distribution comes with more than a dozen pre-configured
284    numerical experiments. Some of these example experiments are tests of
285    individual parts of the model code, but many are fully fledged
286    numerical simulations. A few of the examples are used for tutorial
287    documentation in sections \ref{sect:eg-baro} - \ref{sect:eg-global}.
288    The other examples follow the same general structure as the tutorial
289    examples. However, they only include brief instructions in a text file
290    called {\it README}.  The examples are located in subdirectories under
291    the directory \textit{verification}. Each example is briefly described
292    below.
293    
294  \begin{itemize}  \subsection{Full list of model examples}
 \item \textit{exp0} - single layer, ocean double gyre (barotropic with  
 free-surface).  
295    
296  \item \textit{exp1} - 4 layers, ocean double gyre.  \begin{enumerate}
297    \item \textit{exp0} - single layer, ocean double gyre (barotropic with
298      free-surface). This experiment is described in detail in section
299      \ref{sect:eg-baro}.
300    
301    \item \textit{exp1} - Four layer, ocean double gyre. This experiment
302      is described in detail in section \ref{sect:eg-baroc}.
303      
304  \item \textit{exp2} - 4x4 degree global ocean simulation with steady  \item \textit{exp2} - 4x4 degree global ocean simulation with steady
305  climatological forcing.    climatological forcing. This experiment is described in detail in
306      section \ref{sect:eg-global}.
307      
308    \item \textit{exp4} - Flow over a Gaussian bump in open-water or
309      channel with open boundaries.
310      
311    \item \textit{exp5} - Inhomogenously forced ocean convection in a
312      doubly periodic box.
313    
314  \item \textit{exp4} - flow over a Gaussian bump in open-water or channel  \item \textit{front\_relax} - Relaxation of an ocean thermal front (test for
 with open boundaries.  
   
 \item \textit{exp5} - inhomogenously forced ocean convection in a doubly  
 periodic box.  
   
 \item \textit{front\_relax} - relaxation of an ocean thermal front (test for  
315  Gent/McWilliams scheme). 2D (Y-Z).  Gent/McWilliams scheme). 2D (Y-Z).
316    
317  \item \textit{internal wave} - ocean internal wave forced by open boundary  \item \textit{internal wave} - Ocean internal wave forced by open
318  conditions.    boundary conditions.
319      
320  \item \textit{natl\_box} - eastern subtropical North Atlantic with KPP  \item \textit{natl\_box} - Eastern subtropical North Atlantic with KPP
321  scheme; 1 month integration    scheme; 1 month integration
322      
323  \item \textit{hs94.1x64x5} - zonal averaged atmosphere using Held and Suarez  \item \textit{hs94.1x64x5} - Zonal averaged atmosphere using Held and
324  '94 forcing.    Suarez '94 forcing.
325      
326  \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and Suarez  \item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and
327  '94 forcing.    Suarez '94 forcing.
328      
329  \item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and  \item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and
330  Suarez '94 forcing on the cubed sphere.    Suarez '94 forcing on the cubed sphere.
331      
332  \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics, 5 layers  \item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics.
333  Molteni physics package. Global Zonal Mean configuration, 1x64x5 resolution.    Global Zonal Mean configuration, 1x64x5 resolution.
334      
335  \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate Atmospheric  \item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate
336  physics, 5 layers Molteni physics package. Equatorial Slice configuration.    Atmospheric physics, equatorial Slice configuration.  2D (X-Z).
337  2D (X-Z).    
   
338  \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric  \item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric
339  physics, 5 layers Molteni physics package. 3D Equatorial Channel    physics. 3D Equatorial Channel configuration.
340  configuration (not completely tested).    
341    \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics.
342      Global configuration, on latitude longitude grid with 128x64x5 grid
343      points ($2.8^\circ{\rm degree}$ resolution).
344      
345    \item \textit{adjustment.128x64x1} Barotropic adjustment problem on
346      latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm
347        degree}$ resolution).
348      
349    \item \textit{adjustment.cs-32x32x1} Barotropic adjustment problem on
350      cube sphere grid with 32x32 points per face ( roughly $2.8^\circ{\rm
351        degree}$ resolution).
352      
353    \item \textit{advect\_cs} Two-dimensional passive advection test on
354      cube sphere grid.
355      
356    \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive
357      advection test on Cartesian grid.
358      
359    \item \textit{advect\_yz} Two-dimensional (vertical plane) passive
360      advection test on Cartesian grid.
361      
362    \item \textit{carbon} Simple passive tracer experiment. Includes
363      derivative calculation. Described in detail in section
364      \ref{sect:eg-carbon-ad}.
365    
366    \item \textit{flt\_example} Example of using float package.
367      
368    \item \textit{global\_ocean.90x40x15} Global circulation with GM, flux
369      boundary conditions and poles.
370    
371    \item \textit{global\_ocean\_pressure} Global circulation in pressure
372      coordinate (non-Boussinesq ocean model). Described in detail in
373      section \ref{sect:eg-globalpressure}.
374      
375    \item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube
376      sphere grid.
377    
378  \item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics, 5 layers  \end{enumerate}
 Molteni physics package. Global configuration, 128x64x5 resolution.  
379    
380  \item \textit{adjustment.128x64x1}  \subsection{Directory structure of model examples}
   
 \item \textit{adjustment.cs-32x32x1}  
 \end{itemize}  
   
 \subsubsection{Directory structure of model examples}  
381    
382  Each example directory has the following subdirectories:  Each example directory has the following subdirectories:
383    
# Line 207  Each example directory has the following Line 386  Each example directory has the following
386  minimum, this directory includes the following files:  minimum, this directory includes the following files:
387    
388  \begin{itemize}  \begin{itemize}
389  \item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to the  \item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to
390  ``execution environment'' part of the code. The default version is located    the ``execution environment'' part of the code. The default version
391  in \textit{eesupp/inc}.    is located in \textit{eesupp/inc}.
392      
393  \item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to the  \item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to the
394  ``numerical model'' part of the code. The default version is located in    ``numerical model'' part of the code. The default version is located
395  \textit{model/inc}.    in \textit{model/inc}.
396      
397  \item \textit{code/SIZE.h}: declares size of underlying computational grid.  \item \textit{code/SIZE.h}: declares size of underlying computational
398  The default version is located in \textit{model/inc}.    grid.  The default version is located in \textit{model/inc}.
399  \end{itemize}  \end{itemize}
400    
401  In addition, other include files and subroutines might be present in \textit{%  In addition, other include files and subroutines might be present in
402  code} depending on the particular experiment. See section 2 for more details.  \textit{code} depending on the particular experiment. See Section 2
403    for more details.
404  \item \textit{input}: contains the input data files required to run the  
405  example. At a mimimum, the \textit{input} directory contains the following  \item \textit{input}: contains the input data files required to run
406  files:    the example. At a minimum, the \textit{input} directory contains the
407      following files:
408  \begin{itemize}  
409  \item \textit{input/data}: this file, written as a namelist, specifies the  \begin{itemize}
410  main parameters for the experiment.  \item \textit{input/data}: this file, written as a namelist, specifies
411      the main parameters for the experiment.
412  \item \textit{input/data.pkg}: contains parameters relative to the packages    
413  used in the experiment.  \item \textit{input/data.pkg}: contains parameters relative to the
414      packages used in the experiment.
415  \item \textit{input/eedata}: this file contains ``execution environment''    
416  data. At present, this consists of a specification of the number of threads  \item \textit{input/eedata}: this file contains ``execution
417  to use in $X$ and $Y$ under multithreaded execution.    environment'' data. At present, this consists of a specification of
418      the number of threads to use in $X$ and $Y$ under multithreaded
419      execution.
420  \end{itemize}  \end{itemize}
421    
422  In addition, you will also find in this directory the forcing and topography  In addition, you will also find in this directory the forcing and topography
# Line 250  comparison with your own output when you Line 431  comparison with your own output when you
431  Once you have chosen the example you want to run, you are ready to compile  Once you have chosen the example you want to run, you are ready to compile
432  the code.  the code.
433    
434  \subsection{Compiling the code}  \section{Building the code}
435    \label{sect:buildingCode}
436    
437    To compile the code, we use the {\em make} program. This uses a file
438    ({\em Makefile}) that allows us to pre-process source files, specify
439    compiler and optimization options and also figures out any file
440    dependencies. We supply a script ({\em genmake}), described in section
441    \ref{sect:genmake}, that automatically creates the {\em Makefile} for
442    you. You then need to build the dependencies and compile the code.
443    
444    As an example, let's assume that you want to build and run experiment
445    \textit{verification/exp2}. The are multiple ways and places to actually
446    do this but here let's build the code in
447    \textit{verification/exp2/input}:
448    \begin{verbatim}
449    % cd verification/exp2/input
450    \end{verbatim}
451    First, build the {\em Makefile}:
452    \begin{verbatim}
453    % ../../../tools/genmake -mods=../code
454    \end{verbatim}
455    The command line option tells {\em genmake} to override model source
456    code with any files in the directory {\em ./code/}.
457    
458    If there is no \textit{.genmakerc} in the \textit{input} directory, you have
459    to use the following options when invoking \textit{genmake}:
460    \begin{verbatim}
461    % ../../../tools/genmake  -mods=../code
462    \end{verbatim}
463    
464    Next, create the dependencies:
465    \begin{verbatim}
466    % make depend
467    \end{verbatim}
468    This modifies {\em Makefile} by attaching a [long] list of files on
469    which other files depend. The purpose of this is to reduce
470    re-compilation if and when you start to modify the code. {\tt make
471    depend} also created links from the model source to this directory.
472    
473    Now compile the code:
474    \begin{verbatim}
475    % make
476    \end{verbatim}
477    The {\tt make} command creates an executable called \textit{mitgcmuv}.
478    
479    Now you are ready to run the model. General instructions for doing so are
480    given in section \ref{sect:runModel}. Here, we can run the model with:
481    \begin{verbatim}
482    ./mitgcmuv > output.txt
483    \end{verbatim}
484    where we are re-directing the stream of text output to the file {\em
485    output.txt}.
486    
487    
488    \subsection{Building/compiling the code elsewhere}
489    
490  \subsubsection{The script \textit{genmake}}  In the example above (section \ref{sect:buildingCode}) we built the
491    executable in the {\em input} directory of the experiment for
492    convenience. You can also configure and compile the code in other
493    locations, for example on a scratch disk with out having to copy the
494    entire source tree. The only requirement to do so is you have {\tt
495    genmake} in your path or you know the absolute path to {\tt genmake}.
496    
497    The following sections outline some possible methods of organizing you
498    source and data.
499    
500    \subsubsection{Building from the {\em ../code directory}}
501    
502    This is just as simple as building in the {\em input/} directory:
503    \begin{verbatim}
504    % cd verification/exp2/code
505    % ../../../tools/genmake
506    % make depend
507    % make
508    \end{verbatim}
509    However, to run the model the executable ({\em mitgcmuv}) and input
510    files must be in the same place. If you only have one calculation to make:
511    \begin{verbatim}
512    % cd ../input
513    % cp ../code/mitgcmuv ./
514    % ./mitgcmuv > output.txt
515    \end{verbatim}
516    or if you will be making multiple runs with the same executable:
517    \begin{verbatim}
518    % cd ../
519    % cp -r input run1
520    % cp code/mitgcmuv run1
521    % cd run1
522    % ./mitgcmuv > output.txt
523    \end{verbatim}
524    
525    \subsubsection{Building from a new directory}
526    
527    Since the {\em input} directory contains input files it is often more
528    useful to keep {\em input} pristine and build in a new directory
529    within {\em verification/exp2/}:
530    \begin{verbatim}
531    % cd verification/exp2
532    % mkdir build
533    % cd build
534    % ../../../tools/genmake -mods=../code
535    % make depend
536    % make
537    \end{verbatim}
538    This builds the code exactly as before but this time you need to copy
539    either the executable or the input files or both in order to run the
540    model. For example,
541    \begin{verbatim}
542    % cp ../input/* ./
543    % ./mitgcmuv > output.txt
544    \end{verbatim}
545    or if you tend to make multiple runs with the same executable then
546    running in a new directory each time might be more appropriate:
547    \begin{verbatim}
548    % cd ../
549    % mkdir run1
550    % cp build/mitgcmuv run1/
551    % cp input/* run1/
552    % cd run1
553    % ./mitgcmuv > output.txt
554    \end{verbatim}
555    
556    \subsubsection{Building from on a scratch disk}
557    
558    Model object files and output data can use up large amounts of disk
559    space so it is often the case that you will be operating on a large
560    scratch disk. Assuming the model source is in {\em ~/MITgcm} then the
561    following commands will build the model in {\em /scratch/exp2-run1}:
562    \begin{verbatim}
563    % cd /scratch/exp2-run1
564    % ~/MITgcm/tools/genmake -rootdir=~/MITgcm -mods=~/MITgcm/verification/exp2/code
565    % make depend
566    % make
567    \end{verbatim}
568    To run the model here, you'll need the input files:
569    \begin{verbatim}
570    % cp ~/MITgcm/verification/exp2/input/* ./
571    % ./mitgcmuv > output.txt
572    \end{verbatim}
573    
574    As before, you could build in one directory and make multiple runs of
575    the one experiment:
576    \begin{verbatim}
577    % cd /scratch/exp2
578    % mkdir build
579    % cd build
580    % ~/MITgcm/tools/genmake -rootdir=~/MITgcm -mods=~/MITgcm/verification/exp2/code
581    % make depend
582    % make
583    % cd ../
584    % cp -r ~/MITgcm/verification/exp2/input run2
585    % cd run2
586    % ./mitgcmuv > output.txt
587    \end{verbatim}
588    
589    
590    
591    \subsection{\textit{genmake}}
592    \label{sect:genmake}
593    
594  To compile the code, use the script \textit{genmake} located in the \textit{%  To compile the code, use the script \textit{genmake} located in the \textit{%
595  tools} directory. \textit{genmake} is a script that generates the makefile.  tools} directory. \textit{genmake} is a script that generates the makefile.
# Line 353  For some of the examples, there is a fil Line 690  For some of the examples, there is a fil
690  that particular example. In this way you don't need to type the options when  that particular example. In this way you don't need to type the options when
691  invoking \textit{genmake}.  invoking \textit{genmake}.
692    
 \subsubsection{Compiling}  
693    
694  Let's assume that you want to run, say, example \textit{exp2} in the \textit{%  \section{Running the model}
695  input} directory. To compile the code, type the following commands from the  \label{sect:runModel}
 model root tree:  
 \begin{verbatim}  
 % cd verification/exp2/input  
 % ../../../tools/genmake  
 % make depend  
 % make  
 \end{verbatim}  
696    
697  If there is no \textit{.genmakerc} in the \textit{input} directory, you have  If compilation finished succesfuully (section \ref{sect:buildModel})
698  to use the following options when invoking \textit{genmake}:  then an executable called {\em mitgcmuv} will now exist in the local
699  \begin{verbatim}  directory.
 % ../../../tools/genmake  -mods=../code  
 \end{verbatim}  
700    
701  In addition, you will probably want to disable some of the packages. Taking  To run the model as a single process (ie. not in parallel) simply
702  again the case of \textit{exp2}, the full \textit{genmake} command will  type:
 probably look like this:  
703  \begin{verbatim}  \begin{verbatim}
704  % ../../../tools/genmake  -mods=../code  -disable=kpp,gmredi,aim,...  % ./mitgcmuv
705  \end{verbatim}  \end{verbatim}
706    The ``./'' is a safe-guard to make sure you use the local executable
707  The make command creates an executable called \textit{mitgcmuv}.  in case you have others that exist in your path (surely odd if you
708    do!). The above command will spew out many lines of text output to
709  Note that you can compile and run the code in another directory than \textit{%  your screen.  This output contains details such as parameter values as
710  input}. You just need to make sure that you copy the input data files into  well as diagnostics such as mean Kinetic energy, largest CFL number,
711  the directory where you want to run the model. For example to compile from  etc. It is worth keeping this text output with the binary output so we
712  \textit{code}:  normally re-direct the {\em stdout} stream as follows:
713  \begin{verbatim}  \begin{verbatim}
714  % cd verification/exp2/code  % ./mitgcmuv > output.txt
 % ../../../tools/genmake  
 % make depend  
 % make  
715  \end{verbatim}  \end{verbatim}
716    
717  \subsection{Running the model}  For the example experiments in {\em vericication}, an example of the
718    output is kept in {\em results/output.txt} for comparison. You can compare
719    your {\em output.txt} with this one to check that the set-up works.
720    
721    
 The first thing to do is to run the code by typing \textit{mitgcmuv} and see  
 what happens. You can compare what you get with what is in the \textit{%  
 results} directory. Unless noted otherwise, most examples are set up to run  
 for a few time steps only so that you can quickly figure out whether the  
 model is working or not.  
722    
723  \subsubsection{Output files}  \subsection{Output files}
724    
725  The model produces various output files. At a minimum, the instantaneous  The model produces various output files. At a minimum, the instantaneous
726  ``state'' of the model is written out, which is made of the following files:  ``state'' of the model is written out, which is made of the following files:
# Line 450  as the pickup files but are named differ Line 771  as the pickup files but are named differ
771  used to restart the model but are overwritten every other time they are  used to restart the model but are overwritten every other time they are
772  output to save disk space during long integrations.  output to save disk space during long integrations.
773    
774  \subsubsection{Looking at the output}  \subsection{Looking at the output}
775    
776  All the model data are written according to a ``meta/data'' file format.  All the model data are written according to a ``meta/data'' file format.
777  Each variable is associated with two files with suffix names \textit{.data}  Each variable is associated with two files with suffix names \textit{.data}
# Line 464  written in this format. The matlab scrip Line 785  written in this format. The matlab scrip
785  \textit{utils/matlab} under the root tree. The script \textit{rdmds.m} reads  \textit{utils/matlab} under the root tree. The script \textit{rdmds.m} reads
786  the data. Look at the comments inside the script to see how to use it.  the data. Look at the comments inside the script to see how to use it.
787    
788  \section{Code structure}  Some examples of reading and visualizing some output in {\em Matlab}:
789    \begin{verbatim}
790    % matlab
791    >> H=rdmds('Depth');
792    >> contourf(H');colorbar;
793    >> title('Depth of fluid as used by model');
794    
795    >> eta=rdmds('Eta',10);
796    >> imagesc(eta');axis ij;colorbar;
797    >> title('Surface height at iter=10');
798    
799  \section{Doing it yourself: customizing the code}  >> eta=rdmds('Eta',[0:10:100]);
800    >> for n=1:11; imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
801    \end{verbatim}
802    
803  \subsection{\protect\bigskip Configuration and setup}  \section{Doing it yourself: customizing the code}
804    
805  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
806  easiest thing is to use and adapt the setup of the case studies experiment  easiest thing is to use and adapt the setup of the case studies experiment
# Line 478  relative to the ''numerical model'' part Line 810  relative to the ''numerical model'' part
810  the ''execution environment'' part is covered in the parallel implementation  the ''execution environment'' part is covered in the parallel implementation
811  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.
812    
813    \subsection{Configuration and setup}
814    
815  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
816  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{%
817  model/inc }or in one of the \textit{code }directories of the case study  model/inc }or in one of the \textit{code }directories of the case study
# Line 494  In what follows the parameters are group Line 828  In what follows the parameters are group
828  computational domain, the equations solved in the model, and the simulation  computational domain, the equations solved in the model, and the simulation
829  controls.  controls.
830    
831  \subsubsection{Computational domain, geometry and time-discretization}  \subsection{Computational domain, geometry and time-discretization}
832    
833  \begin{itemize}  \begin{itemize}
834  \item dimensions  \item dimensions
# Line 577  here I think. To come soon...) Line 911  here I think. To come soon...)
911  \item time-discretization  \item time-discretization
912  \end{itemize}  \end{itemize}
913    
914  The time steps are set through the real variables \textbf{deltaTMom }and  The time steps are set through the real variables \textbf{deltaTMom}
915  \textbf{deltaTtracer }(in s) which represent the time step for the momentum  and \textbf{deltaTtracer} (in s) which represent the time step for the
916  and tracer equations, respectively. For synchronous integrations, simply set  momentum and tracer equations, respectively. For synchronous
917  the two variables to the same value (or you can prescribe one time step only  integrations, simply set the two variables to the same value (or you
918  through the variable \textbf{deltaT}). The Adams-Bashforth stabilizing  can prescribe one time step only through the variable
919  parameter is set through the variable \textbf{abEps }(dimensionless). The  \textbf{deltaT}). The Adams-Bashforth stabilizing parameter is set
920  stagger baroclinic time stepping can be activated by setting the logical  through the variable \textbf{abEps} (dimensionless). The stagger
921  variable \textbf{staggerTimeStep }to '.\texttt{TRUE}.'.  baroclinic time stepping can be activated by setting the logical
922    variable \textbf{staggerTimeStep} to '.\texttt{TRUE}.'.
923  \subsubsection{Equation of state}  
924    \subsection{Equation of state}
925  First, because the model equations are written in terms of perturbations, a  
926  reference thermodynamic state needs to be specified. This is done through  First, because the model equations are written in terms of
927  the 1D arrays \textbf{tRef}\textit{\ }and \textbf{sRef}. \textbf{tRef }%  perturbations, a reference thermodynamic state needs to be specified.
928  specifies the reference potential temperature profile (in $^{o}$C for  This is done through the 1D arrays \textbf{tRef} and \textbf{sRef}.
929  the ocean and $^{o}$K for the atmosphere) starting from the level  \textbf{tRef} specifies the reference potential temperature profile
930  k=1. Similarly, \textbf{sRef}\textit{\ }specifies the reference salinity  (in $^{o}$C for the ocean and $^{o}$K for the atmosphere) starting
931  profile (in ppt) for the ocean or the reference specific humidity profile  from the level k=1. Similarly, \textbf{sRef} specifies the reference
932  (in g/kg) for the atmosphere.  salinity profile (in ppt) for the ocean or the reference specific
933    humidity profile (in g/kg) for the atmosphere.
934  The form of the equation of state is controlled by the character variables  
935  \textbf{buoyancyRelation}\textit{\ }and \textbf{eosType}\textit{. }\textbf{%  The form of the equation of state is controlled by the character
936  buoyancyRelation}\textit{\ }is set to '\texttt{OCEANIC}' by default and  variables \textbf{buoyancyRelation} and \textbf{eosType}.
937  needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations. In  \textbf{buoyancyRelation} is set to '\texttt{OCEANIC}' by default and
938  this case, \textbf{eosType}\textit{\ }must be set to '\texttt{IDEALGAS}'.  needs to be set to '\texttt{ATMOSPHERIC}' for atmosphere simulations.
939  For the ocean, two forms of the equation of state are available: linear (set  In this case, \textbf{eosType} must be set to '\texttt{IDEALGAS}'.
940  \textbf{eosType}\textit{\ }to '\texttt{LINEAR}') and a polynomial  For the ocean, two forms of the equation of state are available:
941  approximation to the full nonlinear equation ( set \textbf{eosType}\textit{\  linear (set \textbf{eosType} to '\texttt{LINEAR}') and a polynomial
942  }to '\texttt{POLYNOMIAL}'). In the linear case, you need to specify the  approximation to the full nonlinear equation ( set
943  thermal and haline expansion coefficients represented by the variables  \textbf{eosType}\textit{\ }to '\texttt{POLYNOMIAL}'). In the linear
944  \textbf{tAlpha}\textit{\ }(in K$^{-1}$) and \textbf{sBeta}\textit{\ }(in ppt$%  case, you need to specify the thermal and haline expansion
945  ^{-1}$). For the nonlinear case, you need to generate a file of polynomial  coefficients represented by the variables \textbf{tAlpha}\textit{\
946  coefficients called \textit{POLY3.COEFFS. }To do this, use the program    }(in K$^{-1}$) and \textbf{sBeta} (in ppt$^{-1}$). For the nonlinear
947  \textit{utils/knudsen2/knudsen2.f }under the model tree (a Makefile is  case, you need to generate a file of polynomial coefficients called
948  available in the same directory and you will need to edit the number and the  \textit{POLY3.COEFFS}. To do this, use the program
949  values of the vertical levels in \textit{knudsen2.f }so that they match  \textit{utils/knudsen2/knudsen2.f} under the model tree (a Makefile is
950  those of your configuration). \textit{\ }  available in the same directory and you will need to edit the number
951    and the values of the vertical levels in \textit{knudsen2.f} so that
952    they match those of your configuration).
953    
954    There there are also higher polynomials for the equation of state:
955    \begin{description}
956    \item['\texttt{UNESCO}':] The UNESCO equation of state formula of
957      Fofonoff and Millard \cite{fofonoff83}. This equation of state
958      assumes in-situ temperature, which is not a model variable; \emph{its use
959      is therefore discouraged, and it is only listed for completeness}.
960    \item['\texttt{JMD95Z}':] A modified UNESCO formula by Jackett and
961      McDougall \cite{jackett95}, which uses the model variable potential
962      temperature as input. The '\texttt{Z}' indicates that this equation
963      of state uses a horizontally and temporally constant pressure
964      $p_{0}=-g\rho_{0}z$.
965    \item['\texttt{JMD95P}':] A modified UNESCO formula by Jackett and
966      McDougall \cite{jackett95}, which uses the model variable potential
967      temperature as input. The '\texttt{P}' indicates that this equation
968      of state uses the actual hydrostatic pressure of the last time
969      step. Lagging the pressure in this way requires an additional pickup
970      file for restarts.
971    \item['\texttt{MDJWF}':] The new, more accurate and less expensive
972      equation of state by McDougall et~al. \cite{mcdougall03}. It also
973      requires lagging the pressure and therefore an additional pickup
974      file for restarts.
975    \end{description}
976    For none of these options an reference profile of temperature or
977    salinity is required.
978    
979  \subsubsection{Momentum equations}  \subsection{Momentum equations}
980    
981  In this section, we only focus for now on the parameters that you are likely  In this section, we only focus for now on the parameters that you are likely
982  to change, i.e. the ones relative to forcing and dissipation for example.  to change, i.e. the ones relative to forcing and dissipation for example.
# Line 719  geopotential (for the atmosphere) you ne Line 1080  geopotential (for the atmosphere) you ne
1080  \texttt{TRUE}.' and the other to '.\texttt{FALSE}.' depending on how you  \texttt{TRUE}.' and the other to '.\texttt{FALSE}.' depending on how you
1081  want to deal with the ocean upper or atmosphere lower boundary).  want to deal with the ocean upper or atmosphere lower boundary).
1082    
1083  \subsubsection{Tracer equations}  \subsection{Tracer equations}
1084    
1085  This section covers the tracer equations i.e. the potential temperature  This section covers the tracer equations i.e. the potential temperature
1086  equation and the salinity (for the ocean) or specific humidity (for the  equation and the salinity (for the ocean) or specific humidity (for the
# Line 810  wish the tracer vertical diffusivities t Line 1171  wish the tracer vertical diffusivities t
1171  vertically due to static instabilities. Note that \textbf{cadjFreq }and  vertically due to static instabilities. Note that \textbf{cadjFreq }and
1172  \textbf{ivdc\_kappa }can not both have non-zero value.  \textbf{ivdc\_kappa }can not both have non-zero value.
1173    
1174  \subsubsection{Simulation controls}  \subsection{Simulation controls}
1175    
1176  The model ''clock'' is defined by the variable \textbf{deltaTClock }(in s)  The model ''clock'' is defined by the variable \textbf{deltaTClock }(in s)
1177  which determines the IO frequencies and is used in tagging output.  which determines the IO frequencies and is used in tagging output.
# Line 846  fields can be written out by setting the Line 1207  fields can be written out by setting the
1207  The precision with which to write the binary data is controlled by the  The precision with which to write the binary data is controlled by the
1208  integer variable w\textbf{riteBinaryPrec }(set it to \texttt{32} or \texttt{%  integer variable w\textbf{riteBinaryPrec }(set it to \texttt{32} or \texttt{%
1209  64}).  64}).
1210    
1211    %%% Local Variables:
1212    %%% mode: latex
1213    %%% TeX-master: t
1214    %%% End:
Legend:
Removed from v.1.1.1.1  
changed lines
  Added in v.1.15
  ViewVC Help
Powered by ViewVC 1.1.22