/[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.8 by cnh, Mon Oct 22 11:55:47 2001 UTC revision 1.12 by adcroft, Wed Dec 5 15:49:39 2001 UTC
# Line 48  to enable us to keep track of who's usin Line 48  to enable us to keep track of who's usin
48  You can download the model two ways:  You can download the model two ways:
49    
50  \begin{enumerate}  \begin{enumerate}
51  \item Using CVS software. CVS is a freely available source code managment  \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  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  come with CVS pre-installed, otherwise good places to look for
54  the software for a particular platform are  the software for a particular platform are
# Line 86  You only need to do ``cvs login'' once. Line 86  You only need to do ``cvs login'' once.
86    
87  To obtain the sources for release1 type:  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}
# Line 116  The tar file still contains CVS informat Line 116  The tar file still contains CVS informat
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.
118    
119    \paragraph*{Upgrading from an earlier version}
120    
121    If you already have an earlier version of the code you can ``upgrade''
122    your copy instead of downloading the entire repository again. First,
123    ``cd'' (change directory) to the top of your working copy:
124    \begin{verbatim}
125    % cd MITgcm
126    \end{verbatim}
127    and then issue the cvs update command:
128    \begin{verbatim}
129    % cvs -q update -r release1_beta1 -d -P
130    \end{verbatim}
131    This will update the ``tag'' to ``release1\_beta1'', add any new
132    directories (-d) and remove any empty directories (-P). The -q option
133    means be quiet which will reduce the number of messages you'll see in
134    the terminal. If you have modified the code prior to upgrading, CVS
135    will try to merge your changes with the upgrades. If there is a
136    conflict between your modifications and the upgrade, it will report
137    that file with a ``C'' in front, e.g.:
138    \begin{verbatim}
139    C model/src/ini_parms.F
140    \end{verbatim}
141    If the list of conflicts scrolled off the screen, you can re-issue the
142    cvs update command and it will report the conflicts. Conflicts are
143    indicated in the code by the delimites ``<<<<<<<'', ``======='' and
144    ``>>>>>>>''. For example,
145    \begin{verbatim}
146    <<<<<<< ini_parms.F
147         & bottomDragLinear,myOwnBottomDragCoefficient,
148    =======
149         & bottomDragLinear,bottomDragQuadratic,
150    >>>>>>> 1.18
151    \end{verbatim}
152    means that you added ``myOwnBottomDragCoefficient'' to a namelist at
153    the same time and place that we added ``bottomDragQuadratic''. You
154    need to resolve this conflict and in this case the line should be
155    changed to:
156    \begin{verbatim}
157         & bottomDragLinear,bottomDragQuadratic,myOwnBottomDragCoefficient,
158    \end{verbatim}
159    and the lines with the delimiters (<<<<<<,======,>>>>>>) be deleted.
160    Unless you are making modifications which exactly parallel
161    developments we make, these types of conflicts should be rare.
162    
163    \paragraph*{Upgrading to the current pre-release version}
164    
165    We don't make a ``release'' for every little patch and bug fix in
166    order to keep the frequency of upgrades to a minimum. However, if you
167    have run into a problem for which ``we have already fixed in the
168    latest code'' and we haven't made a ``tag'' or ``release'' since that
169    patch then you'll need to get the latest code:
170    \begin{verbatim}
171    % cvs -q update -A -d -P
172    \end{verbatim}
173    Unlike, the ``check-out'' and ``update'' procedures above, there is no
174    ``tag'' or release name. The -A tells CVS to upgrade to the
175    very latest version. As a rule, we don't recommend this since you
176    might upgrade while we are in the processes of checking in the code so
177    that you may only have part of a patch. Using this method of updating
178    also means we can't tell what version of the code you are working
179    with. So please be sure you understand what you're doing.
180    
181  \section{Model and directory structure}  \section{Model and directory structure}
182    
183  The ``numerical'' model is contained within a execution environment support  The ``numerical'' model is contained within a execution environment
184  wrapper. This wrapper is designed to provide a general framework for  support wrapper. This wrapper is designed to provide a general
185  grid-point models. MITgcmUV is a specific numerical model that uses the  framework for grid-point models. MITgcmUV is a specific numerical
186  framework. Under this structure the model is split into execution  model that uses the framework. Under this structure the model is split
187  environment support code and conventional numerical model code. The  into execution environment support code and conventional numerical
188  execution environment support code is held under the \textit{eesupp}  model code. The execution environment support code is held under the
189  directory. The grid point model code is held under the \textit{model}  \textit{eesupp} directory. The grid point model code is held under the
190  directory. Code execution actually starts in the \textit{eesupp} routines  \textit{model} directory. Code execution actually starts in the
191  and not in the \textit{model} routines. For this reason the top-level  \textit{eesupp} routines and not in the \textit{model} routines. For
192    this reason the top-level
193  \textit{MAIN.F} is in the \textit{eesupp/src} directory. In general,  \textit{MAIN.F} is in the \textit{eesupp/src} directory. In general,
194  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
195  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 139  directory in which to compile the code. Line 202  directory in which to compile the code.
202    
203  \item \textit{diags}: contains the code relative to time-averaged  \item \textit{diags}: contains the code relative to time-averaged
204  diagnostics. It is subdivided into two subdirectories \textit{inc} and  diagnostics. It is subdivided into two subdirectories \textit{inc} and
205  \textit{src} that contain include files (*.\textit{h} files) and fortran  \textit{src} that contain include files (*.\textit{h} files) and Fortran
206  subroutines (*.\textit{F} files), respectively.  subroutines (*.\textit{F} files), respectively.
207    
208  \item \textit{doc}: contains brief documentation notes.  \item \textit{doc}: contains brief documentation notes.
# Line 184  The MITgcm distribution comes with a set Line 247  The MITgcm distribution comes with a set
247  numerical experiments. Some of these examples experiments are tests of  numerical experiments. Some of these examples experiments are tests of
248  individual parts of the model code, but many are fully fledged numerical  individual parts of the model code, but many are fully fledged numerical
249  simulations. A few of the examples are used for tutorial documentation  simulations. A few of the examples are used for tutorial documentation
250  in sections \ref{sec:eg-baro} - \ref{sec:eg-global}. The other examples  in sections \ref{sect:eg-baro} - \ref{sect:eg-global}. The other examples
251  follow the same general structure as the tutorial examples. However,  follow the same general structure as the tutorial examples. However,
252  they only include brief instructions in a text file called {\it README}.  they only include brief instructions in a text file called {\it README}.
253  The examples are located in subdirectories under  The examples are located in subdirectories under
# Line 196  example is briefly described below. Line 259  example is briefly described below.
259  \begin{enumerate}  \begin{enumerate}
260  \item \textit{exp0} - single layer, ocean double gyre (barotropic with  \item \textit{exp0} - single layer, ocean double gyre (barotropic with
261  free-surface). This experiment is described in detail in section  free-surface). This experiment is described in detail in section
262  \ref{sec:eg-baro}.  \ref{sect:eg-baro}.
263    
264  \item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section  \item \textit{exp1} - Four layer, ocean double gyre. This experiment is described in detail in section
265  \ref{sec:eg-baroc}.  \ref{sect:eg-baroc}.
266    
267  \item \textit{exp2} - 4x4 degree global ocean simulation with steady  \item \textit{exp2} - 4x4 degree global ocean simulation with steady
268  climatological forcing. This experiment is described in detail in section  climatological forcing. This experiment is described in detail in section
269  \ref{sec:eg-global}.  \ref{sect:eg-global}.
270    
271  \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
272  with open boundaries.  with open boundaries.
# Line 255  $2.8^\circ{\rm degree}$ resolution). Line 318  $2.8^\circ{\rm degree}$ resolution).
318  cube sphere grid.  cube sphere grid.
319    
320  \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection  \item \textit{advect\_xy} Two-dimensional (horizontal plane) passive advection
321  test on cartesian grid.  test on Cartesian grid.
322    
323  \item \textit{advect\_yz} Two-dimensional (vertical plane) passive advection test on cartesian grid.  \item \textit{advect\_yz} Two-dimensional (vertical plane) passive advection test on Cartesian grid.
324    
325  \item \textit{carbon} Simple passive tracer experiment. Includes derivative  \item \textit{carbon} Simple passive tracer experiment. Includes derivative
326  calculation. Described in detail in section \ref{sec:eg-carbon-ad}.  calculation. Described in detail in section \ref{sect:eg-carbon-ad}.
327    
328  \item \textit{flt\_example} Example of using float package.  \item \textit{flt\_example} Example of using float package.
329    
# Line 297  In addition, other include files and sub Line 360  In addition, other include files and sub
360  code} depending on the particular experiment. See section 2 for more details.  code} depending on the particular experiment. See section 2 for more details.
361    
362  \item \textit{input}: contains the input data files required to run the  \item \textit{input}: contains the input data files required to run the
363  example. At a mimimum, the \textit{input} directory contains the following  example. At a minimum, the \textit{input} directory contains the following
364  files:  files:
365    
366  \begin{itemize}  \begin{itemize}
# Line 330  the code. Line 393  the code.
393  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
394  ({\em Makefile}) that allows us to pre-process source files, specify  ({\em Makefile}) that allows us to pre-process source files, specify
395  compiler and optimization options and also figures out any file  compiler and optimization options and also figures out any file
396  dependancies. We supply a script ({\em genmake}), described in section  dependencies. We supply a script ({\em genmake}), described in section
397  \ref{sect:genmake}, that automatically creates the {\em Makefile} for  \ref{sect:genmake}, that automatically creates the {\em Makefile} for
398  you. You then need to build the dependancies and compile the code.  you. You then need to build the dependencies and compile the code.
399    
400  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
401  \textit{verification/exp2}. The are multiple ways and places to actually  \textit{verification/exp2}. The are multiple ways and places to actually
# Line 354  to use the following options when invoki Line 417  to use the following options when invoki
417  % ../../../tools/genmake  -mods=../code  % ../../../tools/genmake  -mods=../code
418  \end{verbatim}  \end{verbatim}
419    
420  Next, create the dependancies:  Next, create the dependencies:
421  \begin{verbatim}  \begin{verbatim}
422  % make depend  % make depend
423  \end{verbatim}  \end{verbatim}
# Line 406  files must be in the same place. If you Line 469  files must be in the same place. If you
469  % cp ../code/mitgcmuv ./  % cp ../code/mitgcmuv ./
470  % ./mitgcmuv > output.txt  % ./mitgcmuv > output.txt
471  \end{verbatim}  \end{verbatim}
472  or if you will be making muliple runs with the same executable:  or if you will be making multiple runs with the same executable:
473  \begin{verbatim}  \begin{verbatim}
474  % cd ../  % cd ../
475  % cp -r input run1  % cp -r input run1
# Line 418  or if you will be making muliple runs wi Line 481  or if you will be making muliple runs wi
481  \subsubsection{Building from a new directory}  \subsubsection{Building from a new directory}
482    
483  Since the {\em input} directory contains input files it is often more  Since the {\em input} directory contains input files it is often more
484  useful to keep {\em input} prestine and build in a new directory  useful to keep {\em input} pristine and build in a new directory
485  within {\em verification/exp2/}:  within {\em verification/exp2/}:
486  \begin{verbatim}  \begin{verbatim}
487  % cd verification/exp2  % cd verification/exp2
Legend:
Removed from v.1.8  
changed lines
  Added in v.1.12
  ViewVC Help
Powered by ViewVC 1.1.22