/[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.5 by edhill, Thu Feb 12 03:35:05 2004 UTC revision 1.14 by edhill, Sat Dec 11 22:03:32 2004 UTC
# Line 1  Line 1 
1  % $Header$  % $Header$
2  % $Name$  % $Name$
3    
4  \section{NetCDF I/O Integration}  \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}
27    
28    As with all MITgcm packages, MNC can be turned on or off at compile time
29    using the \texttt{packages.conf} file or the \texttt{genmake2}
30    \texttt{-enable=mnc} or \texttt{-disable=mnc} switches.
31    
32    While MNC is likely to work ``as is'', there are a few compile--time
33    constants that may need to be increased for simulations that employ
34    large numbers of tiles within each process.  Note that the important
35    quantity is the maximum number of tiles \textbf{per process}.  Since
36    MPI configurations tend to distribute large numbers of tiles over
37    relatively large numbers of MPI processes, these constants will rarely
38    need to be increased.
39    
40    If MNC runs out of space within its ``lookup'' tables during a
41    simulation, then it will provide an error message along with a
42    recommendation of which parameter to increase.  The parameters are all
43    located within \filelink{pkg/mnc/mnc\_common.h}{pkg-mnc-mnc_common.h}
44    and the ones that may need to be increased are:
45    
46    \begin{center}
47      {\footnotesize
48        \begin{tabular}[htb]{|l|r|l|}\hline
49          \textbf{Name}  &  
50          \textbf{Default}  &  \textbf{Description}  \\\hline
51          &  &  \\
52          \texttt{MNC\_MAX\_ID}  &  1000  &
53          \textbf{IDs for various low-level entities}  \\
54          \texttt{MNC\_MAX\_INFO}  &   400  &
55          \textbf{IDs (mostly for object sizes)}  \\
56          \texttt{MNC\_CW\_MAX\_I}  &  150  &
57          \textbf{IDs for the ``wrapper'' layer}  \\\hline
58        \end{tabular}
59      }
60    \end{center}
61    
62    In those rare cases where MNC ``out-of-memory'' error messages are
63    encountered, it is a good idea to increase the too-small parameter by
64    a factor of \textbf{2--10} in order to avoid wasting time on an
65    iterative compile--test sequence.
66    
67    
68    \subsubsection{MNC Inputs}
69    
70    For run-time configuration, most of the MNC--related model parameters
71    are contained within a Fortran namelist file called \texttt{data.mnc}.
72    If this file does not exist, then the MNC package will interpret that
73    as an indication that it is not to be used.  If the \texttt{data.mnc}
74    file does exist, then it may contain the following parameters:
75    
76    \begin{center}
77      {\footnotesize
78        \begin{tabular}[htb]{|l|c|l|l|}\hline
79          \textbf{Name}  &  \textbf{T}  &  
80          \textbf{Default}  &  \textbf{Description}  \\\hline
81          &  &  &  \\
82          \texttt{useMNC}  &  L  & \texttt{.FALSE.}  &  
83          \textbf{overall MNC ON/OFF switch}  \\
84          \texttt{mnc\_echo\_gvtypes}  &  L  & \texttt{.FALSE.}  &  
85          echo pre-defined ``types'' (debugging)   \\
86          \texttt{mnc\_use\_outdir}  &  L  & \texttt{.FALSE.}  &  
87          create a directory for output  \\
88          \texttt{mnc\_outdir\_str}  &  S  & \texttt{'mnc\_'}  &  
89          output directory name \\
90          \texttt{mnc\_outdir\_date}  &  L  & \texttt{.FALSE.}  &  
91          embed date in the output dir name  \\
92          \texttt{pickup\_write\_mnc}  &  L  & \texttt{.FALSE.}  &  
93          use MNC to write (create) pickup files  \\
94          \texttt{pickup\_read\_mnc}  &  L  & \texttt{.FALSE.}  &  
95          use MNC to read pickup files  \\
96          \texttt{mnc\_use\_indir}  &  L  & \texttt{.FALSE.}  &  
97          use a directory (path) for input  \\
98          \texttt{mnc\_indir\_str}  &  S  & \texttt{''}  &  
99          input directory (or path) name  \\
100          \texttt{snapshot\_mnc}  &  L  & \texttt{.FALSE.}  &  
101          write \texttt{snapshot} (instantaneous) w/MNC  \\
102          \texttt{monitor\_mnc}  &  L  & \texttt{.FALSE.}  &  
103          write \texttt{monitor} w/MNC  \\
104          \texttt{timeave\_mnc}  &  L  & \texttt{.FALSE.}  &  
105          write \texttt{timeave} w/MNC  \\
106          \texttt{autodiff\_mnc}  &  L  & \texttt{.FALSE.}  &  
107          write \texttt{autodiff} w/MNC  \\\hline
108        \end{tabular}
109      }
110    \end{center}
111    
112    Additional MNC--related parameters are contained within the main
113    \texttt{data} namelist file and in some of the namelist files for
114    individual packages.  These options are:
115    \begin{center}
116      {\footnotesize
117        \begin{tabular}[htb]{|l|c|l|l|}\hline
118          \textbf{Name}  &  \textbf{T}  &  
119          \textbf{Default}  &  \textbf{Description}  \\\hline
120          \multicolumn{4}{|c|}{\ }  \\
121          \multicolumn{4}{|c|}{Main namelist file:
122            ``\textbf{data}''}  \\\hline
123          \texttt{snapshot\_ioinc}  &  L  & \texttt{.FALSE.}  &  
124          write \texttt{snapshot} ``inclusively''  \\
125          \texttt{timeave\_ioinc}  &  L  & \texttt{.FALSE.}  &  
126          write \texttt{timeave} ``inclusively''  \\
127          \texttt{monitor\_ioinc}  &  L  & \texttt{.FALSE.}  &  
128          write \texttt{monitor} ``inclusively''  \\
129          \texttt{the\_run\_name}  &  C  & ``name...''  &  
130          name is included in all MNC output  \\\hline
131          \multicolumn{4}{|c|}{\ }  \\
132          \multicolumn{4}{|c|}{Diagnostics namelist file:
133            ``\textbf{data.diagnostics}''}  \\\hline
134          \texttt{diag\_mnc}  &  L  & \texttt{.FALSE.}  &  
135          write \texttt{diagnostics} w/MNC  \\
136          \texttt{diag\_ioinc}  &  L  & \texttt{.FALSE.}  &  
137          write \texttt{diagnostics} ``inclusively''  \\\hline
138        \end{tabular}
139      }
140    \end{center}
141    
142    By default, turning on MNC for a particular output type will result in
143    turning off all the corresponding (usually, default) MDSIO or STDOUT
144    output mechanisms.  In other words, output defaults to being an
145    exclusive selection.  To enable multiple kinds of simultaneous output,
146    flags of the form \texttt{NAME\_ioinc} have been created where
147    \texttt{NAME} corresponds to the various MNC output flags.  When a
148    \texttt{NAME\_ioinc} flag is set to \texttt{.TRUE.}, then multiple
149    simultaneous forms of output are allowed for the \texttt{NAME} output
150    mechanism.  The intent of this design is that typical users will only
151    want one kind of output while people debugging the code (particularly
152    the I/O routines) may want simultaneous types of output.
153    
154    This ``inclusive'' versus ``exclusive'' design is easily applied in
155    cases where three or more kinds of output may be generated.  Thus, it
156    can be readily extended to additional new output types (eg. HDF5).
157    
158    Input types are always exclusive.
159    
160    \subsubsection{MNC Output}
161    
162    While NetCDF files are supposed to be ``self-describing'', it is
163    helpful to note the following:
164    
165    \begin{itemize}
166    \item The constraints placed upon the ``unlimited'' (or ``record'')
167      dimension inherent with NetCDF v3.x make it very inefficient to put
168      variables written at potentially different intervals within the same
169      file.  For this reason, MNC output is split into a few file ``base
170      names'' which try to reflect the nature of their content.
171      
172    \item All MNC output is currently done in a ``tile-per-file'' fashion
173      since most NetCDF v3.x implementions cannot write safely within MPI
174      or multi-threaded environments.  This tiling is done in a global
175      fashion and the tile numbers are appended to the base names
176      described above.  Some scripts to ``assemble'' output are available
177      (\texttt{MITgcm/utils/matlab}).  More general manipulations can be
178      accomplished with the
179      \begin{rawhtml}
180        <A href="http://nco.sourceforge.net">
181      \end{rawhtml}
182    \begin{verbatim}
183    NetCDF Operators (or ``NCO'') at http://nco.sourceforge.net
184    \end{verbatim}
185      \begin{rawhtml} </A> \end{rawhtml}
186      which is a very powerful and convenient set of tools for working
187      with all NetCDF files.
188      
189    \item On many systems, NetCDF has practical file size limits on the
190      order of 2--4GB (the maximium memory addressable with 32bit
191      pointers) due to a lack of operating system, compiler, and/or
192      library support.  In cases where this limit is reached, it is
193      generally a good idea to reduce write frequencies or restart from
194      pickups.
195      
196    \item MNC does not (yet) provide a mechanism for reading information
197      from a single ``global'' file as can be done with the MDSIO
198      package.  This is in progress.
199    
200    \end{itemize}
201    
202    
203    \subsection{MNC Internals}
204    
205  The \texttt{mnc} package is a two-level convenience library (or  The \texttt{mnc} package is a two-level convenience library (or
206  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
207  streamline the user interface to NetCDF by maintaining internal  streamline the user interface to NetCDF by maintaining internal
208  relations (``look-up tables'') keyed with strings (or ``names'') and  relations (look-up tables) keyed with strings (or names) and entities
209  entities such as NetCDF files, variables, and attributes.  such as NetCDF files, variables, and attributes.
210    
211  The two levels of the \texttt{mnc} package are:  The two levels of the \texttt{mnc} package are:
212  \begin{description}  \begin{description}
# Line 34  The two levels of the \texttt{mnc} packa Line 216  The two levels of the \texttt{mnc} packa
216    The upper level contains information about two kinds of    The upper level contains information about two kinds of
217    associations:    associations:
218    \begin{description}    \begin{description}
219    \item[Grid type] is lookup table indexed with a grid type name.    \item[grid type] is lookup table indexed with a grid type name.
220      Each grid type name is associated with a number of dimensions, the      Each grid type name is associated with a number of dimensions, the
221      dimension sizes (one of which may be unlimited), and starting and      dimension sizes (one of which may be unlimited), and starting and
222      ending index arrays.  The intent is to store all the necessary      ending index arrays.  The intent is to store all the necessary
# Line 44  The two levels of the \texttt{mnc} packa Line 226  The two levels of the \texttt{mnc} packa
226      shown in Figures \ref{fig:communication_primitives} and      shown in Figures \ref{fig:communication_primitives} and
227      \ref{fig:tiling-strategy}).      \ref{fig:tiling-strategy}).
228        
229    \item[Variable type] is a lookup table indexed by a variable type    \item[variable type] is a lookup table indexed by a variable type
230      name.  For each name, the table contains a reference to a grid      name.  For each name, the table contains a reference to a grid
231      type for the variable and the names and values of various      type for the variable and the names and values of various
232      attributes.      attributes.
# Line 66  The two levels of the \texttt{mnc} packa Line 248  The two levels of the \texttt{mnc} packa
248  \end{description}  \end{description}
249    
250    
251  \subsection{Using MNC}  \subsubsection{MNC Grid--Types and Variable--Types}
   
 \subsubsection{``Grid--Types'' and ``Variable--Types''}  
252    
253  As a convenience for users, the MNC package includes numerous routines  As a convenience for users, the MNC package includes numerous routines
254  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 94  string follows the format Line 274  string follows the format
274  \begin{center}  \begin{center}
275    \texttt{H0\_H1\_H2\_\_V\_\_T}    \texttt{H0\_H1\_H2\_\_V\_\_T}
276  \end{center}  \end{center}
277  where the terms \textit{H0,H1,H2,V,T} can be almost any combination of  where the terms \textit{H0}, \textit{H1}, \textit{H2}, \textit{V},
278  the following:  \textit{T} can be almost any combination of the following:
279  \begin{center}  \begin{center}
280    \begin{tabular}[h]{|ccc|c|c|}\hline    \begin{tabular}[h]{|ccc|c|c|}\hline
281      \multicolumn{3}{|c|}{Horizontal} & Vertical &  \\      \multicolumn{3}{|c|}{Horizontal} & Vertical & Time \\
282      Location & Direction & Halo & Location & Time  \\\hline      \textbf{H0}: location & \textbf{H1}: dimensions & \textbf{H2}: halo
283      H0  &  H1  &  H2  &  V  &  T  \\\hline            & \textbf{V}: location & \textbf{T}: level  \\\hline
284      \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\      \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\
285      U  &  x  &  Hy  &  i  &  t  \\      U  &  x  &  Hy  &  i  &  t  \\
286      V  &  y  &      &  c  &     \\      V  &  y  &      &  c  &     \\
# Line 114  file Line 294  file
294    \texttt{pkg/mnc/pre-defined\_grids.txt}.    \texttt{pkg/mnc/pre-defined\_grids.txt}.
295  \end{center}  \end{center}
296    
297    The variable type is an association between a variable type name and the
298    following items:
299    \begin{center}
300      \begin{tabular}[h]{|l|l|}\hline
301        \textbf{Item}  & \textbf{Purpose}  \\\hline
302        grid type  &  defines the in-memory arrangement  \\
303        \texttt{bi,bj} dimensions  &  tiling indices, if present  \\\hline
304      \end{tabular}
305    \end{center}
306    and is used by the \texttt{mnc\_cw\_*\_[R|W]} subroutines for reading
307    and writing variables.
308    
309    
310  \subsubsection{An Example}  \subsubsection{Using MNC: Examples}
311    
312  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
313  function calls.  The first function call defines a variable type,  function calls.  The first function call defines a variable type,
314  associates it with a name (character string), and provides additional  associates it with a name (character string), and provides additional
315  information about the indicies for \texttt{bi,bj} dimensions.  The  information about the indicies for the tile (\texttt{bi},\texttt{bj})
316  second function call will write variable at, if necessary, the  dimensions.  The second function call will write the data at, if
317  current time level within the model.  necessary, the current time level within the model.
318    
319  Examples of the initialization calls can be found in the file  Examples of the initialization calls can be found in the file
320  \begin{center}  \filelink{model/src/ini\_mnc\_io.F}{model-src-ini_mnc_io.F}
321    \filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F}  where these function calls:
322  \end{center}  {\footnotesize
 where these four function calls: {\footnotesize  
323  \begin{verbatim}  \begin{verbatim}
324    C     Create MNC definitions for DYNVARS.h variables  C     Create MNC definitions for DYNVARS.h variables
325          CALL MNC_CW_ADD_VNAME(myThid, 'iter', '-_-_--__-__t', 0,0)        CALL MNC_CW_ADD_VNAME('iter', '-_-_--__-__t', 0,0, myThid)
326          CALL MNC_CW_ADD_VATTR_TEXT(myThid,'iter',1,        CALL MNC_CW_ADD_VATTR_TEXT('iter',1,
327         &     'long_name','iteration_count')       &     'long_name','iteration_count', myThid)
328          CALL MNC_CW_ADD_VNAME(myThid, 'U', 'U_xy_Hn__C__t', 4,5)  
329          CALL MNC_CW_ADD_VATTR_TEXT(myThid,'U',1,'units','m/s')        CALL MNC_CW_ADD_VNAME('model_time', '-_-_--__-__t', 0,0, myThid)
330  \end{verbatim} }        CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,
331  {\noindent initialize two \texttt{VNAME}s and add one attribute to each.}       &     'long_name','Model Time', myThid)
332          CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,'units','s', myThid)
333    
334          CALL MNC_CW_ADD_VNAME('U', 'U_xy_Hn__C__t', 4,5, myThid)
335          CALL MNC_CW_ADD_VATTR_TEXT('U',1,'units','m/s', myThid)
336          CALL MNC_CW_ADD_VATTR_TEXT('U',1,
337         &     'coordinates','XU YU RC iter', myThid)
338    
339          CALL MNC_CW_ADD_VNAME('T', 'Cen_xy_Hn__C__t', 4,5, myThid)
340          CALL MNC_CW_ADD_VATTR_TEXT('T',1,'units','degC', myThid)
341          CALL MNC_CW_ADD_VATTR_TEXT('T',1,'long_name',
342         &     'potential_temperature', myThid)
343          CALL MNC_CW_ADD_VATTR_TEXT('T',1,
344         &     'coordinates','XC YC RC iter', myThid)
345    \end{verbatim}
346    }
347    {\noindent initialize four \texttt{VNAME}s and add one or more NetCDF
348      attributes to each.}
349            
350  The two variables are subsequently written at specific time steps  The four variables defined above are subsequently written at specific
351  within  time steps within
352  \begin{center}  \filelink{model/src/write\_state.F}{model-src-write_state.F}
353    \filelink{model/src/write\_state.F}{model-src-write_state.F}  using the function calls:
354  \end{center}  {\footnotesize
 using the function calls: {\footnotesize  
355  \begin{verbatim}  \begin{verbatim}
356    C     Write the DYNVARS.h variables using the MNC package  C       Write dynvars using the MNC package
357          mnc_iter = myIter          CALL MNC_CW_SET_UDIM('state', -1, myThid)
358          CALL MNC_CW_RL_W_R(myThid,'state',0,0,'iter',-1,mnc_iter)          CALL MNC_CW_I_W('I','state',0,0,'iter', myIter, myThid)
359          CALL MNC_CW_RL_W_D(myThid,'state',0,0,'U', 0, uVel)          CALL MNC_CW_SET_UDIM('state', 0, myThid)
360  \end{verbatim} }          CALL MNC_CW_RL_W('D','state',0,0,'model_time',myTime, myThid)
361            CALL MNC_CW_RL_W('D','state',0,0,'U', uVel, myThid)
362            CALL MNC_CW_RL_W('D','state',0,0,'T', theta, myThid)
363  \subsection{Key subroutines, parameters and files}  \end{verbatim}
364    }
 All of the variables used to implement the lookup tables are described  
 in \filelink{model/src/write\_state.F}{model-src-write_state.F}  
   
365    
366    While it is easiest to write variables within typical 2D and 3D fields
367    where all data is known at a given time, it is also possible to write
368    fields where only a portion (\textit{eg.} a ``slab'' or ``slice'') is
369    known at a given instant.  An example is provided within
370    \filelink{pkg/mom\_vecinv/mom\_vecinv.F}{pkg-mom_vecinv-mom_vecinv.F}
371    where an offset vector is used: {\footnotesize
372    \begin{verbatim}
373           IF (useMNC .AND. snapshot_mnc) THEN
374             CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fV', uCf,
375       &          offsets, myThid)
376             CALL MNC_CW_RL_W_OFFSET('D','mom_vi',bi,bj, 'fU', vCf,
377       &          offsets, myThid)
378           ENDIF
379    \end{verbatim}
380    }
381    to write a 3D field one depth slice at a time.
382    
383  \subsection{Package Reference}  Each element in the offset vector corresponds (in order) to the
384    dimensions of the ``full'' (or virtual) array and specifies which are
385    known at the time of the call.  A zero within the offset array means
386    that all values along that dimension are available while a positive
387    integer means that only values along that index of the dimension are
388    available.  In all cases, the matrix passed is assumed to start (that
389    is, have an in-memory structure) coinciding with the start of the
390    specified slice.  Thus, using this offset array mechanism, a slice
391    can be written along any single dimension or combinations of
392    dimensions.
393    
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.14
  ViewVC Help
Powered by ViewVC 1.1.22