/[MITgcm]/manual/s_phys_pkgs/mnc.tex

Diff of /manual/s_phys_pkgs/mnc.tex

Parent Directory | Revision Log | View Revision Graph Revision Graph | View Patch Patch

-revision 1.8 by edhill,
Sat Apr  3 23:05:05 2004 UTC
+revision 1.13 by edhill,
Tue Oct 12 21:44:59 2004 UTC
 Line 3
  \section{NetCDF I/O Integration: MNC}
  \label{sec:pkg:mnc}
+ \begin{rawhtml}
+ <!-- CMIREDIR:package_mnc: -->
+ \end{rawhtml}
  The \texttt{mnc} package is a set of convenience routines written to
  expedite the process of creating, appending, and reading NetCDF files.
-Line 18 
 http://www.unidata.ucar.edu/packages/net
+Line 21 
 http://www.unidata.ucar.edu/packages/net
  \begin{rawhtml} </A> \end{rawhtml}
- \subsection{Introduction}
+ \subsection{Using MNC}
+ \subsubsection{MNC Configuration and Inputs}
+ As with all MITgcm packages, MNC can be turned on/off at compile time
+ using the \texttt{packages.conf} file or the genmake2
+ \texttt{-enable=mnc} or \texttt{-disable=mnc} switches.
+ For run-time configuration, most of the MNC--related model 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  \\
+       \texttt{autodiff\_mnc}  &  L  & \texttt{.FALSE.}  &
+       write \texttt{autodiff} 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''  \\
+       \texttt{the\_run\_name}  &  C  & ``name...''  &
+       name is included in all MNC output  \\\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}
+ By default, turning on MNC for a particular output type 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} have been created where
+ \texttt{NAME} corresponds to the various MNC output flags.  When a
+ \texttt{NAME\_ioinc} flag is set to \texttt{.TRUE.}, then multiple
+ simultaneous 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.
+ \subsubsection{MNC Output}
+ While NetCDF files are supposed to be ``self-describing'', it is
+ helpful to note the following:
+ \begin{itemize}
+ \item The constraints placed upon the ``unlimited'' (or ``record'')
+   dimension inherent with NetCDF v3.x make it very inefficient to put
+   variables written at potentially different intervals within the same
+   file.  For this reason, MNC output is split into a few file ``base
+   names'' which try to reflect the nature of their content.
+ \item All MNC output is currently done in a ``tile-per-file'' fashion
+   since most NetCDF v3.x implementions cannot write safely within MPI
+   or multi-threaded environments.  This tiling is done in a global
+   fashion and the tile numbers are appended to the base names
+   described above.  Some scripts to ``assemble'' output are available
+   (\texttt{MITgcm/utils/matlab}).  More general manipulations can be
+   accomplished with the
+   \begin{rawhtml}
+     <A href="http://nco.sourceforge.net">
+   \end{rawhtml}
+ \begin{verbatim}
+ NetCDF Operators (or ``NCO'') at http://nco.sourceforge.net
+ \end{verbatim}
+   \begin{rawhtml} </A> \end{rawhtml}
+   which is a very powerful and convenient set of tools for working
+   with all NetCDF files.
+ \item On many systems, NetCDF has practical file size limits on the
+   order of 2--4GB (the maximium memory addressable with 32bit
+   pointers) due to a lack of operating system, compiler, and/or
+   library support.  In cases where this limit is reached, it is
+   generally a good idea to reduce write frequencies or restart from
+   pickups.
+ \item MNC does not (yet) provide a mechanism for reading information
+   from a single ``global'' file as can be done with the MDSIO
+   package.  This is in progress.
+ \end{itemize}
+ \subsection{MNC Internals}
  The \texttt{mnc} package is a two-level convenience library (or
  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
-Line 66 
 The two levels of the \texttt{mnc} packa
+Line 210 
 The two levels of the \texttt{mnc} packa
  \end{description}
- \subsection{Using MNC}
+ \subsubsection{MNC Grid--Types and Variable--Types}
- \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
-Line 117 
 file
+Line 259 
 file
  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
-Line 127 
 and is used by the \texttt{mnc\_cw\_*\_[
+Line 269 
 and is used by the \texttt{mnc\_cw\_*\_[
  and writing variables.
- \subsubsection{An Example}
+ \subsubsection{Using MNC: Examples}
  Writing variables to NetCDF files can be accomplished in as few as two
  function calls.  The first function call defines a variable type,
-Line 138 
 necessary, the current time level within
+Line 280 
 necessary, the current time level within
  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:
+ where these function calls:
  {\footnotesize
  \begin{verbatim}
  C     Create MNC definitions for DYNVARS.h variables
-Line 164 
 C     Create MNC definitions for DYNVARS
+Line 306 
 C     Create MNC definitions for DYNVARS
       &     'coordinates','XC YC RC iter', myThid)
  \end{verbatim}
  }
- {\noindent initialize two \texttt{VNAME}s and add one NetCDF
+ {\noindent initialize four \texttt{VNAME}s and add one or more NetCDF
-   attribute to each.}
+   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 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_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)
-Line 184 
 C       Write dynvars using the MNC pack
+Line 325 
 C       Write dynvars using the MNC pack
  \end{verbatim}
  }
- %\subsection{Key subroutines, parameters and files}
+ While it is easiest to write variables within typical 2D and 3D fields
+ where all data is known at a given time, it is also possible to write
+ fields where only a portion (\textit{eg.} a ``slab'' or ``slice'') is
+ known at a given instant.  An example is provided within
+ \filelink{pkg/mom\_vecinv/mom\_vecinv.F}{pkg-mom_vecinv-mom_vecinv.F}
+ where an offset vector is used: {\footnotesize
+ \begin{verbatim}
+        IF (useMNC .AND. snapshot_mnc) THEN
+          CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fV', uCf,
+    &          offsets, myThid)
+          CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fU', vCf,
+    &          offsets, myThid)
+        ENDIF
+ \end{verbatim}
+ }
+ to write a 3D field one depth slice at a time.
- \subsection{Package Reference}
+ Each element in the offset vector corresponds (in order) to the
+ dimensions of the ``full'' (or virtual) array and specifies which are
+ known at the time of the call.  A zero within the offset array means
+ that all values along that dimension are available while a positive
+ integer means that only values along that index of the dimension are
+ available.  In all cases, the matrix passed is assumed to start (that
+ is, have an in-memory structure) coinciding with the start of the
+ specified slice.  Thus, using this offset array mechanism, a slice
+ can be written along any single dimension or combinations of
+ dimensions.

 Legend:



Removed from v.1.8
 


changed lines


 
Added in v.1.13
 Legend:



Removed from v.1.8
 


changed lines


 
Added in v.1.13
-Removed from v.1.8
+Added in v.1.13

	ViewVC Help
Powered by ViewVC 1.1.22