/[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.11 by edhill, Wed Sep 22 15:11: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    
7  The \texttt{mnc} package is a set of convenience routines written to  The \texttt{mnc} package is a set of convenience routines written to
# Line 23  http://www.unidata.ucar.edu/packages/net Line 23  http://www.unidata.ucar.edu/packages/net
23  The \texttt{mnc} package is a two-level convenience library (or  The \texttt{mnc} package is a two-level convenience library (or
24  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
25  streamline the user interface to NetCDF by maintaining internal  streamline the user interface to NetCDF by maintaining internal
26  relations (``look-up tables'') keyed with strings (or ``names'') and  relations (look-up tables) keyed with strings (or names) and entities
27  entities such as NetCDF files, variables, and attributes.  such as NetCDF files, variables, and attributes.
28    
29  The two levels of the \texttt{mnc} package are:  The two levels of the \texttt{mnc} package are:
30  \begin{description}  \begin{description}
# Line 34  The two levels of the \texttt{mnc} packa Line 34  The two levels of the \texttt{mnc} packa
34    The upper level contains information about two kinds of    The upper level contains information about two kinds of
35    associations:    associations:
36    \begin{description}    \begin{description}
37    \item[Grid type] is lookup table indexed with a grid type name.    \item[grid type] is lookup table indexed with a grid type name.
38      Each grid type name is associated with a number of dimensions, the      Each grid type name is associated with a number of dimensions, the
39      dimension sizes (one of which may be unlimited), and starting and      dimension sizes (one of which may be unlimited), and starting and
40      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 44  The two levels of the \texttt{mnc} packa
44      shown in Figures \ref{fig:communication_primitives} and      shown in Figures \ref{fig:communication_primitives} and
45      \ref{fig:tiling-strategy}).      \ref{fig:tiling-strategy}).
46        
47    \item[Variable type] is a lookup table indexed by a variable type    \item[variable type] is a lookup table indexed by a variable type
48      name.  For each name, the table contains a reference to a grid      name.  For each name, the table contains a reference to a grid
49      type for the variable and the names and values of various      type for the variable and the names and values of various
50      attributes.      attributes.
# Line 68  The two levels of the \texttt{mnc} packa Line 68  The two levels of the \texttt{mnc} packa
68    
69  \subsection{Using MNC}  \subsection{Using MNC}
70    
71  \subsubsection{``Grid--Types'' and ``Variable--Types''}  \subsubsection{Grid--Types and Variable--Types}
72    
73  As a convenience for users, the MNC package includes numerous routines  As a convenience for users, the MNC package includes numerous routines
74  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 94  string follows the format
94  \begin{center}  \begin{center}
95    \texttt{H0\_H1\_H2\_\_V\_\_T}    \texttt{H0\_H1\_H2\_\_V\_\_T}
96  \end{center}  \end{center}
97  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},
98  the following:  \textit{T} can be almost any combination of the following:
99  \begin{center}  \begin{center}
100    \begin{tabular}[h]{|ccc|c|c|}\hline    \begin{tabular}[h]{|ccc|c|c|}\hline
101      \multicolumn{3}{|c|}{Horizontal} & Vertical &  \\      \multicolumn{3}{|c|}{Horizontal} & Vertical & Time \\
102      Location & Direction & Halo & Location & Time  \\\hline      \textbf{H0}: location & \textbf{H1}: dimensions & \textbf{H2}: halo
103      H0  &  H1  &  H2  &  V  &  T  \\\hline            & \textbf{V}: location & \textbf{T}: level  \\\hline
104      \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\      \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\
105      U  &  x  &  Hy  &  i  &  t  \\      U  &  x  &  Hy  &  i  &  t  \\
106      V  &  y  &      &  c  &     \\      V  &  y  &      &  c  &     \\
# Line 114  file Line 114  file
114    \texttt{pkg/mnc/pre-defined\_grids.txt}.    \texttt{pkg/mnc/pre-defined\_grids.txt}.
115  \end{center}  \end{center}
116    
117    The variable type is an association between a variable type name and the
118    following items:
119    \begin{center}
120      \begin{tabular}[h]{|l|l|}\hline
121        \textbf{Item}  & \textbf{Purpose}  \\\hline
122        grid type  &  defines the in-memory arrangement  \\
123        \texttt{bi,bj} dimensions  &  tiling indices, if present  \\\hline
124      \end{tabular}
125    \end{center}
126    and is used by the \texttt{mnc\_cw\_*\_[R|W]} subroutines for reading
127    and writing variables.
128    
129    
130  \subsubsection{An Example}  \subsubsection{An Example}
131    
132  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
133  function calls.  The first function call defines a variable type,  function calls.  The first function call defines a variable type,
134  associates it with a name (character string), and provides additional  associates it with a name (character string), and provides additional
135  information about the indicies for \texttt{bi,bj} dimensions.  The  information about the indicies for the tile (\texttt{bi},\texttt{bj})
136  second function call will write variable at, if necessary, the  dimensions.  The second function call will write the data at, if
137  current time level within the model.  necessary, the current time level within the model.
138    
139  Examples of the initialization calls can be found in the file  Examples of the initialization calls can be found in the file
140  \begin{center}  \filelink{model/src/ini\_mnc\_io.F}{model-src-ini_mnc_io.F}
141    \filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F}  where these function calls:
142  \end{center}  {\footnotesize
 where these four function calls: {\footnotesize  
143  \begin{verbatim}  \begin{verbatim}
144    C     Create MNC definitions for DYNVARS.h variables  C     Create MNC definitions for DYNVARS.h variables
145          CALL MNC_CW_ADD_VNAME(myThid, 'iter', '-_-_--__-__t', 0,0)        CALL MNC_CW_ADD_VNAME('iter', '-_-_--__-__t', 0,0, myThid)
146          CALL MNC_CW_ADD_VATTR_TEXT(myThid,'iter',1,        CALL MNC_CW_ADD_VATTR_TEXT('iter',1,
147         &     'long_name','iteration_count')       &     'long_name','iteration_count', myThid)
148          CALL MNC_CW_ADD_VNAME(myThid, 'U', 'U_xy_Hn__C__t', 4,5)  
149          CALL MNC_CW_ADD_VATTR_TEXT(myThid,'U',1,'units','m/s')        CALL MNC_CW_ADD_VNAME('model_time', '-_-_--__-__t', 0,0, myThid)
150  \end{verbatim} }        CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,
151  {\noindent initialize two \texttt{VNAME}s and add one attribute to each.}       &     'long_name','Model Time', myThid)
152          CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,'units','s', myThid)
153    
154          CALL MNC_CW_ADD_VNAME('U', 'U_xy_Hn__C__t', 4,5, myThid)
155          CALL MNC_CW_ADD_VATTR_TEXT('U',1,'units','m/s', myThid)
156          CALL MNC_CW_ADD_VATTR_TEXT('U',1,
157         &     'coordinates','XU YU RC iter', myThid)
158    
159          CALL MNC_CW_ADD_VNAME('T', 'Cen_xy_Hn__C__t', 4,5, myThid)
160          CALL MNC_CW_ADD_VATTR_TEXT('T',1,'units','degC', myThid)
161          CALL MNC_CW_ADD_VATTR_TEXT('T',1,'long_name',
162         &     'potential_temperature', myThid)
163          CALL MNC_CW_ADD_VATTR_TEXT('T',1,
164         &     'coordinates','XC YC RC iter', myThid)
165    \end{verbatim}
166    }
167    {\noindent initialize four \texttt{VNAME}s and add one or more NetCDF
168      attributes to each.}
169            
170  The two variables are subsequently written at specific time steps  The four variables defined above are subsequently written at specific
171  within  time steps within
172  \begin{center}  \filelink{model/src/write\_state.F}{model-src-write_state.F}
173    \filelink{model/src/write\_state.F}{model-src-write_state.F}  using the function calls:
174  \end{center}  {\footnotesize
 using the function calls: {\footnotesize  
175  \begin{verbatim}  \begin{verbatim}
176    C     Write the DYNVARS.h variables using the MNC package  C       Write dynvars using the MNC package
177          mnc_iter = myIter          CALL MNC_CW_SET_UDIM('state', -1, myThid)
178          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)
179          CALL MNC_CW_RL_W_D(myThid,'state',0,0,'U', 0, uVel)          CALL MNC_CW_SET_UDIM('state', 0, myThid)
180  \end{verbatim} }          CALL MNC_CW_RL_W('D','state',0,0,'model_time',myTime, myThid)
181            CALL MNC_CW_RL_W('D','state',0,0,'U', uVel, myThid)
182            CALL MNC_CW_RL_W('D','state',0,0,'T', theta, myThid)
183    \end{verbatim}
184    }
185    
186    
187  \subsection{Key subroutines, parameters and files}  \subsubsection{Parameters}
188    
189  All of the variables used to implement the lookup tables are described  Most of the MNC--related parameters are contained within a Fortran
190  in \filelink{model/src/write\_state.F}{model-src-write_state.F}  namelist file called \texttt{data.mnc}.  If this file does not exist,
191    then the MNC package will interpret that as an indication that it is
192    not to be used.  If the \texttt{data.mnc} file does exist, then it may
193    contain the following parameters:
194    
195    \begin{center}
196      {\footnotesize
197        \begin{tabular}[htb]{|l|c|l|l|}\hline
198          \textbf{Name}  &  \textbf{T}  &  
199          \textbf{Default}  &  \textbf{Description}  \\\hline
200          &  &  &  \\
201          \texttt{useMNC}  &  L  & \texttt{.FALSE.}  &  
202          \textbf{overall MNC ON/OFF switch}  \\
203          \texttt{mnc\_echo\_gvtypes}  &  L  & \texttt{.FALSE.}  &  
204          echo pre-defined ``types'' (debugging)   \\
205          \texttt{mnc\_use\_outdir}  &  L  & \texttt{.FALSE.}  &  
206          create a directory for output  \\
207          \texttt{mnc\_outdir\_str}  &  S  & \texttt{'mnc\_'}  &  
208          output directory name \\
209          \texttt{mnc\_outdir\_date}  &  L  & \texttt{.FALSE.}  &  
210          embed date in the output dir name  \\
211          \texttt{pickup\_write\_mnc}  &  L  & \texttt{.FALSE.}  &  
212          use MNC to write (create) pickup files  \\
213          \texttt{pickup\_read\_mnc}  &  L  & \texttt{.FALSE.}  &  
214          use MNC to read pickup files  \\
215          \texttt{mnc\_use\_indir}  &  L  & \texttt{.FALSE.}  &  
216          use a directory (path) for input  \\
217          \texttt{mnc\_indir\_str}  &  S  & \texttt{''}  &  
218          input directory (or path) name  \\
219          \texttt{snapshot\_mnc}  &  L  & \texttt{.FALSE.}  &  
220          write \texttt{snapshot} (instantaneous) w/MNC  \\
221          \texttt{monitor\_mnc}  &  L  & \texttt{.FALSE.}  &  
222          write \texttt{monitor} w/MNC  \\
223          \texttt{timeave\_mnc}  &  L  & \texttt{.FALSE.}  &  
224          write \texttt{timeave} w/MNC  \\\hline
225        \end{tabular}
226      }
227    \end{center}
228    
229    Additional MNC--related parameters are contained within the main
230    \texttt{data} namelist file and in some of the namelist files for
231    individual packages.  These options are:
232    \begin{center}
233      {\footnotesize
234        \begin{tabular}[htb]{|l|c|l|l|}\hline
235          \textbf{Name}  &  \textbf{T}  &  
236          \textbf{Default}  &  \textbf{Description}  \\\hline
237          \multicolumn{4}{|c|}{\ }  \\
238          \multicolumn{4}{|c|}{Main namelist file:
239            ``\textbf{data}''}  \\\hline
240          \texttt{snapshot\_ioinc}  &  L  & \texttt{.FALSE.}  &  
241          write \texttt{snapshot} ``inclusively''  \\
242          \texttt{timeave\_ioinc}  &  L  & \texttt{.FALSE.}  &  
243          write \texttt{timeave} ``inclusively''  \\
244          \texttt{monitor\_ioinc}  &  L  & \texttt{.FALSE.}  &  
245          write \texttt{monitor} ``inclusively''  \\\hline
246          \multicolumn{4}{|c|}{\ }  \\
247          \multicolumn{4}{|c|}{Diagnostics namelist file:
248            ``\textbf{data.diagnostics}''}  \\\hline
249          \texttt{diag\_mnc}  &  L  & \texttt{.FALSE.}  &  
250          write \texttt{diagnostics} w/MNC  \\
251          \texttt{diag\_ioinc}  &  L  & \texttt{.FALSE.}  &  
252          write \texttt{diagnostics} ``inclusively''  \\\hline
253        \end{tabular}
254      }
255    \end{center}
256    
257  \subsection{Package Reference}  By default, turning on MNC for a particular output stream will result
258    in turning off all the corresponding (usually, default) MDSIO or
259    STDOUT output mechanisms.  In other words, output defaults to being an
260    exclusive selection.  To enable multiple kinds of simultaneous output,
261    flags of the form \texttt{NAME\_ioinc} can be used where \texttt{NAME}
262    corresponds to the various MNC output flags.  When a
263    \texttt{NAME\_ioinc} flag is set to \texttt{.TRUE.}, then multiple
264    forms of output are allowed for the \texttt{NAME} output mechanism.
265    The intent of this design is that typical users will only want one
266    kind of output while people debugging the code (particularly the I/O
267    routines) may want simultaneous types of output.
268    
269    This ``inclusive'' versus ``exclusive'' design is easily applied in
270    cases where three or more kinds of output may be generated.  Thus, it
271    can be readily extended to additional new output types (eg. HDF5).
272    
273    Input types are always exclusive.
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.11
  ViewVC Help
Powered by ViewVC 1.1.22