/[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.14 by edhill, Sat Dec 11 22:03:32 2004 UTC revision 1.15 by edhill, Mon Jul 18 14:00:00 2005 UTC
# Line 20  http://www.unidata.ucar.edu/packages/net Line 20  http://www.unidata.ucar.edu/packages/net
20  \end{verbatim}  \end{verbatim}
21  \begin{rawhtml} </A> \end{rawhtml}  \begin{rawhtml} </A> \end{rawhtml}
22    
23    Since it is a ``wrapper'' for netCDF, MNC depends upon the Fortran-77
24    interface included with the standard netCDF v3.x library which is
25    often called \texttt{libnetcdf.a}.  Please contact your local systems
26    administrators or the
27    \begin{rawhtml} <A href="mailto:mitgcm-support@mitgcm.org"> \end{rawhtml}
28    MITgcm-support
29    \begin{rawhtml} </A> \end{rawhtml}
30    list for help building and installing netCDF for your particular
31    platform.
32    
33    
34  \subsection{Using MNC}  \subsection{Using MNC}
35    
# Line 67  iterative compile--test sequence. Line 77  iterative compile--test sequence.
77    
78  \subsubsection{MNC Inputs}  \subsubsection{MNC Inputs}
79    
80  For run-time configuration, most of the MNC--related model parameters  Like most MITgcm packages, all of MNC can be turned on/off at runtime
81  are contained within a Fortran namelist file called \texttt{data.mnc}.  using a single flag in \texttt{data.pkg}
 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:  
   
82  \begin{center}  \begin{center}
83    {\footnotesize    {\footnotesize
84      \begin{tabular}[htb]{|l|c|l|l|}\hline      \begin{tabular}[htb]{|l|c|l|l|}\hline
# Line 80  file does exist, then it may contain the Line 86  file does exist, then it may contain the
86        \textbf{Default}  &  \textbf{Description}  \\\hline        \textbf{Default}  &  \textbf{Description}  \\\hline
87        &  &  &  \\        &  &  &  \\
88        \texttt{useMNC}  &  L  & \texttt{.FALSE.}  &          \texttt{useMNC}  &  L  & \texttt{.FALSE.}  &  
89        \textbf{overall MNC ON/OFF switch}  \\        overall MNC ON/OFF switch  \\\hline
90        \texttt{mnc\_echo\_gvtypes}  &  L  & \texttt{.FALSE.}  &        \end{tabular}
91        echo pre-defined ``types'' (debugging)   \\    }
92    \end{center}
93    
94    One important MNC--related flag is present in the main \texttt{data}
95    namelist file in the \texttt{PARM03} section and it is:
96    \begin{center}
97      {\footnotesize
98        \begin{tabular}[htb]{|l|c|l|l|}\hline
99          \textbf{Name}  &  \textbf{T}  &  
100          \textbf{Default}  &  \textbf{Description}  \\\hline
101          &  &  &  \\
102          \texttt{outputTypesInclusive}  &  L  & \texttt{.FALSE.}  &  
103          use all available output ``types''  \\\hline
104        \end{tabular}
105      }
106    \end{center}
107    which specifies that turning on MNC for a particular type of output
108    should not simultaneously turn off the default output method as it
109    normally does.  Usually, this option is only used for debugging
110    purposes since it is inefficient to write output types using both MNC
111    and MDSIO or ASCII output.  This option can also be helpful when
112    transitioning from MDSIO to MNC since the output can be readily
113    compared.
114    
115    For run-time configuration, most of the MNC--related model parameters
116    are contained within a Fortran namelist file called
117    \texttt{data.mnc}.  The availabe parameters currently include:
118    \begin{center}
119      {\footnotesize
120        \begin{tabular}[htb]{|l|c|l|l|}\hline
121          \textbf{Name}  &  \textbf{T}  &  
122          \textbf{Default}  &  \textbf{Description}  \\\hline
123          &  &  &  \\
124        \texttt{mnc\_use\_outdir}  &  L  & \texttt{.FALSE.}  &          \texttt{mnc\_use\_outdir}  &  L  & \texttt{.FALSE.}  &  
125        create a directory for output  \\        create a directory for output  \\
126        \texttt{mnc\_outdir\_str}  &  S  & \texttt{'mnc\_'}  &          \ \ \texttt{mnc\_outdir\_str}  &  S  & \texttt{'mnc\_'}  &  
127        output directory name \\        output directory name \\
128        \texttt{mnc\_outdir\_date}  &  L  & \texttt{.FALSE.}  &          \ \ \texttt{mnc\_outdir\_date}  &  L  & \texttt{.FALSE.}  &  
129        embed date in the output dir name  \\        embed date in the outdir name  \\
130          \ \ \texttt{mnc\_outdir\_num}  &  L  & \texttt{.FALSE.}  &  
131          optional  \\
132        \texttt{pickup\_write\_mnc}  &  L  & \texttt{.FALSE.}  &          \texttt{pickup\_write\_mnc}  &  L  & \texttt{.FALSE.}  &  
133        use MNC to write (create) pickup files  \\        use MNC to write pickup files  \\
134        \texttt{pickup\_read\_mnc}  &  L  & \texttt{.FALSE.}  &          \texttt{pickup\_read\_mnc}  &  L  & \texttt{.FALSE.}  &  
135        use MNC to read pickup files  \\        use MNC to read pickup files  \\
136        \texttt{mnc\_use\_indir}  &  L  & \texttt{.FALSE.}  &          \texttt{mnc\_use\_indir}  &  L  & \texttt{.FALSE.}  &  
137        use a directory (path) for input  \\        use a directory (path) for input  \\
138        \texttt{mnc\_indir\_str}  &  S  & \texttt{''}  &          \ \ \texttt{mnc\_indir\_str}  &  S  & \texttt{''}  &  
139        input directory (or path) name  \\        input directory (or path) name  \\
140        \texttt{snapshot\_mnc}  &  L  & \texttt{.FALSE.}  &          \texttt{snapshot\_mnc}  &  L  & \texttt{.FALSE.}  &  
141        write \texttt{snapshot} (instantaneous) w/MNC  \\        write \texttt{snapshot} output w/MNC  \\
142        \texttt{monitor\_mnc}  &  L  & \texttt{.FALSE.}  &          \texttt{monitor\_mnc}  &  L  & \texttt{.FALSE.}  &  
143        write \texttt{monitor} w/MNC  \\        write \texttt{monitor} output w/MNC  \\
144        \texttt{timeave\_mnc}  &  L  & \texttt{.FALSE.}  &          \texttt{timeave\_mnc}  &  L  & \texttt{.FALSE.}  &  
145        write \texttt{timeave} w/MNC  \\        write \texttt{timeave} output w/MNC  \\
146        \texttt{autodiff\_mnc}  &  L  & \texttt{.FALSE.}  &          \texttt{autodiff\_mnc}  &  L  & \texttt{.FALSE.}  &  
147        write \texttt{autodiff} w/MNC  \\\hline        write \texttt{autodiff} output w/MNC  \\
148          \texttt{mnc\_max\_fsize}  &  R  & 2.1e+09  &  
149          max allowable file size  \\
150          \texttt{readgrid\_mnc}  &  L  &  \texttt{.FALSE.}  &  
151          read grid quantities using MNC  \\
152          \texttt{mnc\_echo\_gvtypes}  &  L  & \texttt{.FALSE.}  &  
153          list pre-defined ``types'' (debug)   \\\hline
154      \end{tabular}      \end{tabular}
155    }    }
156  \end{center}  \end{center}
157    
158  Additional MNC--related parameters are contained within the main  Unlike the older MDSIO method, MNC has the ability to create or use
159  \texttt{data} namelist file and in some of the namelist files for  existing output directories.  If either \texttt{mnc\_outdir\_date} or
160  individual packages.  These options are:  \texttt{mnc\_outdir\_num} is true, then MNC will try to create
161    directories on a \textit{PER PROCESS} basis for its output.  This
162    means that a single directory will be created for a non-MPI run and
163    multiple directories (one per MPI process) will be created for an MPI
164    run.  This approach was chosen since it works safely on both shared
165    global file systems (such as NFS and AFS) and on local
166    (per-compute-node) file systems.  And if both
167    \texttt{mnc\_outdir\_date} and \texttt{mnc\_outdir\_num} are false,
168    then the MNC package will assume that the directory specified in
169    \texttt{mnc\_outdir\_str} already exists and will use it.  This allows
170    the user to create and specify directories outside of the model.
171    
172    For input, MNC can use a single global input directory.  This is a
173    just convenience that allows MNC to gather all of its input files from a
174    path other than the current working directory.  As with MDSIO, the
175    default is to use the current working directory.
176    
177    The flags \texttt{snapshot\_mnc}, \texttt{monitor\_mnc},
178    \texttt{timeave\_mnc}, and \texttt{autodiff\_mnc} allow the user to
179    turn on MNC for particular ``types'' of output.  If a type is
180    selected, then MNC will be used for all output that matches that type.
181    This applies to output from the main model and from all of the
182    optional MITgcm packages.  Mostly, the names used here correspond to
183    the names used for the output frequencies in the main \texttt{data}
184    namelist file.
185    
186    The \texttt{mnc\_max\_fsize} parameter is a convenience added to help
187    users work around common file size limitations.  On many computer
188    systems, either the opterating system, the file system(s), and/or the
189    netCDF libraries are unable to handle files greater than two or four
190    gigabytes in size.  The MNC package is able to work within this
191    limitation by creating new files which grow along the netCDF
192    ``unlimited'' (usually, time) dimension.  The default value for this
193    parameter is just slightly less than 2GB which is safe on virtually
194    all operating systems.  Essentially, this feature is a way to
195    intelligently and automatically split files output along the unlimited
196    dimension.  On systems that support large file sizes, these splits can
197    be readily concatenated (that is, un-done) using tools such as the
198    netCDF Operators (with \texttt{ncrcat}) which is available at:
199    \begin{rawhtml} <A href="http://nco.sourceforge.net/"> \end{rawhtml}
200    \begin{verbatim}
201    http://nco.sourceforge.net/
202    \end{verbatim}
203    \begin{rawhtml} </A> \end{rawhtml}
204    
205    Additional MNC--related parameters may be contained within each
206    package.  Please see the individual packages for descriptions of their
207    use of MNC.
208    
209    
210    \subsubsection{MNC Output}
211    
212    Depending upon the flags used, MNC will produce zero or more
213    directories containing one or more netCDF files as output.  These
214    files are either mostly or entirely compliant with the netCDF ``CF''
215    convention (v1.0) and any conformance issues will be fixed over time.
216    The patterns used for file names are:
217    \begin{center}
218    \texttt{BASENAME.nIter0.tileNum.seqNum.nc}
219    \end{center}
220    and an example is:
221    \begin{center}
222    \texttt{grid.0000000000.000001.0000.nc}
223    \end{center}
224    where \texttt{BASENAME} is the name selected to represent a set of
225    variables written together, \texttt{nIter0} is the starting iteration
226    number as specified in the main \texttt{data} namelist input file and
227    written in a zero-filled 10-digit format, \texttt{tileNum} is the
228    six-digit zero-filled tile number, \texttt{seqnum} is a four-digit
229    zero-filled sequence number used when maximum allowable files sizes
230    are too small to contain all of the output for a particular type
231    within one run (new files are created with sequential numbers as files
232    reach the maximum file size limit), and \texttt{.nc} is the file
233    suffix specified by the current netCDF ``CF'' conventions.
234    
235    Some example \texttt{BASENAME} values are:
236    \begin{description}
237    \item[grid] contains the variables that describe the various grid
238      constants related to locations, lengths, areas, etc.
239    \item[state] contains the variables output at the snapshot or
240      \texttt{dumpFreq} time frequency
241    \item[pickup.ckptA, pickup.ckptB] are the ``rolling'' checkpoint files
242    \item[tave] contains the time-averaged quantities from the main model
243    \end{description}
244    
245    All MNC output is currently done in a ``file-per-tile'' fashion since
246    most NetCDF v3.x implementions cannot write safely within MPI or
247    multi-threaded environments.  This tiling is done in a global fashion
248    and the tile numbers are appended to the base names as described
249    above.  Some scripts to manipulate MNC output are available at
250    \texttt{MITgcm/utils/matlab/} which includes a spatial ``assembly''
251    script called \texttt{MITgcm/utils/matlab/mnc\_assembly.m}.
252    
253    More general manipulations can be performed on netCDF files with
254    \begin{rawhtml} <A href="http://nco.sourceforge.net"> \end{rawhtml}
255    \begin{verbatim}
256    the NetCDF Operators (``NCO'')
257    at http://nco.sourceforge.net
258    \end{verbatim}
259    \begin{rawhtml} </A> \end{rawhtml}
260    or with
261    \begin{rawhtml} <A href=''http://www.mpimet.mpg.de/~cdo/"> \end{rawhtml}
262    \begin{verbatim}
263    the Climate Data Operators (``CDO'')
264    at http://www.mpimet.mpg.de/~cdo/
265    \end{verbatim}
266    \begin{rawhtml} </A> \end{rawhtml}
267    
268    Unlike the older MDSIO routines, MNC reads and writes variables on
269    different ``grids'' depending upon their location on, for instance, an
270    Arakawa C--grid.  The following table provides examples:
271  \begin{center}  \begin{center}
272    {\footnotesize    {\footnotesize
273      \begin{tabular}[htb]{|l|c|l|l|}\hline      \begin{tabular}[htb]{|l|c|c|c|}\hline
274        \textbf{Name}  &  \textbf{T}  &          \textbf{Name}  &  \textbf{C--grid location}  &  
275        \textbf{Default}  &  \textbf{Description}  \\\hline        \textbf{\# in X}  &  \textbf{\# in Y}  \\\hline
276        \multicolumn{4}{|c|}{\ }  \\        Temperature & mass & \texttt{sNx} & \texttt{sNy} \\
277        \multicolumn{4}{|c|}{Main namelist file:        Salinity & mass & \texttt{sNx} & \texttt{sNy} \\
278          ``\textbf{data}''}  \\\hline        U velocity & U & \texttt{sNx+1} & \texttt{sNy} \\
279        \texttt{snapshot\_ioinc}  &  L  & \texttt{.FALSE.}  &          V velocity & V & \texttt{sNx} & \texttt{sNy+1} \\
280        write \texttt{snapshot} ``inclusively''  \\        Vorticity & vorticity & \texttt{sNx+1} & \texttt{sNy+1} \\\hline
       \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  
281      \end{tabular}      \end{tabular}
282    }    }
283  \end{center}  \end{center}
284    and the intent is two--fold:
285    \begin{enumerate}
286    \item For some grid topologies it is impossible to output all
287      quantities using only \texttt{sNx,sNy} arrays for every tile.  Two
288      examples of this failure are the missing corners problem for
289      vorticity values on the cubesphere and the velocity edge values for
290      some open--boundary domains.
291    \item Writing quantities located on velocity or vorticity points with
292      the above scheme introduces a very small data redundancy.  However,
293      any slight inconvenience is easily offset by the ease with which one
294      can, on every individual tile, interpolate these values to mass
295      points without having to perform an ``exchange'' (or
296      ``halo-filling'') operation to collect the values from neighboring
297      tiles.  This makes the most common post--processing operations much
298      easier to implement.
299    \end{enumerate}
300    
301    
302    \subsection{MNC Troubleshooting}
303    
304    \subsubsection{Build Troubleshooting}
305    
306    In order to build MITgcm with MNC enabled, the netCDF v3.x Fortran-77
307    (not Fortran-90) library must be available.  This library is compposed
308    of a single header file (called \texttt{netcdf.inc}) and a single
309    library file (usually called \texttt{libnetcdf.a}) and it must be
310    built with the same compiler (or a binary-compatible compiler) with
311    compatible compiler options as the one used to build MITgcm.
312    
313    For more details concerning the netCDF build and install process,
314    please visit the netCDF home page at:
315    \begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}
316    \begin{verbatim}
317    http://www.unidata.ucar.edu/packages/netcdf/
318    \end{verbatim}
319    \begin{rawhtml} </A> \end{rawhtml}
320    which includes an extensive list of known--good netCDF configurations
321    for various platforms
322    
323  By default, turning on MNC for a particular output type will result in  \subsubsection{Runtime Troubleshooting}
 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}  
324    
325  While NetCDF files are supposed to be ``self-describing'', it is  Please be aware of the following:
 helpful to note the following:  
326    
327  \begin{itemize}  \begin{itemize}
328    \item As a safety feature, the MNC package does not, by default, allow
329      pre-existing files to be appended to or overwritten.  This is in
330      contrast to the older MDSIO package which will, without any warning,
331      overwrite existing files.  If MITgcm aborts with an error message
332      about the inability to open or write to a netCDF file, please check
333      \textbf{first} whether you are attempting to overwrite files from a
334      previous run.
335    
336  \item The constraints placed upon the ``unlimited'' (or ``record'')  \item The constraints placed upon the ``unlimited'' (or ``record'')
337    dimension inherent with NetCDF v3.x make it very inefficient to put    dimension inherent with NetCDF v3.x make it very inefficient to put
338    variables written at potentially different intervals within the same    variables written at potentially different intervals within the same
339    file.  For this reason, MNC output is split into a few file ``base    file.  For this reason, MNC output is split into groups of files
340    names'' which try to reflect the nature of their content.    which attempt to reflect the nature of their content.
341        
342  \item All MNC output is currently done in a ``tile-per-file'' fashion  \item On many systems, netCDF has practical file size limits on the
343    since most NetCDF v3.x implementions cannot write safely within MPI    order of 2--4GB (the maximium memory addressable with 32bit pointers
344    or multi-threaded environments.  This tiling is done in a global    or pointer differences) due to a lack of operating system, compiler,
345    fashion and the tile numbers are appended to the base names    and/or library support.  The latest revisions of netCDF v3.x have
346    described above.  Some scripts to ``assemble'' output are available    large file support and, on some operating systems, file sizes are
347    (\texttt{MITgcm/utils/matlab}).  More general manipulations can be    only limited by available disk space.
   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.  
348        
349  \item On many systems, NetCDF has practical file size limits on the  \item There is an 80 character limit to the total length of all file
350    order of 2--4GB (the maximium memory addressable with 32bit    names.  This limit includes the directory (or path) since paths and
351    pointers) due to a lack of operating system, compiler, and/or    file names are internally appended.  Generally, file names will not
352    library support.  In cases where this limit is reached, it is    exceed the limit and paths can usually be shortened using, for
353    generally a good idea to reduce write frequencies or restart from    example, soft links.
   pickups.  
354        
355  \item MNC does not (yet) provide a mechanism for reading information  \item MNC does not (yet) provide a mechanism for reading information
356    from a single ``global'' file as can be done with the MDSIO    from a single ``global'' file as can be done with the MDSIO
357    package.  This is in progress.    package.  This is in progress.
   
358  \end{itemize}  \end{itemize}
359    
360    
Legend:
Removed from v.1.14  
changed lines
  Added in v.1.15
  ViewVC Help
Powered by ViewVC 1.1.22