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

Diff of /manual/s_phys_pkgs/mnc.tex

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

revision 1.11 by edhill, Wed Sep 22 15:11:32 2004 UTC revision 1.12 by edhill, Tue Oct 12 18:16:03 2004 UTC
# Line 3  Line 3 
3    
4  \section{NetCDF I/O Integration: MNC}  \section{NetCDF I/O Integration: MNC}
5  \label{sec:pkg:mnc}  \label{sec:pkg:mnc}
6    \begin{rawhtml}
7    <!-- CMIREDIR:package_mnc: -->
8    \end{rawhtml}
9    
10  The \texttt{mnc} package is a set of convenience routines written to  The \texttt{mnc} package is a set of convenience routines written to
11  expedite the process of creating, appending, and reading NetCDF files.  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
21  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
22    
23    
24  \subsection{Introduction}  \subsection{Using MNC}
25    
26    \subsubsection{MNC Configuration and Inputs}
27    
28    As with all MITgcm packages, MNC can be turned on/off at compile time
29    using the \texttt{packages.conf} file or the genmake2
30    \texttt{-enable=mnc} or \texttt{-disable=mnc} switches.
31    
32    For run-time configuration, most of the MNC--related model parameters
33    are contained within a Fortran namelist file called \texttt{data.mnc}.
34    If this file does not exist, then the MNC package will interpret that
35    as an indication that it is not to be used.  If the \texttt{data.mnc}
36    file does exist, then it may contain the following parameters:
37    
38    \begin{center}
39      {\footnotesize
40        \begin{tabular}[htb]{|l|c|l|l|}\hline
41          \textbf{Name}  &  \textbf{T}  &  
42          \textbf{Default}  &  \textbf{Description}  \\\hline
43          &  &  &  \\
44          \texttt{useMNC}  &  L  & \texttt{.FALSE.}  &  
45          \textbf{overall MNC ON/OFF switch}  \\
46          \texttt{mnc\_echo\_gvtypes}  &  L  & \texttt{.FALSE.}  &  
47          echo pre-defined ``types'' (debugging)   \\
48          \texttt{mnc\_use\_outdir}  &  L  & \texttt{.FALSE.}  &  
49          create a directory for output  \\
50          \texttt{mnc\_outdir\_str}  &  S  & \texttt{'mnc\_'}  &  
51          output directory name \\
52          \texttt{mnc\_outdir\_date}  &  L  & \texttt{.FALSE.}  &  
53          embed date in the output dir name  \\
54          \texttt{pickup\_write\_mnc}  &  L  & \texttt{.FALSE.}  &  
55          use MNC to write (create) pickup files  \\
56          \texttt{pickup\_read\_mnc}  &  L  & \texttt{.FALSE.}  &  
57          use MNC to read pickup files  \\
58          \texttt{mnc\_use\_indir}  &  L  & \texttt{.FALSE.}  &  
59          use a directory (path) for input  \\
60          \texttt{mnc\_indir\_str}  &  S  & \texttt{''}  &  
61          input directory (or path) name  \\
62          \texttt{snapshot\_mnc}  &  L  & \texttt{.FALSE.}  &  
63          write \texttt{snapshot} (instantaneous) w/MNC  \\
64          \texttt{monitor\_mnc}  &  L  & \texttt{.FALSE.}  &  
65          write \texttt{monitor} w/MNC  \\
66          \texttt{timeave\_mnc}  &  L  & \texttt{.FALSE.}  &  
67          write \texttt{timeave} w/MNC  \\
68          \texttt{autodiff\_mnc}  &  L  & \texttt{.FALSE.}  &  
69          write \texttt{autodiff} w/MNC  \\\hline
70        \end{tabular}
71      }
72    \end{center}
73    
74    Additional MNC--related parameters are contained within the main
75    \texttt{data} namelist file and in some of the namelist files for
76    individual packages.  These options are:
77    \begin{center}
78      {\footnotesize
79        \begin{tabular}[htb]{|l|c|l|l|}\hline
80          \textbf{Name}  &  \textbf{T}  &  
81          \textbf{Default}  &  \textbf{Description}  \\\hline
82          \multicolumn{4}{|c|}{\ }  \\
83          \multicolumn{4}{|c|}{Main namelist file:
84            ``\textbf{data}''}  \\\hline
85          \texttt{snapshot\_ioinc}  &  L  & \texttt{.FALSE.}  &  
86          write \texttt{snapshot} ``inclusively''  \\
87          \texttt{timeave\_ioinc}  &  L  & \texttt{.FALSE.}  &  
88          write \texttt{timeave} ``inclusively''  \\
89          \texttt{monitor\_ioinc}  &  L  & \texttt{.FALSE.}  &  
90          write \texttt{monitor} ``inclusively''  \\
91          \texttt{the\_run\_name}  &  C  & ``name...''  &  
92          name is included in all MNC output  \\\hline
93          \multicolumn{4}{|c|}{\ }  \\
94          \multicolumn{4}{|c|}{Diagnostics namelist file:
95            ``\textbf{data.diagnostics}''}  \\\hline
96          \texttt{diag\_mnc}  &  L  & \texttt{.FALSE.}  &  
97          write \texttt{diagnostics} w/MNC  \\
98          \texttt{diag\_ioinc}  &  L  & \texttt{.FALSE.}  &  
99          write \texttt{diagnostics} ``inclusively''  \\\hline
100        \end{tabular}
101      }
102    \end{center}
103    
104    By default, turning on MNC for a particular output type will result in
105    turning off all the corresponding (usually, default) MDSIO or STDOUT
106    output mechanisms.  In other words, output defaults to being an
107    exclusive selection.  To enable multiple kinds of simultaneous output,
108    flags of the form \texttt{NAME\_ioinc} have been created where
109    \texttt{NAME} corresponds to the various MNC output flags.  When a
110    \texttt{NAME\_ioinc} flag is set to \texttt{.TRUE.}, then multiple
111    simultaneous forms of output are allowed for the \texttt{NAME} output
112    mechanism.  The intent of this design is that typical users will only
113    want one kind of output while people debugging the code (particularly
114    the I/O routines) may want simultaneous types of output.
115    
116    This ``inclusive'' versus ``exclusive'' design is easily applied in
117    cases where three or more kinds of output may be generated.  Thus, it
118    can be readily extended to additional new output types (eg. HDF5).
119    
120    Input types are always exclusive.
121    
122    \subsubsection{MNC Output}
123    
124    While NetCDF files are supposed to be ``self-describing'', it is
125    helpful to note the following:
126    
127    \begin{itemize}
128    \item The constraints placed upon the ``unlimited'' (or ``record'')
129      dimension inherent with NetCDF v3.x make it very inefficient to put
130      variables written at potentially different intervals within the same
131      file.  For this reason, MNC output is split into a few file ``base
132      names'' which try to reflect the nature of their content.
133      
134    \item All MNC output is currently done in a ``tile-per-file'' fashion
135      since most NetCDF v3.x implementions cannot write safely within MPI
136      or multi-threaded environments.  This tiling is done in a global
137      fashion and the tile numbers are appended to the base names
138      described above.  Some scripts to ``assemble'' output are available
139      (\texttt{MITgcm/utils/matlab}).  More general manipulations can be
140      accomplished with the
141      \begin{rawhtml}
142        <A href="http://nco.sourceforge.net">
143      \end{rawhtml}
144    \begin{verbatim}
145    NetCDF Operators (or ``NCO'') at http://nco.sourceforge.net
146    \end{verbatim}
147      \begin{rawhtml} </A> \end{rawhtml}
148      which is a very powerful and convenient set of tools for working
149      with all NetCDF files.
150      
151    \item MNC does not (yet) provide a mechanism for reading information
152      from a single ``global'' file as can be done with the MDSIO
153      package.
154    
155    \end{itemize}
156    
157    
158    \subsection{MNC Internals}
159    
160  The \texttt{mnc} package is a two-level convenience library (or  The \texttt{mnc} package is a two-level convenience library (or
161  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
# Line 66  The two levels of the \texttt{mnc} packa Line 203  The two levels of the \texttt{mnc} packa
203  \end{description}  \end{description}
204    
205    
206  \subsection{Using MNC}  \subsubsection{MNC Grid--Types and Variable--Types}
   
 \subsubsection{Grid--Types and Variable--Types}  
207    
208  As a convenience for users, the MNC package includes numerous routines  As a convenience for users, the MNC package includes numerous routines
209  to aid in the writing of data to NetCDF format.  Probably the biggest  to aid in the writing of data to NetCDF format.  Probably the biggest
# Line 127  and is used by the \texttt{mnc\_cw\_*\_[ Line 262  and is used by the \texttt{mnc\_cw\_*\_[
262  and writing variables.  and writing variables.
263    
264    
265  \subsubsection{An Example}  \subsubsection{Using MNC: Examples}
266    
267  Writing variables to NetCDF files can be accomplished in as few as two  Writing variables to NetCDF files can be accomplished in as few as two
268  function calls.  The first function call defines a variable type,  function calls.  The first function call defines a variable type,
# Line 183  C       Write dynvars using the MNC pack Line 318  C       Write dynvars using the MNC pack
318  \end{verbatim}  \end{verbatim}
319  }  }
320    
321    While it is easiest to write variables within typical 2D and 3D fields
322    where all data is known at a given time, it is also possible to write
323    fields where only a portion (\textit{eg.} a ``slab'' or ``slice'') is
324    known at a given instant.  An example is provided within
325    \filelink{pkg/mom\_vecinv/mom\_vecinv.F}{pkg-mom_vecinv-mom_vecinv.F}
326    where an offset vector is used: {\footnotesize
327    \begin{verbatim}
328           IF (useMNC .AND. snapshot_mnc) THEN
329             CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fV', uCf,
330       &          offsets, myThid)
331             CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fU', vCf,
332       &          offsets, myThid)
333           ENDIF
334    \end{verbatim}
335    }
336    to write a 3D field one depth slice at a time.
337    
338  \subsubsection{Parameters}  Each element in the offset vector corresponds (in order) to the
339    dimensions of the ``full'' (or virtual) array and specifies which are
340  Most of the MNC--related parameters are contained within a Fortran  known at the time of the call.  A zero within the offset array means
341  namelist file called \texttt{data.mnc}.  If this file does not exist,  that all values along that dimension are available while a positive
342  then the MNC package will interpret that as an indication that it is  integer means that only values along that index of the dimension are
343  not to be used.  If the \texttt{data.mnc} file does exist, then it may  available.  In all cases, the matrix passed is assumed to start (that
344  contain the following parameters:  is, have an in-memory structure) coinciding with the start of the
345    specified slice.  Thus, using this offset array mechanism, a slice
346  \begin{center}  can be written along any single dimension or combinations of
347    {\footnotesize  dimensions.
     \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}  
   
 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).  
348    
 Input types are always exclusive.  
Legend:
Removed from v.1.11  
changed lines
  Added in v.1.12
  ViewVC Help
Powered by ViewVC 1.1.22