/[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.2 by cnh, Wed Jan 28 21:27:45 2004 UTC revision 1.7 by edhill, Fri Apr 2 15:56:02 2004 UTC
# Line 1  Line 1 
1  % $Header$  % $Header$
2  % $Name$  % $Name$
3    
4  %%  * Introduction  \section{NetCDF I/O Integration: MNC}
5  %%    o what it does, citations (refs go into mitgcm_manual.bib,  \label{sec:pkg:mnc}
 %%      preferably in alphabetic order)  
 %%    o Equations  
 %%  * Key subroutines and parameters  
 %%  * Reference material (auto generated from Protex and structured comments)  
 %%    o automatically inserted at \section{Reference}  
6    
7    The \texttt{mnc} package is a set of convenience routines written to
8    expedite the process of creating, appending, and reading NetCDF files.
9    NetCDF is an increasingly popular self-describing file format
10    \cite{rew:97} intended primarily for scientific data sets.  An
11    extensive collection of NetCDF reference papers, user guides,
12    software, FAQs, and other information can be obtained from UCAR's web
13    site at:
14    \begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}
15    \begin{verbatim}
16    http://www.unidata.ucar.edu/packages/netcdf/
17    \end{verbatim}
18    \begin{rawhtml} </A> \end{rawhtml}
19    
 \section{MNC: the MITgcm NetCDF Package}  
 \label{sec:pkg:mnc}  
20    
21  \subsection{Introduction}  \subsection{Introduction}
22    
23  The MNC package is a set of convenience routines written to expedite  The \texttt{mnc} package is a two-level convenience library (or
24  the process of creating, appending, and reading NetCDF files.  NetCDF  ``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
25  is a self-describing file format \cite{rew:97} intended primarily for  streamline the user interface to NetCDF by maintaining internal
26  scientific data.  NetCDF reference papers, user guides, FAQs, and other  relations (look-up tables) keyed with strings (or names) and entities
27  information can be obtained from UCAR's web site at:  such as NetCDF files, variables, and attributes.
28    
29  \begin{itemize}  The two levels of the \texttt{mnc} package are:
30  \item http://www.unidata.ucar.edu/packages/netcdf/  \begin{description}
31  \end{itemize}  
32    \item[Upper level] \
33      
34      The upper level contains information about two kinds of
35      associations:
36      \begin{description}
37      \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
39        dimension sizes (one of which may be unlimited), and starting and
40        ending index arrays.  The intent is to store all the necessary
41        size and shape information for the Fortran arrays containing
42        MITgcm--style ``tile'' variables (that is, a central region
43        surrounded by a variably-sized ``halo'' or exchange region as
44        shown in Figures \ref{fig:communication_primitives} and
45        \ref{fig:tiling-strategy}).
46      
47      \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
49        type for the variable and the names and values of various
50        attributes.
51      \end{description}
52      
53      Within the upper level, these associations are not permanently tied
54      to any particular NetCDF file.  This allows the information to be
55      re-used over multiple file reads and writes.
56    
57    \item[Lower level] \
58      
59      In the lower (or internal) level, associations are stored for NetCDF
60      files and many of the entities that they contain including
61      dimensions, variables, and global attributes.  All associations are
62      on a per-file basis.  Thus, each entity is tied to a unique NetCDF
63      file and will be created or destroyed when files are, respectively,
64      opened or closed.
65    
66    \end{description}
67    
68    
69    \subsection{Using MNC}
70    
71    \subsubsection{Grid--Types and Variable--Types}
72    
73    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
75    convenience is the use of pre-defined ``grid types'' and ``variable
76    types''.  These ``types'' are simply look-up tables that store
77    dimensions, indicies, attributes, and other information that can all
78    be retrieved using a single character string.
79    
80    The ``grid types'' are a way of mapping variables within MITgcm to
81    NetCDF arrays.  Within MITgcm, most spatial variables are defined
82    using two-- or three--dimensional arrays with ``overlap'' regions (see
83    Figures \ref{fig:communication_primitives}, a possible vertical index,
84    and \ref{fig:tiling-strategy}) and tile indicies such as the following
85    ``U'' velocity:
86    \begin{verbatim}
87          _RL  uVel (1-OLx:sNx+OLx,1-OLy:sNy+OLy,Nr,nSx,nSy)
88    \end{verbatim}
89    as defined in \filelink{model/inc/DYNVARS.h}{model-inc-DYNVARS.h}
90    
91    The grid type is a character string that encodes the presence and
92    types associated with the four possible dimensions.  The character
93    string follows the format
94    \begin{center}
95      \texttt{H0\_H1\_H2\_\_V\_\_T}
96    \end{center}
97    where the terms \textit{H0}, \textit{H1}, \textit{H2}, \textit{V},
98    \textit{T} can be almost any combination of the following:
99    \begin{center}
100      \begin{tabular}[h]{|ccc|c|c|}\hline
101        \multicolumn{3}{|c|}{Horizontal} & Vertical & Time \\
102        \textbf{H0}: location & \textbf{H1}: dimensions & \textbf{H2}: halo
103              & \textbf{V}: location & \textbf{T}: level  \\\hline
104        \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\
105        U  &  x  &  Hy  &  i  &  t  \\
106        V  &  y  &      &  c  &     \\
107        Cen  &   &      &     &     \\
108        Cor  &   &      &     &     \\\hline
109      \end{tabular}
110    \end{center}
111    A example list of all pre-defined combinations is contained in the
112    file
113    \begin{center}
114      \texttt{pkg/mnc/pre-defined\_grids.txt}.
115    \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]{|ll|}\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}
131    
132    Writing variables to NetCDF files can be accomplished in as few as two
133    function calls.  The first function call defines a variable type,
134    associates it with a name (character string), and provides additional
135    information about the indicies for the tile (\texttt{bi},\texttt{bj})
136    dimensions.  The second function call will write the data at, if
137    necessary, the current time level within the model.
138    
139    Examples of the initialization calls can be found in the file
140    \filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F}
141    where these four function calls:
142    {\footnotesize
143    \begin{verbatim}
144      C     Create MNC definitions for DYNVARS.h variables
145            CALL MNC_CW_ADD_VNAME(myThid, 'iter', '-_-_--__-__t', 0,0)
146            CALL MNC_CW_ADD_VATTR_TEXT(myThid,'iter',1,
147           &     'long_name','iteration_count')
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')
150    \end{verbatim}
151    }
152    {\noindent initialize two \texttt{VNAME}s and add one NetCDF
153      attribute to each.}
154        
155    The two variables defined above are subsequently written at specific
156    time steps within
157    \filelink{model/src/write\_state.F}{model-src-write_state.F}
158    using the function calls:
159    {\footnotesize
160    \begin{verbatim}
161      C     Write the DYNVARS.h variables using the MNC package
162            mnc_iter = myIter
163            CALL MNC_CW_RL_W_R(myThid,'state',0,0,'iter',-1,mnc_iter)
164            CALL MNC_CW_RL_W_D(myThid,'state',0,0,'U', 0, uVel)
165    \end{verbatim}
166    }
167    
168    
169    \subsection{Key subroutines, parameters and files}
170    
171    All of the variables used to implement the lookup tables are described
172    in \filelink{model/src/write\_state.F}{model-src-write_state.F}
173    
 \subsection{Key Routines}  
174    
175    
176    \subsection{Package Reference}
177    
 \subsection{References}  
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.7
  ViewVC Help
Powered by ViewVC 1.1.22