--- manual/s_phys_pkgs/mnc.tex	2004/04/02 15:56:02	1.7
+++ manual/s_phys_pkgs/mnc.tex	2004/09/22 15:11:32	1.11
@@ -1,4 +1,4 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.7 2004/04/02 15:56:02 edhill Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.11 2004/09/22 15:11:32 edhill Exp $
 % $Name:  $
 
 \section{NetCDF I/O Integration: MNC}
@@ -117,7 +117,7 @@
 The variable type is an association between a variable type name and the
 following items:
 \begin{center}
-  \begin{tabular}[h]{|ll|}\hline
+  \begin{tabular}[h]{|l|l|}\hline
     \textbf{Item}  & \textbf{Purpose}  \\\hline
     grid type  &  defines the in-memory arrangement  \\
     \texttt{bi,bj} dimensions  &  tiling indices, if present  \\\hline
@@ -137,41 +137,137 @@
 necessary, the current time level within the model.
 
 Examples of the initialization calls can be found in the file 
-\filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F}
-where these four function calls:
+\filelink{model/src/ini\_mnc\_io.F}{model-src-ini_mnc_io.F}
+where these function calls:
 {\footnotesize
 \begin{verbatim}
-  C     Create MNC definitions for DYNVARS.h variables
-        CALL MNC_CW_ADD_VNAME(myThid, 'iter', '-_-_--__-__t', 0,0)
-        CALL MNC_CW_ADD_VATTR_TEXT(myThid,'iter',1,
-       &     'long_name','iteration_count')
-        CALL MNC_CW_ADD_VNAME(myThid, 'U', 'U_xy_Hn__C__t', 4,5)
-        CALL MNC_CW_ADD_VATTR_TEXT(myThid,'U',1,'units','m/s')
+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.}
+{\noindent initialize four \texttt{VNAME}s and add one or more NetCDF
+  attributes to each.}
     
-The two variables defined above are subsequently written at specific
+The four 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 the DYNVARS.h variables using the MNC package
-        mnc_iter = myIter
-        CALL MNC_CW_RL_W_R(myThid,'state',0,0,'iter',-1,mnc_iter)
-        CALL MNC_CW_RL_W_D(myThid,'state',0,0,'U', 0, uVel)
+C       Write dynvars using the MNC package
+        CALL MNC_CW_SET_UDIM('state', -1, myThid)
+        CALL MNC_CW_I_W('I','state',0,0,'iter', myIter, 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}
+\subsubsection{Parameters}
 
-All of the variables used to implement the lookup tables are described
-in \filelink{model/src/write\_state.F}{model-src-write_state.F}
+Most of the MNC--related parameters are contained within a Fortran
+namelist file called \texttt{data.mnc}.  If this file does not exist,
+then the MNC package will interpret that as an indication that it is
+not to be used.  If the \texttt{data.mnc} file does exist, then it may
+contain the following parameters:
 
+\begin{center}
+  {\footnotesize
+    \begin{tabular}[htb]{|l|c|l|l|}\hline
+      \textbf{Name}  &  \textbf{T}  &  
+      \textbf{Default}  &  \textbf{Description}  \\\hline
+      &  &  &  \\
+      \texttt{useMNC}  &  L  & \texttt{.FALSE.}  &  
+      \textbf{overall MNC ON/OFF switch}  \\
+      \texttt{mnc\_echo\_gvtypes}  &  L  & \texttt{.FALSE.}  &  
+      echo pre-defined ``types'' (debugging)   \\
+      \texttt{mnc\_use\_outdir}  &  L  & \texttt{.FALSE.}  &  
+      create a directory for output  \\
+      \texttt{mnc\_outdir\_str}  &  S  & \texttt{'mnc\_'}  &  
+      output directory name \\
+      \texttt{mnc\_outdir\_date}  &  L  & \texttt{.FALSE.}  &  
+      embed date in the output dir name  \\
+      \texttt{pickup\_write\_mnc}  &  L  & \texttt{.FALSE.}  &  
+      use MNC to write (create) pickup files  \\
+      \texttt{pickup\_read\_mnc}  &  L  & \texttt{.FALSE.}  &  
+      use MNC to read pickup files  \\
+      \texttt{mnc\_use\_indir}  &  L  & \texttt{.FALSE.}  &  
+      use a directory (path) for input  \\
+      \texttt{mnc\_indir\_str}  &  S  & \texttt{''}  &  
+      input directory (or path) name  \\
+      \texttt{snapshot\_mnc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{snapshot} (instantaneous) w/MNC  \\
+      \texttt{monitor\_mnc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{monitor} w/MNC  \\
+      \texttt{timeave\_mnc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{timeave} w/MNC  \\\hline
+    \end{tabular}
+  }
+\end{center}
 
+Additional MNC--related parameters are contained within the main
+\texttt{data} namelist file and in some of the namelist files for
+individual packages.  These options are:
+\begin{center}
+  {\footnotesize
+    \begin{tabular}[htb]{|l|c|l|l|}\hline
+      \textbf{Name}  &  \textbf{T}  &  
+      \textbf{Default}  &  \textbf{Description}  \\\hline
+      \multicolumn{4}{|c|}{\ }  \\
+      \multicolumn{4}{|c|}{Main namelist file: 
+        ``\textbf{data}''}  \\\hline
+      \texttt{snapshot\_ioinc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{snapshot} ``inclusively''  \\
+      \texttt{timeave\_ioinc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{timeave} ``inclusively''  \\
+      \texttt{monitor\_ioinc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{monitor} ``inclusively''  \\\hline
+      \multicolumn{4}{|c|}{\ }  \\
+      \multicolumn{4}{|c|}{Diagnostics namelist file: 
+        ``\textbf{data.diagnostics}''}  \\\hline
+      \texttt{diag\_mnc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{diagnostics} w/MNC  \\
+      \texttt{diag\_ioinc}  &  L  & \texttt{.FALSE.}  &  
+      write \texttt{diagnostics} ``inclusively''  \\\hline
+    \end{tabular}
+  }
+\end{center}
 
-\subsection{Package Reference}
+By default, turning on MNC for a particular output stream will result
+in turning off all the corresponding (usually, default) MDSIO or
+STDOUT output mechanisms.  In other words, output defaults to being an
+exclusive selection.  To enable multiple kinds of simultaneous output,
+flags of the form \texttt{NAME\_ioinc} can be used where \texttt{NAME}
+corresponds to the various MNC output flags.  When a
+\texttt{NAME\_ioinc} flag is set to \texttt{.TRUE.}, then multiple
+forms of output are allowed for the \texttt{NAME} output mechanism.
+The intent of this design is that typical users will only want one
+kind of output while people debugging the code (particularly the I/O
+routines) may want simultaneous types of output.
+
+This ``inclusive'' versus ``exclusive'' design is easily applied in
+cases where three or more kinds of output may be generated.  Thus, it
+can be readily extended to additional new output types (eg. HDF5).
 
+Input types are always exclusive.