--- manual/s_getstarted/text/getting_started.tex	2004/10/14 14:54:24	1.28
+++ manual/s_getstarted/text/getting_started.tex	2004/10/14 19:11:47	1.29
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.28 2004/10/14 14:54:24 cnh Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_getstarted/text/getting_started.tex,v 1.29 2004/10/14 19:11:47 edhill Exp $
 % $Name:  $
 
 %\section{Getting started}
@@ -507,18 +507,18 @@
 % ../../../tools/genmake2 -mods=../code
 \end{verbatim}
 The command line option tells {\em genmake} to override model source
-code with any files in the directory {\em ./code/}.
+code with any files in the directory {\em ../code/}.
 
 On many systems, the {\em genmake2} program will be able to
 automatically recognize the hardware, find compilers and other tools
 within the user's path (``echo \$PATH''), and then choose an
-appropriate set of options from the files contained in the {\em
-  tools/build\_options} directory.  Under some circumstances, a user
-may have to create a new ``optfile'' in order to specify the exact
-combination of compiler, compiler flags, libraries, and other options
-necessary to build a particular configuration of MITgcm.  In such
-cases, it is generally helpful to read the existing ``optfiles'' and
-mimic their syntax.
+appropriate set of options from the files (``optfiles'') contained in
+the {\em tools/build\_options} directory.  Under some circumstances, a
+user may have to create a new ``optfile'' in order to specify the
+exact combination of compiler, compiler flags, libraries, and other
+options necessary to build a particular configuration of MITgcm.  In
+such cases, it is generally helpful to read the existing ``optfiles''
+and mimic their syntax.
 
 Through the MITgcm-support list, the MITgcm developers are willing to
 provide help writing or modifing ``optfiles''.  And we encourage users
@@ -542,7 +542,11 @@
 upon which other files depend. The purpose of this is to reduce
 re-compilation if and when you start to modify the code. The {\tt make
   depend} command also creates links from the model source to this
-directory.
+directory.  It is important to note that the {\tt make depend} stage
+will occasionally produce warnings or errors since the dependency
+parsing tool is unable to find all of the necessary header files
+(\textit{eg.}  \texttt{netcdf.inc}).  In these circumstances, it is
+usually OK to ignore the warnings/errors and proceed to the next step.
 
 Next compile the code:
 \begin{verbatim}
@@ -568,8 +572,8 @@
 then an executable called \texttt{mitgcmuv} will now exist in the
 local directory.
 
-To run the model as a single process (ie. not in parallel) simply
-type:
+To run the model as a single process (\textit{ie.} not in parallel)
+simply type:
 \begin{verbatim}
 % ./mitgcmuv
 \end{verbatim}
@@ -583,17 +587,30 @@
 \begin{verbatim}
 % ./mitgcmuv > output.txt
 \end{verbatim}
+In the event that the model encounters an error and stops, it is very
+helpful to include the last few line of this \texttt{output.txt} file
+along with the (\texttt{stderr}) error message within any bug reports.
 
 For the example experiments in {\em verification}, an example of the
-output is kept in {\em results/output.txt} for comparison. You can compare
-your {\em output.txt} with this one to check that the set-up works.
+output is kept in {\em results/output.txt} for comparison. You can
+compare your {\em output.txt} with the corresponding one for that
+experiment to check that the set-up works.
 
 
 
 \subsection{Output files}
 
-The model produces various output files. At a minimum, the instantaneous
-``state'' of the model is written out, which is made of the following files:
+The model produces various output files.  Depending upon the I/O
+package selected (either \texttt{mdsio} or \texttt{mnc} or both as
+determined by both the compile-time settings and the run-time flags in
+\texttt{data.pkg}), the following output may appear.
+
+
+\subsubsection{MDSIO output files}
+
+The ``traditional'' output files are generated by the \texttt{mdsio}
+package.  At a minimum, the instantaneous ``state'' of the model is
+written out, which is made of the following files:
 
 \begin{itemize}
 \item \textit{U.00000nIter} - zonal component of velocity field (m/s and $>
@@ -641,19 +658,58 @@
 used to restart the model but are overwritten every other time they are
 output to save disk space during long integrations.
 
+
+
+\subsubsection{MNC output files}
+
+Unlike the \texttt{mdsio} output, the \texttt{mnc}--generated output
+is usually (though not necessarily) placed within a subdirectory with
+a name such as \texttt{mnc\_test\_\${DATE}\_\${SEQ}}.  The files
+within this subdirectory are all in the ``self-describing'' netCDF
+format and can thus be browsed and/or plotted using tools such as:
+\begin{itemize}
+\item At a minimum, the \texttt{ncdump} utility is typically included
+  with every netCDF install:
+  \begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}
+\begin{verbatim}
+http://www.unidata.ucar.edu/packages/netcdf/
+\end{verbatim}
+  \begin{rawhtml} </A> \end{rawhtml}
+
+\item The \texttt{ncview} utility is a very convenient and quick way
+  to plot netCDF data and it runs on most OSes:
+  \begin{rawhtml} <A href="http://meteora.ucsd.edu/~pierce/ncview_home_page.html"> \end{rawhtml}
+\begin{verbatim}
+http://meteora.ucsd.edu/~pierce/ncview_home_page.html
+\end{verbatim}
+  \begin{rawhtml} </A> \end{rawhtml}
+  
+\item MatLAB(c) and other common post-processing environments provide
+  various netCDF interfaces including:
+  \begin{rawhtml} <A href="http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html"> \end{rawhtml}
+\begin{verbatim}
+http://woodshole.er.usgs.gov/staffpages/cdenham/public_html/MexCDF/nc4ml5.html
+\end{verbatim}
+  \begin{rawhtml} </A> \end{rawhtml}
+
+\end{itemize}
+
+
 \subsection{Looking at the output}
 
-All the model data are written according to a ``meta/data'' file format.
-Each variable is associated with two files with suffix names \textit{.data}
-and \textit{.meta}. The \textit{.data} file contains the data written in
-binary form (big\_endian by default). The \textit{.meta} file is a
-``header'' file that contains information about the size and the structure
-of the \textit{.data} file. This way of organizing the output is
-particularly useful when running multi-processors calculations. The base
-version of the model includes a few matlab utilities to read output files
-written in this format. The matlab scripts are located in the directory 
-\textit{utils/matlab} under the root tree. The script \textit{rdmds.m} reads
-the data. Look at the comments inside the script to see how to use it.
+The ``traditional'' or mdsio model data are written according to a
+``meta/data'' file format.  Each variable is associated with two files
+with suffix names \textit{.data} and \textit{.meta}. The
+\textit{.data} file contains the data written in binary form
+(big\_endian by default). The \textit{.meta} file is a ``header'' file
+that contains information about the size and the structure of the
+\textit{.data} file. This way of organizing the output is particularly
+useful when running multi-processors calculations. The base version of
+the model includes a few matlab utilities to read output files written
+in this format. The matlab scripts are located in the directory
+\textit{utils/matlab} under the root tree. The script \textit{rdmds.m}
+reads the data. Look at the comments inside the script to see how to
+use it.
 
 Some examples of reading and visualizing some output in {\em Matlab}:
 \begin{verbatim}
@@ -670,3 +726,4 @@
 >> for n=1:11; imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
 \end{verbatim}
 
+Similar scripts for netCDF output (\texttt{rdmnc.m}) are available.