99 |
\begin{verbatim} |
\begin{verbatim} |
100 |
% setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/gcmpack |
% setenv CVSROOT :pserver:cvsanon@mitgcm.org:/u/gcmpack |
101 |
\end{verbatim} |
\end{verbatim} |
102 |
in your .cshrc or .tcshrc file. For bash or sh shells, put: |
in your \texttt{.cshrc} or \texttt{.tcshrc} file. For bash or sh |
103 |
|
shells, put: |
104 |
\begin{verbatim} |
\begin{verbatim} |
105 |
% export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack' |
% export CVSROOT=':pserver:cvsanon@mitgcm.org:/u/gcmpack' |
106 |
\end{verbatim} |
\end{verbatim} |
155 |
\label{tab:cvsModules} |
\label{tab:cvsModules} |
156 |
\end{table} |
\end{table} |
157 |
|
|
158 |
The checkout process creates a directory called \textit{MITgcm}. If |
The checkout process creates a directory called \texttt{MITgcm}. If |
159 |
the directory \textit{MITgcm} exists this command updates your code |
the directory \texttt{MITgcm} exists this command updates your code |
160 |
based on the repository. Each directory in the source tree contains a |
based on the repository. Each directory in the source tree contains a |
161 |
directory \textit{CVS}. This information is required by CVS to keep |
directory \texttt{CVS}. This information is required by CVS to keep |
162 |
track of your file versions with respect to the repository. Don't edit |
track of your file versions with respect to the repository. Don't edit |
163 |
the files in \textit{CVS}! You can also use CVS to download code |
the files in \texttt{CVS}! You can also use CVS to download code |
164 |
updates. More extensive information on using CVS for maintaining |
updates. More extensive information on using CVS for maintaining |
165 |
MITgcm code can be found |
MITgcm code can be found |
166 |
\begin{rawhtml} <A href=''http://mitgcm.org/usingcvstoget.html'' target="idontexist"> \end{rawhtml} |
\begin{rawhtml} <A href=''http://mitgcm.org/usingcvstoget.html'' target="idontexist"> \end{rawhtml} |
274 |
model that uses the framework. Under this structure the model is split |
model that uses the framework. Under this structure the model is split |
275 |
into execution environment support code and conventional numerical |
into execution environment support code and conventional numerical |
276 |
model code. The execution environment support code is held under the |
model code. The execution environment support code is held under the |
277 |
\textit{eesupp} directory. The grid point model code is held under the |
\texttt{eesupp} directory. The grid point model code is held under the |
278 |
\textit{model} directory. Code execution actually starts in the |
\texttt{model} directory. Code execution actually starts in the |
279 |
\textit{eesupp} routines and not in the \textit{model} routines. For |
\texttt{eesupp} routines and not in the \texttt{model} routines. For |
280 |
this reason the top-level \textit{MAIN.F} is in the |
this reason the top-level \texttt{MAIN.F} is in the |
281 |
\textit{eesupp/src} directory. In general, end-users should not need |
\texttt{eesupp/src} directory. In general, end-users should not need |
282 |
to worry about this level. The top-level routine for the numerical |
to worry about this level. The top-level routine for the numerical |
283 |
part of the code is in \textit{model/src/THE\_MODEL\_MAIN.F}. Here is |
part of the code is in \texttt{model/src/THE\_MODEL\_MAIN.F}. Here is |
284 |
a brief description of the directory structure of the model under the |
a brief description of the directory structure of the model under the |
285 |
root tree (a detailed description is given in section 3: Code |
root tree (a detailed description is given in section 3: Code |
286 |
structure). |
structure). |
287 |
|
|
288 |
\begin{itemize} |
\begin{itemize} |
289 |
|
|
290 |
\item \textit{bin}: this directory is initially empty. It is the |
\item \texttt{bin}: this directory is initially empty. It is the |
291 |
default directory in which to compile the code. |
default directory in which to compile the code. |
292 |
|
|
293 |
\item \textit{diags}: contains the code relative to time-averaged |
\item \texttt{diags}: contains the code relative to time-averaged |
294 |
diagnostics. It is subdivided into two subdirectories \textit{inc} |
diagnostics. It is subdivided into two subdirectories \texttt{inc} |
295 |
and \textit{src} that contain include files (*.\textit{h} files) and |
and \texttt{src} that contain include files (\texttt{*.h} files) and |
296 |
Fortran subroutines (*.\textit{F} files), respectively. |
Fortran subroutines (\texttt{*.F} files), respectively. |
297 |
|
|
298 |
\item \textit{doc}: contains brief documentation notes. |
\item \texttt{doc}: contains brief documentation notes. |
299 |
|
|
300 |
\item \textit{eesupp}: contains the execution environment source code. |
\item \texttt{eesupp}: contains the execution environment source code. |
301 |
Also subdivided into two subdirectories \textit{inc} and |
Also subdivided into two subdirectories \texttt{inc} and |
302 |
\textit{src}. |
\texttt{src}. |
303 |
|
|
304 |
\item \textit{exe}: this directory is initially empty. It is the |
\item \texttt{exe}: this directory is initially empty. It is the |
305 |
default directory in which to execute the code. |
default directory in which to execute the code. |
306 |
|
|
307 |
\item \textit{model}: this directory contains the main source code. |
\item \texttt{model}: this directory contains the main source code. |
308 |
Also subdivided into two subdirectories \textit{inc} and |
Also subdivided into two subdirectories \texttt{inc} and |
309 |
\textit{src}. |
\texttt{src}. |
310 |
|
|
311 |
\item \textit{pkg}: contains the source code for the packages. Each |
\item \texttt{pkg}: contains the source code for the packages. Each |
312 |
package corresponds to a subdirectory. For example, \textit{gmredi} |
package corresponds to a subdirectory. For example, \texttt{gmredi} |
313 |
contains the code related to the Gent-McWilliams/Redi scheme, |
contains the code related to the Gent-McWilliams/Redi scheme, |
314 |
\textit{aim} the code relative to the atmospheric intermediate |
\texttt{aim} the code relative to the atmospheric intermediate |
315 |
physics. The packages are described in detail in section 3. |
physics. The packages are described in detail in section 3. |
316 |
|
|
317 |
\item \textit{tools}: this directory contains various useful tools. |
\item \texttt{tools}: this directory contains various useful tools. |
318 |
For example, \textit{genmake2} is a script written in csh (C-shell) |
For example, \texttt{genmake2} is a script written in csh (C-shell) |
319 |
that should be used to generate your makefile. The directory |
that should be used to generate your makefile. The directory |
320 |
\textit{adjoint} contains the makefile specific to the Tangent |
\texttt{adjoint} contains the makefile specific to the Tangent |
321 |
linear and Adjoint Compiler (TAMC) that generates the adjoint code. |
linear and Adjoint Compiler (TAMC) that generates the adjoint code. |
322 |
The latter is described in details in part V. |
The latter is described in details in part V. |
323 |
|
|
324 |
\item \textit{utils}: this directory contains various utilities. The |
\item \texttt{utils}: this directory contains various utilities. The |
325 |
subdirectory \textit{knudsen2} contains code and a makefile that |
subdirectory \texttt{knudsen2} contains code and a makefile that |
326 |
compute coefficients of the polynomial approximation to the knudsen |
compute coefficients of the polynomial approximation to the knudsen |
327 |
formula for an ocean nonlinear equation of state. The |
formula for an ocean nonlinear equation of state. The |
328 |
\textit{matlab} subdirectory contains matlab scripts for reading |
\texttt{matlab} subdirectory contains matlab scripts for reading |
329 |
model output directly into matlab. \textit{scripts} contains C-shell |
model output directly into matlab. \texttt{scripts} contains C-shell |
330 |
post-processing scripts for joining processor-based and tiled-based |
post-processing scripts for joining processor-based and tiled-based |
331 |
model output. |
model output. |
332 |
|
|
333 |
\item \textit{verification}: this directory contains the model |
\item \texttt{verification}: this directory contains the model |
334 |
examples. See section \ref{sect:modelExamples}. |
examples. See section \ref{sect:modelExamples}. |
335 |
|
|
336 |
\end{itemize} |
\end{itemize} |
351 |
The other examples follow the same general structure as the tutorial |
The other examples follow the same general structure as the tutorial |
352 |
examples. However, they only include brief instructions in a text file |
examples. However, they only include brief instructions in a text file |
353 |
called {\it README}. The examples are located in subdirectories under |
called {\it README}. The examples are located in subdirectories under |
354 |
the directory \textit{verification}. Each example is briefly described |
the directory \texttt{verification}. Each example is briefly described |
355 |
below. |
below. |
356 |
|
|
357 |
\subsection{Full list of model examples} |
\subsection{Full list of model examples} |
358 |
|
|
359 |
\begin{enumerate} |
\begin{enumerate} |
360 |
|
|
361 |
\item \textit{exp0} - single layer, ocean double gyre (barotropic with |
\item \texttt{exp0} - single layer, ocean double gyre (barotropic with |
362 |
free-surface). This experiment is described in detail in section |
free-surface). This experiment is described in detail in section |
363 |
\ref{sect:eg-baro}. |
\ref{sect:eg-baro}. |
364 |
|
|
365 |
\item \textit{exp1} - Four layer, ocean double gyre. This experiment |
\item \texttt{exp1} - Four layer, ocean double gyre. This experiment |
366 |
is described in detail in section \ref{sect:eg-baroc}. |
is described in detail in section \ref{sect:eg-baroc}. |
367 |
|
|
368 |
\item \textit{exp2} - 4x4 degree global ocean simulation with steady |
\item \texttt{exp2} - 4x4 degree global ocean simulation with steady |
369 |
climatological forcing. This experiment is described in detail in |
climatological forcing. This experiment is described in detail in |
370 |
section \ref{sect:eg-global}. |
section \ref{sect:eg-global}. |
371 |
|
|
372 |
\item \textit{exp4} - Flow over a Gaussian bump in open-water or |
\item \texttt{exp4} - Flow over a Gaussian bump in open-water or |
373 |
channel with open boundaries. |
channel with open boundaries. |
374 |
|
|
375 |
\item \textit{exp5} - Inhomogenously forced ocean convection in a |
\item \texttt{exp5} - Inhomogenously forced ocean convection in a |
376 |
doubly periodic box. |
doubly periodic box. |
377 |
|
|
378 |
\item \textit{front\_relax} - Relaxation of an ocean thermal front (test for |
\item \texttt{front\_relax} - Relaxation of an ocean thermal front (test for |
379 |
Gent/McWilliams scheme). 2D (Y-Z). |
Gent/McWilliams scheme). 2D (Y-Z). |
380 |
|
|
381 |
\item \textit{internal wave} - Ocean internal wave forced by open |
\item \texttt{internal wave} - Ocean internal wave forced by open |
382 |
boundary conditions. |
boundary conditions. |
383 |
|
|
384 |
\item \textit{natl\_box} - Eastern subtropical North Atlantic with KPP |
\item \texttt{natl\_box} - Eastern subtropical North Atlantic with KPP |
385 |
scheme; 1 month integration |
scheme; 1 month integration |
386 |
|
|
387 |
\item \textit{hs94.1x64x5} - Zonal averaged atmosphere using Held and |
\item \texttt{hs94.1x64x5} - Zonal averaged atmosphere using Held and |
388 |
Suarez '94 forcing. |
Suarez '94 forcing. |
389 |
|
|
390 |
\item \textit{hs94.128x64x5} - 3D atmosphere dynamics using Held and |
\item \texttt{hs94.128x64x5} - 3D atmosphere dynamics using Held and |
391 |
Suarez '94 forcing. |
Suarez '94 forcing. |
392 |
|
|
393 |
\item \textit{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and |
\item \texttt{hs94.cs-32x32x5} - 3D atmosphere dynamics using Held and |
394 |
Suarez '94 forcing on the cubed sphere. |
Suarez '94 forcing on the cubed sphere. |
395 |
|
|
396 |
\item \textit{aim.5l\_zon-ave} - Intermediate Atmospheric physics. |
\item \texttt{aim.5l\_zon-ave} - Intermediate Atmospheric physics. |
397 |
Global Zonal Mean configuration, 1x64x5 resolution. |
Global Zonal Mean configuration, 1x64x5 resolution. |
398 |
|
|
399 |
\item \textit{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate |
\item \texttt{aim.5l\_XZ\_Equatorial\_Slice} - Intermediate |
400 |
Atmospheric physics, equatorial Slice configuration. 2D (X-Z). |
Atmospheric physics, equatorial Slice configuration. 2D (X-Z). |
401 |
|
|
402 |
\item \textit{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric |
\item \texttt{aim.5l\_Equatorial\_Channel} - Intermediate Atmospheric |
403 |
physics. 3D Equatorial Channel configuration. |
physics. 3D Equatorial Channel configuration. |
404 |
|
|
405 |
\item \textit{aim.5l\_LatLon} - Intermediate Atmospheric physics. |
\item \texttt{aim.5l\_LatLon} - Intermediate Atmospheric physics. |
406 |
Global configuration, on latitude longitude grid with 128x64x5 grid |
Global configuration, on latitude longitude grid with 128x64x5 grid |
407 |
points ($2.8^\circ{\rm degree}$ resolution). |
points ($2.8^\circ{\rm degree}$ resolution). |
408 |
|
|
409 |
\item \textit{adjustment.128x64x1} Barotropic adjustment problem on |
\item \texttt{adjustment.128x64x1} Barotropic adjustment problem on |
410 |
latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm |
latitude longitude grid with 128x64 grid points ($2.8^\circ{\rm |
411 |
degree}$ resolution). |
degree}$ resolution). |
412 |
|
|
413 |
\item \textit{adjustment.cs-32x32x1} Barotropic adjustment problem on |
\item \texttt{adjustment.cs-32x32x1} Barotropic adjustment problem on |
414 |
cube sphere grid with 32x32 points per face ( roughly $2.8^\circ{\rm |
cube sphere grid with 32x32 points per face ( roughly $2.8^\circ{\rm |
415 |
degree}$ resolution). |
degree}$ resolution). |
416 |
|
|
417 |
\item \textit{advect\_cs} Two-dimensional passive advection test on |
\item \texttt{advect\_cs} Two-dimensional passive advection test on |
418 |
cube sphere grid. |
cube sphere grid. |
419 |
|
|
420 |
\item \textit{advect\_xy} Two-dimensional (horizontal plane) passive |
\item \texttt{advect\_xy} Two-dimensional (horizontal plane) passive |
421 |
advection test on Cartesian grid. |
advection test on Cartesian grid. |
422 |
|
|
423 |
\item \textit{advect\_yz} Two-dimensional (vertical plane) passive |
\item \texttt{advect\_yz} Two-dimensional (vertical plane) passive |
424 |
advection test on Cartesian grid. |
advection test on Cartesian grid. |
425 |
|
|
426 |
\item \textit{carbon} Simple passive tracer experiment. Includes |
\item \texttt{carbon} Simple passive tracer experiment. Includes |
427 |
derivative calculation. Described in detail in section |
derivative calculation. Described in detail in section |
428 |
\ref{sect:eg-carbon-ad}. |
\ref{sect:eg-carbon-ad}. |
429 |
|
|
430 |
\item \textit{flt\_example} Example of using float package. |
\item \texttt{flt\_example} Example of using float package. |
431 |
|
|
432 |
\item \textit{global\_ocean.90x40x15} Global circulation with GM, flux |
\item \texttt{global\_ocean.90x40x15} Global circulation with GM, flux |
433 |
boundary conditions and poles. |
boundary conditions and poles. |
434 |
|
|
435 |
\item \textit{global\_ocean\_pressure} Global circulation in pressure |
\item \texttt{global\_ocean\_pressure} Global circulation in pressure |
436 |
coordinate (non-Boussinesq ocean model). Described in detail in |
coordinate (non-Boussinesq ocean model). Described in detail in |
437 |
section \ref{sect:eg-globalpressure}. |
section \ref{sect:eg-globalpressure}. |
438 |
|
|
439 |
\item \textit{solid-body.cs-32x32x1} Solid body rotation test for cube |
\item \texttt{solid-body.cs-32x32x1} Solid body rotation test for cube |
440 |
sphere grid. |
sphere grid. |
441 |
|
|
442 |
\end{enumerate} |
\end{enumerate} |
446 |
Each example directory has the following subdirectories: |
Each example directory has the following subdirectories: |
447 |
|
|
448 |
\begin{itemize} |
\begin{itemize} |
449 |
\item \textit{code}: contains the code particular to the example. At a |
\item \texttt{code}: contains the code particular to the example. At a |
450 |
minimum, this directory includes the following files: |
minimum, this directory includes the following files: |
451 |
|
|
452 |
\begin{itemize} |
\begin{itemize} |
453 |
\item \textit{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to |
\item \texttt{code/packages.conf}: declares the list of packages or |
454 |
|
package groups to be used. If not included, the default version |
455 |
|
is located in \texttt{pkg/pkg\_default}. Package groups are |
456 |
|
simply convenient collections of commonly used packages which are |
457 |
|
defined in \texttt{pkg/pkg\_default}. Some packages may require |
458 |
|
other packages or may require their absence (that is, they are |
459 |
|
incompatible) and these package dependencies are listed in |
460 |
|
\texttt{pkg/pkg\_depend}. |
461 |
|
|
462 |
|
\item \texttt{code/CPP\_EEOPTIONS.h}: declares CPP keys relative to |
463 |
the ``execution environment'' part of the code. The default |
the ``execution environment'' part of the code. The default |
464 |
version is located in \textit{eesupp/inc}. |
version is located in \texttt{eesupp/inc}. |
465 |
|
|
466 |
\item \textit{code/CPP\_OPTIONS.h}: declares CPP keys relative to |
\item \texttt{code/CPP\_OPTIONS.h}: declares CPP keys relative to |
467 |
the ``numerical model'' part of the code. The default version is |
the ``numerical model'' part of the code. The default version is |
468 |
located in \textit{model/inc}. |
located in \texttt{model/inc}. |
469 |
|
|
470 |
\item \textit{code/SIZE.h}: declares size of underlying |
\item \texttt{code/SIZE.h}: declares size of underlying |
471 |
computational grid. The default version is located in |
computational grid. The default version is located in |
472 |
\textit{model/inc}. |
\texttt{model/inc}. |
473 |
\end{itemize} |
\end{itemize} |
474 |
|
|
475 |
In addition, other include files and subroutines might be present in |
In addition, other include files and subroutines might be present in |
476 |
\textit{code} depending on the particular experiment. See Section 2 |
\texttt{code} depending on the particular experiment. See Section 2 |
477 |
for more details. |
for more details. |
478 |
|
|
479 |
\item \textit{input}: contains the input data files required to run |
\item \texttt{input}: contains the input data files required to run |
480 |
the example. At a minimum, the \textit{input} directory contains the |
the example. At a minimum, the \texttt{input} directory contains the |
481 |
following files: |
following files: |
482 |
|
|
483 |
\begin{itemize} |
\begin{itemize} |
484 |
\item \textit{input/data}: this file, written as a namelist, |
\item \texttt{input/data}: this file, written as a namelist, |
485 |
specifies the main parameters for the experiment. |
specifies the main parameters for the experiment. |
486 |
|
|
487 |
\item \textit{input/data.pkg}: contains parameters relative to the |
\item \texttt{input/data.pkg}: contains parameters relative to the |
488 |
packages used in the experiment. |
packages used in the experiment. |
489 |
|
|
490 |
\item \textit{input/eedata}: this file contains ``execution |
\item \texttt{input/eedata}: this file contains ``execution |
491 |
environment'' data. At present, this consists of a specification |
environment'' data. At present, this consists of a specification |
492 |
of the number of threads to use in $X$ and $Y$ under multithreaded |
of the number of threads to use in $X$ and $Y$ under multithreaded |
493 |
execution. |
execution. |
498 |
of the experiment. This varies from experiment to experiment. See |
of the experiment. This varies from experiment to experiment. See |
499 |
section 2 for more details. |
section 2 for more details. |
500 |
|
|
501 |
\item \textit{results}: this directory contains the output file |
\item \texttt{results}: this directory contains the output file |
502 |
\textit{output.txt} produced by the simulation example. This file is |
\texttt{output.txt} produced by the simulation example. This file is |
503 |
useful for comparison with your own output when you run the |
useful for comparison with your own output when you run the |
504 |
experiment. |
experiment. |
505 |
\end{itemize} |
\end{itemize} |
513 |
<!-- CMIREDIR:buildingCode: --> |
<!-- CMIREDIR:buildingCode: --> |
514 |
\end{rawhtml} |
\end{rawhtml} |
515 |
|
|
516 |
To compile the code, we use the {\em make} program. This uses a file |
To compile the code, we use the \texttt{make} program. This uses a |
517 |
({\em Makefile}) that allows us to pre-process source files, specify |
file (\texttt{Makefile}) that allows us to pre-process source files, |
518 |
compiler and optimization options and also figures out any file |
specify compiler and optimization options and also figures out any |
519 |
dependencies. We supply a script ({\em genmake2}), described in |
file dependencies. We supply a script (\texttt{genmake2}), described |
520 |
section \ref{sect:genmake}, that automatically creates the {\em |
in section \ref{sect:genmake}, that automatically creates the |
521 |
Makefile} for you. You then need to build the dependencies and |
\texttt{Makefile} for you. You then need to build the dependencies and |
522 |
compile the code. |
compile the code. |
523 |
|
|
524 |
As an example, let's assume that you want to build and run experiment |
As an example, assume that you want to build and run experiment |
525 |
\textit{verification/exp2}. The are multiple ways and places to |
\texttt{verification/exp2}. The are multiple ways and places to |
526 |
actually do this but here let's build the code in |
actually do this but here let's build the code in |
527 |
\textit{verification/exp2/input}: |
\texttt{verification/exp2/build}: |
528 |
\begin{verbatim} |
\begin{verbatim} |
529 |
% cd verification/exp2/input |
% cd verification/exp2/build |
530 |
\end{verbatim} |
\end{verbatim} |
531 |
First, build the {\em Makefile}: |
First, build the \texttt{Makefile}: |
532 |
\begin{verbatim} |
\begin{verbatim} |
533 |
% ../../../tools/genmake2 -mods=../code |
% ../../../tools/genmake2 -mods=../code |
534 |
\end{verbatim} |
\end{verbatim} |
535 |
The command line option tells {\em genmake} to override model source |
The command line option tells \texttt{genmake} to override model source |
536 |
code with any files in the directory {\em ../code/}. |
code with any files in the directory \texttt{../code/}. |
537 |
|
|
538 |
On many systems, the {\em genmake2} program will be able to |
On many systems, the \texttt{genmake2} program will be able to |
539 |
automatically recognize the hardware, find compilers and other tools |
automatically recognize the hardware, find compilers and other tools |
540 |
within the user's path (``echo \$PATH''), and then choose an |
within the user's path (``\texttt{echo \$PATH}''), and then choose an |
541 |
appropriate set of options from the files (``optfiles'') contained in |
appropriate set of options from the files (``optfiles'') contained in |
542 |
the {\em tools/build\_options} directory. Under some circumstances, a |
the \texttt{tools/build\_options} directory. Under some |
543 |
user may have to create a new ``optfile'' in order to specify the |
circumstances, a user may have to create a new ``optfile'' in order to |
544 |
exact combination of compiler, compiler flags, libraries, and other |
specify the exact combination of compiler, compiler flags, libraries, |
545 |
options necessary to build a particular configuration of MITgcm. In |
and other options necessary to build a particular configuration of |
546 |
such cases, it is generally helpful to read the existing ``optfiles'' |
MITgcm. In such cases, it is generally helpful to read the existing |
547 |
and mimic their syntax. |
``optfiles'' and mimic their syntax. |
548 |
|
|
549 |
Through the MITgcm-support list, the MITgcm developers are willing to |
Through the MITgcm-support list, the MITgcm developers are willing to |
550 |
provide help writing or modifing ``optfiles''. And we encourage users |
provide help writing or modifing ``optfiles''. And we encourage users |
555 |
\begin{rawhtml} </A> \end{rawhtml} |
\begin{rawhtml} </A> \end{rawhtml} |
556 |
list. |
list. |
557 |
|
|
558 |
To specify an optfile to {\em genmake2}, the syntax is: |
To specify an optfile to \texttt{genmake2}, the syntax is: |
559 |
\begin{verbatim} |
\begin{verbatim} |
560 |
% ../../../tools/genmake2 -mods=../code -of /path/to/optfile |
% ../../../tools/genmake2 -mods=../code -of /path/to/optfile |
561 |
\end{verbatim} |
\end{verbatim} |
562 |
|
|
563 |
Once a {\em Makefile} has been generated, we create the dependencies: |
Once a \texttt{Makefile} has been generated, we create the |
564 |
|
dependencies with the command: |
565 |
\begin{verbatim} |
\begin{verbatim} |
566 |
% make depend |
% make depend |
567 |
\end{verbatim} |
\end{verbatim} |
568 |
This modifies the {\em Makefile} by attaching a [long] list of files |
This modifies the \texttt{Makefile} by attaching a (usually, long) |
569 |
upon which other files depend. The purpose of this is to reduce |
list of files upon which other files depend. The purpose of this is to |
570 |
re-compilation if and when you start to modify the code. The {\tt make |
reduce re-compilation if and when you start to modify the code. The |
571 |
depend} command also creates links from the model source to this |
{\tt make depend} command also creates links from the model source to |
572 |
directory. It is important to note that the {\tt make depend} stage |
this directory. It is important to note that the {\tt make depend} |
573 |
will occasionally produce warnings or errors since the dependency |
stage will occasionally produce warnings or errors since the |
574 |
parsing tool is unable to find all of the necessary header files |
dependency parsing tool is unable to find all of the necessary header |
575 |
(\textit{eg.} \texttt{netcdf.inc}). In these circumstances, it is |
files (\textit{eg.} \texttt{netcdf.inc}). In these circumstances, it |
576 |
usually OK to ignore the warnings/errors and proceed to the next step. |
is usually OK to ignore the warnings/errors and proceed to the next |
577 |
|
step. |
578 |
|
|
579 |
Next compile the code: |
Next one can compile the code using: |
580 |
\begin{verbatim} |
\begin{verbatim} |
581 |
% make |
% make |
582 |
\end{verbatim} |
\end{verbatim} |
583 |
The {\tt make} command creates an executable called \textit{mitgcmuv}. |
The {\tt make} command creates an executable called \texttt{mitgcmuv}. |
584 |
Additional make ``targets'' are defined within the makefile to aid in |
Additional make ``targets'' are defined within the makefile to aid in |
585 |
the production of adjoint and other versions of MITgcm. |
the production of adjoint and other versions of MITgcm. On SMP |
586 |
|
(shared multi-processor) systems, the build process can often be sped |
587 |
|
up appreciably using the command: |
588 |
|
\begin{verbatim} |
589 |
|
% make -j 2 |
590 |
|
\end{verbatim} |
591 |
|
where the ``2'' can be replaced with a number that corresponds to the |
592 |
|
number of CPUs available. |
593 |
|
|
594 |
Now you are ready to run the model. General instructions for doing so are |
Now you are ready to run the model. General instructions for doing so are |
595 |
given in section \ref{sect:runModel}. Here, we can run the model with: |
given in section \ref{sect:runModel}. Here, we can run the model by |
596 |
|
first creating links to all the input files: |
597 |
|
\begin{verbatim} |
598 |
|
ln -s ../input/* . |
599 |
|
\end{verbatim} |
600 |
|
and then calling the executable with: |
601 |
\begin{verbatim} |
\begin{verbatim} |
602 |
./mitgcmuv > output.txt |
./mitgcmuv > output.txt |
603 |
\end{verbatim} |
\end{verbatim} |
604 |
where we are re-directing the stream of text output to the file {\em |
where we are re-directing the stream of text output to the file |
605 |
output.txt}. |
\texttt{output.txt}. |
606 |
|
|
607 |
|
|
608 |
\section[Running MITgcm]{Running the model in prognostic mode} |
\section[Running MITgcm]{Running the model in prognostic mode} |
611 |
<!-- CMIREDIR:runModel: --> |
<!-- CMIREDIR:runModel: --> |
612 |
\end{rawhtml} |
\end{rawhtml} |
613 |
|
|
614 |
If compilation finished succesfuully (section \ref{sect:buildingCode}) |
If compilation finished succesfully (section \ref{sect:buildingCode}) |
615 |
then an executable called \texttt{mitgcmuv} will now exist in the |
then an executable called \texttt{mitgcmuv} will now exist in the |
616 |
local directory. |
local directory. |
617 |
|
|
626 |
your screen. This output contains details such as parameter values as |
your screen. This output contains details such as parameter values as |
627 |
well as diagnostics such as mean Kinetic energy, largest CFL number, |
well as diagnostics such as mean Kinetic energy, largest CFL number, |
628 |
etc. It is worth keeping this text output with the binary output so we |
etc. It is worth keeping this text output with the binary output so we |
629 |
normally re-direct the {\em stdout} stream as follows: |
normally re-direct the \texttt{stdout} stream as follows: |
630 |
\begin{verbatim} |
\begin{verbatim} |
631 |
% ./mitgcmuv > output.txt |
% ./mitgcmuv > output.txt |
632 |
\end{verbatim} |
\end{verbatim} |
634 |
helpful to include the last few line of this \texttt{output.txt} file |
helpful to include the last few line of this \texttt{output.txt} file |
635 |
along with the (\texttt{stderr}) error message within any bug reports. |
along with the (\texttt{stderr}) error message within any bug reports. |
636 |
|
|
637 |
For the example experiments in {\em verification}, an example of the |
For the example experiments in \texttt{verification}, an example of the |
638 |
output is kept in {\em results/output.txt} for comparison. You can |
output is kept in \texttt{results/output.txt} for comparison. You can |
639 |
compare your {\em output.txt} with the corresponding one for that |
compare your \texttt{output.txt} with the corresponding one for that |
640 |
experiment to check that the set-up works. |
experiment to check that the set-up works. |
641 |
|
|
642 |
|
|
643 |
|
|
644 |
\subsection{Output files} |
\subsection{Output files} |
645 |
|
|
646 |
The model produces various output files. Depending upon the I/O |
The model produces various output files and, when using \texttt{mnc}, |
647 |
package selected (either \texttt{mdsio} or \texttt{mnc} or both as |
sometimes even directories. Depending upon the I/O package(s) |
648 |
determined by both the compile-time settings and the run-time flags in |
selected at compile time (either \texttt{mdsio} or \texttt{mnc} or |
649 |
\texttt{data.pkg}), the following output may appear. |
both as determined by \texttt{code/packages.conf}) and the run-time |
650 |
|
flags set (in \texttt{input/data.pkg}), the following output may |
651 |
|
appear. |
652 |
|
|
653 |
|
|
654 |
\subsubsection{MDSIO output files} |
\subsubsection{MDSIO output files} |
658 |
written out, which is made of the following files: |
written out, which is made of the following files: |
659 |
|
|
660 |
\begin{itemize} |
\begin{itemize} |
661 |
\item \textit{U.00000nIter} - zonal component of velocity field (m/s and $> |
\item \texttt{U.00000nIter} - zonal component of velocity field (m/s and $> |
662 |
0 $ eastward). |
0 $ eastward). |
663 |
|
|
664 |
\item \textit{V.00000nIter} - meridional component of velocity field (m/s |
\item \texttt{V.00000nIter} - meridional component of velocity field (m/s |
665 |
and $> 0$ northward). |
and $> 0$ northward). |
666 |
|
|
667 |
\item \textit{W.00000nIter} - vertical component of velocity field (ocean: |
\item \texttt{W.00000nIter} - vertical component of velocity field (ocean: |
668 |
m/s and $> 0$ upward, atmosphere: Pa/s and $> 0$ towards increasing pressure |
m/s and $> 0$ upward, atmosphere: Pa/s and $> 0$ towards increasing pressure |
669 |
i.e. downward). |
i.e. downward). |
670 |
|
|
671 |
\item \textit{T.00000nIter} - potential temperature (ocean: $^{0}$C, |
\item \texttt{T.00000nIter} - potential temperature (ocean: $^{0}$C, |
672 |
atmosphere: $^{0}$K). |
atmosphere: $^{0}$K). |
673 |
|
|
674 |
\item \textit{S.00000nIter} - ocean: salinity (psu), atmosphere: water vapor |
\item \texttt{S.00000nIter} - ocean: salinity (psu), atmosphere: water vapor |
675 |
(g/kg). |
(g/kg). |
676 |
|
|
677 |
\item \textit{Eta.00000nIter} - ocean: surface elevation (m), atmosphere: |
\item \texttt{Eta.00000nIter} - ocean: surface elevation (m), atmosphere: |
678 |
surface pressure anomaly (Pa). |
surface pressure anomaly (Pa). |
679 |
\end{itemize} |
\end{itemize} |
680 |
|
|
681 |
The chain \textit{00000nIter} consists of ten figures that specify the |
The chain \texttt{00000nIter} consists of ten figures that specify the |
682 |
iteration number at which the output is written out. For example, \textit{% |
iteration number at which the output is written out. For example, \texttt{% |
683 |
U.0000000300} is the zonal velocity at iteration 300. |
U.0000000300} is the zonal velocity at iteration 300. |
684 |
|
|
685 |
In addition, a ``pickup'' or ``checkpoint'' file called: |
In addition, a ``pickup'' or ``checkpoint'' file called: |
686 |
|
|
687 |
\begin{itemize} |
\begin{itemize} |
688 |
\item \textit{pickup.00000nIter} |
\item \texttt{pickup.00000nIter} |
689 |
\end{itemize} |
\end{itemize} |
690 |
|
|
691 |
is written out. This file represents the state of the model in a condensed |
is written out. This file represents the state of the model in a condensed |
693 |
there is an additional ``pickup'' file: |
there is an additional ``pickup'' file: |
694 |
|
|
695 |
\begin{itemize} |
\begin{itemize} |
696 |
\item \textit{pickup\_cd.00000nIter} |
\item \texttt{pickup\_cd.00000nIter} |
697 |
\end{itemize} |
\end{itemize} |
698 |
|
|
699 |
containing the D-grid velocity data and that has to be written out as well |
containing the D-grid velocity data and that has to be written out as well |
700 |
in order to restart the integration. Rolling checkpoint files are the same |
in order to restart the integration. Rolling checkpoint files are the same |
701 |
as the pickup files but are named differently. Their name contain the chain |
as the pickup files but are named differently. Their name contain the chain |
702 |
\textit{ckptA} or \textit{ckptB} instead of \textit{00000nIter}. They can be |
\texttt{ckptA} or \texttt{ckptB} instead of \texttt{00000nIter}. They can be |
703 |
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 |
704 |
output to save disk space during long integrations. |
output to save disk space during long integrations. |
705 |
|
|
713 |
within this subdirectory are all in the ``self-describing'' netCDF |
within this subdirectory are all in the ``self-describing'' netCDF |
714 |
format and can thus be browsed and/or plotted using tools such as: |
format and can thus be browsed and/or plotted using tools such as: |
715 |
\begin{itemize} |
\begin{itemize} |
716 |
\item At a minimum, the \texttt{ncdump} utility is typically included |
\item \texttt{ncdump} is a utility which is typically included |
717 |
with every netCDF install: |
with every netCDF install: |
718 |
\begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml} |
\begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml} |
719 |
\begin{verbatim} |
\begin{verbatim} |
720 |
http://www.unidata.ucar.edu/packages/netcdf/ |
http://www.unidata.ucar.edu/packages/netcdf/ |
721 |
\end{verbatim} |
\end{verbatim} |
722 |
\begin{rawhtml} </A> \end{rawhtml} |
\begin{rawhtml} </A> \end{rawhtml} and it converts the netCDF |
723 |
|
binaries into formatted ASCII text files. |
724 |
|
|
725 |
\item The \texttt{ncview} utility is a very convenient and quick way |
\item \texttt{ncview} utility is a very convenient and quick way |
726 |
to plot netCDF data and it runs on most OSes: |
to plot netCDF data and it runs on most OSes: |
727 |
\begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml} |
\begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml} |
728 |
\begin{verbatim} |
\begin{verbatim} |
729 |
http://meteora.ucsd.edu/~pierce/ncview_home_page.html |
http://meteora.ucsd.edu/~pierce/ncview_home_page.html |
730 |
\end{verbatim} |
\end{verbatim} |
731 |
\begin{rawhtml} </A> \end{rawhtml} |
\begin{rawhtml} </A> \end{rawhtml} |
732 |
|
|
737 |
http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html |
http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html |
738 |
\end{verbatim} |
\end{verbatim} |
739 |
\begin{rawhtml} </A> \end{rawhtml} |
\begin{rawhtml} </A> \end{rawhtml} |
|
|
|
740 |
\end{itemize} |
\end{itemize} |
741 |
|
|
742 |
|
|
744 |
|
|
745 |
The ``traditional'' or mdsio model data are written according to a |
The ``traditional'' or mdsio model data are written according to a |
746 |
``meta/data'' file format. Each variable is associated with two files |
``meta/data'' file format. Each variable is associated with two files |
747 |
with suffix names \textit{.data} and \textit{.meta}. The |
with suffix names \texttt{.data} and \texttt{.meta}. The |
748 |
\textit{.data} file contains the data written in binary form |
\texttt{.data} file contains the data written in binary form |
749 |
(big\_endian by default). The \textit{.meta} file is a ``header'' file |
(big\_endian by default). The \texttt{.meta} file is a ``header'' file |
750 |
that contains information about the size and the structure of the |
that contains information about the size and the structure of the |
751 |
\textit{.data} file. This way of organizing the output is particularly |
\texttt{.data} file. This way of organizing the output is particularly |
752 |
useful when running multi-processors calculations. The base version of |
useful when running multi-processors calculations. The base version of |
753 |
the model includes a few matlab utilities to read output files written |
the model includes a few matlab utilities to read output files written |
754 |
in this format. The matlab scripts are located in the directory |
in this format. The matlab scripts are located in the directory |
755 |
\textit{utils/matlab} under the root tree. The script \textit{rdmds.m} |
\texttt{utils/matlab} under the root tree. The script \texttt{rdmds.m} |
756 |
reads the data. Look at the comments inside the script to see how to |
reads the data. Look at the comments inside the script to see how to |
757 |
use it. |
use it. |
758 |
|
|
771 |
>> 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 |
772 |
\end{verbatim} |
\end{verbatim} |
773 |
|
|
774 |
Similar scripts for netCDF output (\texttt{rdmnc.m}) are available. |
Similar scripts for netCDF output (\texttt{rdmnc.m}) are available and |
775 |
|
they are described in Section \ref{sec:pkg:mnc}. |
776 |
|
|