--- manual/s_phys_pkgs/mnc.tex	2004/02/04 04:49:19	1.4
+++ manual/s_phys_pkgs/mnc.tex	2004/04/03 23:05:05	1.8
@@ -1,7 +1,7 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.4 2004/02/04 04:49:19 edhill Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.8 2004/04/03 23:05:05 edhill Exp $
 % $Name:  $
 
-\section{NetCDF I/O Integration}
+\section{NetCDF I/O Integration: MNC}
 \label{sec:pkg:mnc}
 
 The \texttt{mnc} package is a set of convenience routines written to
@@ -23,8 +23,8 @@
 The \texttt{mnc} package is a two-level convenience library (or
 ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
 streamline the user interface to NetCDF by maintaining internal
-relations (``look-up tables'') keyed with strings (or ``names'') and
-entities such as NetCDF files, variables, and attributes.
+relations (look-up tables) keyed with strings (or names) and entities
+such as NetCDF files, variables, and attributes.
 
 The two levels of the \texttt{mnc} package are:
 \begin{description}
@@ -34,7 +34,7 @@
   The upper level contains information about two kinds of
   associations:
   \begin{description}
-  \item[Grid type] is lookup table indexed with a grid type name.
+  \item[grid type] is lookup table indexed with a grid type name.
     Each grid type name is associated with a number of dimensions, the
     dimension sizes (one of which may be unlimited), and starting and
     ending index arrays.  The intent is to store all the necessary
@@ -44,7 +44,7 @@
     shown in Figures \ref{fig:communication_primitives} and
     \ref{fig:tiling-strategy}).
   
-  \item[Variable type] is a lookup table indexed by a variable type
+  \item[variable type] is a lookup table indexed by a variable type
     name.  For each name, the table contains a reference to a grid
     type for the variable and the names and values of various
     attributes.
@@ -66,11 +66,125 @@
 \end{description}
 
 
-\subsection{Key subroutines, parameters and files}
+\subsection{Using MNC}
 
-All of the variables used to implement the lookup tables are described
-in \filelink{pkg/mnc/mnc\_common.h}{pkg/mnc/mnc_common}.
+\subsubsection{Grid--Types and Variable--Types}
 
+As a convenience for users, the MNC package includes numerous routines
+to aid in the writing of data to NetCDF format.  Probably the biggest
+convenience is the use of pre-defined ``grid types'' and ``variable
+types''.  These ``types'' are simply look-up tables that store
+dimensions, indicies, attributes, and other information that can all
+be retrieved using a single character string.
+
+The ``grid types'' are a way of mapping variables within MITgcm to
+NetCDF arrays.  Within MITgcm, most spatial variables are defined
+using two-- or three--dimensional arrays with ``overlap'' regions (see
+Figures \ref{fig:communication_primitives}, a possible vertical index,
+and \ref{fig:tiling-strategy}) and tile indicies such as the following
+``U'' velocity:
+\begin{verbatim}
+      _RL  uVel (1-OLx:sNx+OLx,1-OLy:sNy+OLy,Nr,nSx,nSy)
+\end{verbatim}
+as defined in \filelink{model/inc/DYNVARS.h}{model-inc-DYNVARS.h}
+
+The grid type is a character string that encodes the presence and
+types associated with the four possible dimensions.  The character
+string follows the format
+\begin{center}
+  \texttt{H0\_H1\_H2\_\_V\_\_T}
+\end{center}
+where the terms \textit{H0}, \textit{H1}, \textit{H2}, \textit{V},
+\textit{T} can be almost any combination of the following:
+\begin{center}
+  \begin{tabular}[h]{|ccc|c|c|}\hline
+    \multicolumn{3}{|c|}{Horizontal} & Vertical & Time \\
+    \textbf{H0}: location & \textbf{H1}: dimensions & \textbf{H2}: halo 
+          & \textbf{V}: location & \textbf{T}: level  \\\hline
+    \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\
+    U  &  x  &  Hy  &  i  &  t  \\
+    V  &  y  &      &  c  &     \\
+    Cen  &   &      &     &     \\
+    Cor  &   &      &     &     \\\hline
+  \end{tabular}
+\end{center}
+A example list of all pre-defined combinations is contained in the
+file
+\begin{center}
+  \texttt{pkg/mnc/pre-defined\_grids.txt}.
+\end{center}
+
+The variable type is an association between a variable type name and the
+following items:
+\begin{center}
+  \begin{tabular}[h]{|ll|}\hline
+    \textbf{Item}  & \textbf{Purpose}  \\\hline
+    grid type  &  defines the in-memory arrangement  \\
+    \texttt{bi,bj} dimensions  &  tiling indices, if present  \\\hline
+  \end{tabular}
+\end{center}
+and is used by the \texttt{mnc\_cw\_*\_[R|W]} subroutines for reading
+and writing variables.
+
+
+\subsubsection{An Example}
+
+Writing variables to NetCDF files can be accomplished in as few as two
+function calls.  The first function call defines a variable type,
+associates it with a name (character string), and provides additional
+information about the indicies for the tile (\texttt{bi},\texttt{bj})
+dimensions.  The second function call will write the data at, if
+necessary, the current time level within the model.
+
+Examples of the initialization calls can be found in the file 
+\filelink{model/src/ini\_mnc\_io.F}{model-src-ini_mnc_io.F}
+where these four function calls:
+{\footnotesize
+\begin{verbatim}
+C     Create MNC definitions for DYNVARS.h variables
+      CALL MNC_CW_ADD_VNAME('iter', '-_-_--__-__t', 0,0, myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('iter',1,
+     &     'long_name','iteration_count', myThid)
+
+      CALL MNC_CW_ADD_VNAME('model_time', '-_-_--__-__t', 0,0, myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,
+     &     'long_name','Model Time', myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,'units','s', myThid)
+
+      CALL MNC_CW_ADD_VNAME('U', 'U_xy_Hn__C__t', 4,5, myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('U',1,'units','m/s', myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('U',1,
+     &     'coordinates','XU YU RC iter', myThid)
+
+      CALL MNC_CW_ADD_VNAME('T', 'Cen_xy_Hn__C__t', 4,5, myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('T',1,'units','degC', myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('T',1,'long_name',
+     &     'potential_temperature', myThid)
+      CALL MNC_CW_ADD_VATTR_TEXT('T',1,
+     &     'coordinates','XC YC RC iter', myThid)
+\end{verbatim}
+}
+{\noindent initialize two \texttt{VNAME}s and add one NetCDF
+  attribute to each.}
+    
+The two variables defined above are subsequently written at specific
+time steps within
+\filelink{model/src/write\_state.F}{model-src-write_state.F}
+using the function calls:
+{\footnotesize
+\begin{verbatim}
+C       Write dynvars using the MNC package
+        mnc_iter = myIter
+        CALL MNC_CW_SET_UDIM('state', -1, myThid)
+        CALL MNC_CW_RL_W('D','state',0,0,'iter',mnc_iter, myThid)
+        CALL MNC_CW_SET_UDIM('state', 0, myThid)
+        CALL MNC_CW_RL_W('D','state',0,0,'model_time',myTime, myThid)
+        CALL MNC_CW_RL_W('D','state',0,0,'U', uVel, myThid)
+        CALL MNC_CW_RL_W('D','state',0,0,'T', theta, myThid)
+\end{verbatim}
+}
 
+%\subsection{Key subroutines, parameters and files}
 
 \subsection{Package Reference}
+