15 |
this section, we provide information on how to customize the code when |
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. |
you are ready to try implementing the configuration you have in mind. |
17 |
|
|
18 |
|
|
19 |
\section{Where to find information} |
\section{Where to find information} |
20 |
\label{sect:whereToFindInfo} |
\label{sect:whereToFindInfo} |
21 |
|
\begin{rawhtml} |
22 |
|
<!-- CMIREDIR:whereToFindInfo: --> |
23 |
|
\end{rawhtml} |
24 |
|
|
25 |
A web site is maintained for release 2 (``Pelican'') of MITgcm: |
A web site is maintained for release 2 (``Pelican'') of MITgcm: |
26 |
\begin{rawhtml} <A href=http://mitgcm.org/pelican/ target="idontexist"> \end{rawhtml} |
\begin{rawhtml} <A href=http://mitgcm.org/pelican/ target="idontexist"> \end{rawhtml} |
54 |
|
|
55 |
\section{Obtaining the code} |
\section{Obtaining the code} |
56 |
\label{sect:obtainingCode} |
\label{sect:obtainingCode} |
57 |
|
\begin{rawhtml} |
58 |
|
<!-- CMIREDIR:obtainingCode: --> |
59 |
|
\end{rawhtml} |
60 |
|
|
61 |
MITgcm can be downloaded from our system by following |
MITgcm can be downloaded from our system by following |
62 |
the instructions below. As a courtesy we ask that you send e-mail to us at |
the instructions below. As a courtesy we ask that you send e-mail to us at |
263 |
with. So please be sure you understand what you're doing. |
with. So please be sure you understand what you're doing. |
264 |
|
|
265 |
\section{Model and directory structure} |
\section{Model and directory structure} |
266 |
|
\begin{rawhtml} |
267 |
|
<!-- CMIREDIR:directory_structure: --> |
268 |
|
\end{rawhtml} |
269 |
|
|
270 |
The ``numerical'' model is contained within a execution environment |
The ``numerical'' model is contained within a execution environment |
271 |
support wrapper. This wrapper is designed to provide a general |
support wrapper. This wrapper is designed to provide a general |
336 |
|
|
337 |
\section[MITgcm Example Experiments]{Example experiments} |
\section[MITgcm Example Experiments]{Example experiments} |
338 |
\label{sect:modelExamples} |
\label{sect:modelExamples} |
339 |
|
\begin{rawhtml} |
340 |
|
<!-- CMIREDIR:modelExamples: --> |
341 |
|
\end{rawhtml} |
342 |
|
|
343 |
%% a set of twenty-four pre-configured numerical experiments |
%% a set of twenty-four pre-configured numerical experiments |
344 |
|
|
499 |
|
|
500 |
\section[Building MITgcm]{Building the code} |
\section[Building MITgcm]{Building the code} |
501 |
\label{sect:buildingCode} |
\label{sect:buildingCode} |
502 |
|
\begin{rawhtml} |
503 |
|
<!-- CMIREDIR:buildingCode: --> |
504 |
|
\end{rawhtml} |
505 |
|
|
506 |
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 |
507 |
({\em Makefile}) that allows us to pre-process source files, specify |
({\em Makefile}) that allows us to pre-process source files, specify |
523 |
% ../../../tools/genmake2 -mods=../code |
% ../../../tools/genmake2 -mods=../code |
524 |
\end{verbatim} |
\end{verbatim} |
525 |
The command line option tells {\em genmake} to override model source |
The command line option tells {\em genmake} to override model source |
526 |
code with any files in the directory {\em ./code/}. |
code with any files in the directory {\em ../code/}. |
527 |
|
|
528 |
On many systems, the {\em genmake2} program will be able to |
On many systems, the {\em genmake2} program will be able to |
529 |
automatically recognize the hardware, find compilers and other tools |
automatically recognize the hardware, find compilers and other tools |
530 |
within the user's path (``echo \$PATH''), and then choose an |
within the user's path (``echo \$PATH''), and then choose an |
531 |
appropriate set of options from the files contained in the {\em |
appropriate set of options from the files (``optfiles'') contained in |
532 |
tools/build\_options} directory. Under some circumstances, a user |
the {\em tools/build\_options} directory. Under some circumstances, a |
533 |
may have to create a new ``optfile'' in order to specify the exact |
user may have to create a new ``optfile'' in order to specify the |
534 |
combination of compiler, compiler flags, libraries, and other options |
exact combination of compiler, compiler flags, libraries, and other |
535 |
necessary to build a particular configuration of MITgcm. In such |
options necessary to build a particular configuration of MITgcm. In |
536 |
cases, it is generally helpful to read the existing ``optfiles'' and |
such cases, it is generally helpful to read the existing ``optfiles'' |
537 |
mimic their syntax. |
and mimic their syntax. |
538 |
|
|
539 |
Through the MITgcm-support list, the MITgcm developers are willing to |
Through the MITgcm-support list, the MITgcm developers are willing to |
540 |
provide help writing or modifing ``optfiles''. And we encourage users |
provide help writing or modifing ``optfiles''. And we encourage users |
558 |
upon which other files depend. The purpose of this is to reduce |
upon which other files depend. The purpose of this is to reduce |
559 |
re-compilation if and when you start to modify the code. The {\tt make |
re-compilation if and when you start to modify the code. The {\tt make |
560 |
depend} command also creates links from the model source to this |
depend} command also creates links from the model source to this |
561 |
directory. |
directory. It is important to note that the {\tt make depend} stage |
562 |
|
will occasionally produce warnings or errors since the dependency |
563 |
|
parsing tool is unable to find all of the necessary header files |
564 |
|
(\textit{eg.} \texttt{netcdf.inc}). In these circumstances, it is |
565 |
|
usually OK to ignore the warnings/errors and proceed to the next step. |
566 |
|
|
567 |
Next compile the code: |
Next compile the code: |
568 |
\begin{verbatim} |
\begin{verbatim} |
583 |
|
|
584 |
\section[Running MITgcm]{Running the model in prognostic mode} |
\section[Running MITgcm]{Running the model in prognostic mode} |
585 |
\label{sect:runModel} |
\label{sect:runModel} |
586 |
|
\begin{rawhtml} |
587 |
|
<!-- CMIREDIR:runModel: --> |
588 |
|
\end{rawhtml} |
589 |
|
|
590 |
If compilation finished succesfuully (section \ref{sect:buildingCode}) |
If compilation finished succesfuully (section \ref{sect:buildingCode}) |
591 |
then an executable called \texttt{mitgcmuv} will now exist in the |
then an executable called \texttt{mitgcmuv} will now exist in the |
592 |
local directory. |
local directory. |
593 |
|
|
594 |
To run the model as a single process (ie. not in parallel) simply |
To run the model as a single process (\textit{ie.} not in parallel) |
595 |
type: |
simply type: |
596 |
\begin{verbatim} |
\begin{verbatim} |
597 |
% ./mitgcmuv |
% ./mitgcmuv |
598 |
\end{verbatim} |
\end{verbatim} |
606 |
\begin{verbatim} |
\begin{verbatim} |
607 |
% ./mitgcmuv > output.txt |
% ./mitgcmuv > output.txt |
608 |
\end{verbatim} |
\end{verbatim} |
609 |
|
In the event that the model encounters an error and stops, it is very |
610 |
|
helpful to include the last few line of this \texttt{output.txt} file |
611 |
|
along with the (\texttt{stderr}) error message within any bug reports. |
612 |
|
|
613 |
For the example experiments in {\em verification}, an example of the |
For the example experiments in {\em verification}, an example of the |
614 |
output is kept in {\em results/output.txt} for comparison. You can compare |
output is kept in {\em results/output.txt} for comparison. You can |
615 |
your {\em output.txt} with this one to check that the set-up works. |
compare your {\em output.txt} with the corresponding one for that |
616 |
|
experiment to check that the set-up works. |
617 |
|
|
618 |
|
|
619 |
|
|
620 |
\subsection{Output files} |
\subsection{Output files} |
621 |
|
|
622 |
The model produces various output files. At a minimum, the instantaneous |
The model produces various output files. Depending upon the I/O |
623 |
``state'' of the model is written out, which is made of the following files: |
package selected (either \texttt{mdsio} or \texttt{mnc} or both as |
624 |
|
determined by both the compile-time settings and the run-time flags in |
625 |
|
\texttt{data.pkg}), the following output may appear. |
626 |
|
|
627 |
|
|
628 |
|
\subsubsection{MDSIO output files} |
629 |
|
|
630 |
|
The ``traditional'' output files are generated by the \texttt{mdsio} |
631 |
|
package. At a minimum, the instantaneous ``state'' of the model is |
632 |
|
written out, which is made of the following files: |
633 |
|
|
634 |
\begin{itemize} |
\begin{itemize} |
635 |
\item \textit{U.00000nIter} - zonal component of velocity field (m/s and $> |
\item \textit{U.00000nIter} - zonal component of velocity field (m/s and $> |
677 |
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 |
678 |
output to save disk space during long integrations. |
output to save disk space during long integrations. |
679 |
|
|
680 |
|
|
681 |
|
|
682 |
|
\subsubsection{MNC output files} |
683 |
|
|
684 |
|
Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output |
685 |
|
is usually (though not necessarily) placed within a subdirectory with |
686 |
|
a name such as \texttt{mnc\_test\_\${DATE}\_\${SEQ}}. The files |
687 |
|
within this subdirectory are all in the ``self-describing'' netCDF |
688 |
|
format and can thus be browsed and/or plotted using tools such as: |
689 |
|
\begin{itemize} |
690 |
|
\item At a minimum, the \texttt{ncdump} utility is typically included |
691 |
|
with every netCDF install: |
692 |
|
\begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml} |
693 |
|
\begin{verbatim} |
694 |
|
http://www.unidata.ucar.edu/packages/netcdf/ |
695 |
|
\end{verbatim} |
696 |
|
\begin{rawhtml} </A> \end{rawhtml} |
697 |
|
|
698 |
|
\item The \texttt{ncview} utility is a very convenient and quick way |
699 |
|
to plot netCDF data and it runs on most OSes: |
700 |
|
\begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml} |
701 |
|
\begin{verbatim} |
702 |
|
http://meteora.ucsd.edu/~pierce/ncview_home_page.html |
703 |
|
\end{verbatim} |
704 |
|
\begin{rawhtml} </A> \end{rawhtml} |
705 |
|
|
706 |
|
\item MatLAB(c) and other common post-processing environments provide |
707 |
|
various netCDF interfaces including: |
708 |
|
\begin{rawhtml} <A href="http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html"> \end{rawhtml} |
709 |
|
\begin{verbatim} |
710 |
|
http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html |
711 |
|
\end{verbatim} |
712 |
|
\begin{rawhtml} </A> \end{rawhtml} |
713 |
|
|
714 |
|
\end{itemize} |
715 |
|
|
716 |
|
|
717 |
\subsection{Looking at the output} |
\subsection{Looking at the output} |
718 |
|
|
719 |
All the model data are written according to a ``meta/data'' file format. |
The ``traditional'' or mdsio model data are written according to a |
720 |
Each variable is associated with two files with suffix names \textit{.data} |
``meta/data'' file format. Each variable is associated with two files |
721 |
and \textit{.meta}. The \textit{.data} file contains the data written in |
with suffix names \textit{.data} and \textit{.meta}. The |
722 |
binary form (big\_endian by default). The \textit{.meta} file is a |
\textit{.data} file contains the data written in binary form |
723 |
``header'' file that contains information about the size and the structure |
(big\_endian by default). The \textit{.meta} file is a ``header'' file |
724 |
of the \textit{.data} file. This way of organizing the output is |
that contains information about the size and the structure of the |
725 |
particularly useful when running multi-processors calculations. The base |
\textit{.data} file. This way of organizing the output is particularly |
726 |
version of the model includes a few matlab utilities to read output files |
useful when running multi-processors calculations. The base version of |
727 |
written in this format. The matlab scripts are located in the directory |
the model includes a few matlab utilities to read output files written |
728 |
\textit{utils/matlab} under the root tree. The script \textit{rdmds.m} reads |
in this format. The matlab scripts are located in the directory |
729 |
the data. Look at the comments inside the script to see how to use it. |
\textit{utils/matlab} under the root tree. The script \textit{rdmds.m} |
730 |
|
reads the data. Look at the comments inside the script to see how to |
731 |
|
use it. |
732 |
|
|
733 |
Some examples of reading and visualizing some output in {\em Matlab}: |
Some examples of reading and visualizing some output in {\em Matlab}: |
734 |
\begin{verbatim} |
\begin{verbatim} |
745 |
>> 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 |
746 |
\end{verbatim} |
\end{verbatim} |
747 |
|
|
748 |
|
Similar scripts for netCDF output (\texttt{rdmnc.m}) are available. |