manual/s_phys_pkgs/mnc.tex

% $Header: /u/u3/gcmpack/manual/part6/mnc.tex,v 1.5 2004/02/12 03:35:05 edhill Exp $
% $Name:  $

\section{NetCDF I/O Integration: MNC}
\label{sec:pkg:mnc}

The \texttt{mnc} package is a set of convenience routines written to
expedite the process of creating, appending, and reading NetCDF files.
NetCDF is an increasingly popular self-describing file format
\cite{rew:97} intended primarily for scientific data sets.  An
extensive collection of NetCDF reference papers, user guides,
software, FAQs, and other information can be obtained from UCAR's web
site at:
\begin{rawhtml} <A href="http://www.unidata.ucar.edu/packages/netcdf/"> \end{rawhtml}
\begin{verbatim}
http://www.unidata.ucar.edu/packages/netcdf/
\end{verbatim}
\begin{rawhtml} </A> \end{rawhtml}


\subsection{Introduction}

The \texttt{mnc} package is a two-level convenience library (or
``wrapper'') for most of the NetCDF Fortran API.  Its purpose is to
streamline the user interface to NetCDF by maintaining internal
relations (look-up tables) keyed with strings (or names) and entities
such as NetCDF files, variables, and attributes.

The two levels of the \texttt{mnc} package are:
\begin{description}

\item[Upper level] \ 
  
  The upper level contains information about two kinds of
  associations:
  \begin{description}
  \item[grid type] is lookup table indexed with a grid type name.
    Each grid type name is associated with a number of dimensions, the
    dimension sizes (one of which may be unlimited), and starting and
    ending index arrays.  The intent is to store all the necessary
    size and shape information for the Fortran arrays containing
    MITgcm--style ``tile'' variables (that is, a central region
    surrounded by a variably-sized ``halo'' or exchange region as
    shown in Figures \ref{fig:communication_primitives} and
    \ref{fig:tiling-strategy}).
  
  \item[variable type] is a lookup table indexed by a variable type
    name.  For each name, the table contains a reference to a grid
    type for the variable and the names and values of various
    attributes.
  \end{description}
  
  Within the upper level, these associations are not permanently tied
  to any particular NetCDF file.  This allows the information to be
  re-used over multiple file reads and writes.

\item[Lower level] \ 
  
  In the lower (or internal) level, associations are stored for NetCDF
  files and many of the entities that they contain including
  dimensions, variables, and global attributes.  All associations are
  on a per-file basis.  Thus, each entity is tied to a unique NetCDF
  file and will be created or destroyed when files are, respectively,
  opened or closed.

\end{description}


\subsection{Using MNC}

\subsubsection{Grid--Types and Variable--Types}

As a convenience for users, the MNC package includes numerous routines
to aid in the writing of data to NetCDF format.  Probably the biggest
convenience is the use of pre-defined ``grid types'' and ``variable
types''.  These ``types'' are simply look-up tables that store
dimensions, indicies, attributes, and other information that can all
be retrieved using a single character string.

The ``grid types'' are a way of mapping variables within MITgcm to
NetCDF arrays.  Within MITgcm, most spatial variables are defined
using two-- or three--dimensional arrays with ``overlap'' regions (see
Figures \ref{fig:communication_primitives}, a possible vertical index,
and \ref{fig:tiling-strategy}) and tile indicies such as the following
``U'' velocity:
\begin{verbatim}
      _RL  uVel (1-OLx:sNx+OLx,1-OLy:sNy+OLy,Nr,nSx,nSy)
\end{verbatim}
as defined in \filelink{model/inc/DYNVARS.h}{model-inc-DYNVARS.h}

The grid type is a character string that encodes the presence and
types associated with the four possible dimensions.  The character
string follows the format
\begin{center}
  \texttt{H0\_H1\_H2\_\_V\_\_T}
\end{center}
where the terms \textit{H0}, \textit{H1}, \textit{H2}, \textit{V},
\textit{T} can be almost any combination of the following:
\begin{center}
  \begin{tabular}[h]{|ccc|c|c|}\hline
    \multicolumn{3}{|c|}{Horizontal} & Vertical & Time \\
    \textit{H0}: location & \textit{H1}: dimensions & \textit{H2}: halo 
          & \textit{V}: location & \textit{T}: level  \\\hline
    \texttt{-} & xy & Hn & \texttt{-} & \texttt{-} \\
    U  &  x  &  Hy  &  i  &  t  \\
    V  &  y  &      &  c  &     \\
    Cen  &   &      &     &     \\
    Cor  &   &      &     &     \\\hline
  \end{tabular}
\end{center}
A example list of all pre-defined combinations is contained in the
file
\begin{center}
  \texttt{pkg/mnc/pre-defined\_grids.txt}.
\end{center}


\subsubsection{An Example}

Writing variables to NetCDF files can be accomplished in as few as two
function calls.  The first function call defines a variable type,
associates it with a name (character string), and provides additional
information about the indicies for the tile (\texttt{bi},\texttt{bj})
dimensions.  The second function call will write the data at, if
necessary, the current time level within the model.

Examples of the initialization calls can be found in the file 
\filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F}
where these four function calls:
{\footnotesize
\begin{verbatim}
  C     Create MNC definitions for DYNVARS.h variables
        CALL MNC_CW_ADD_VNAME(myThid, 'iter', '-_-_--__-__t', 0,0)
        CALL MNC_CW_ADD_VATTR_TEXT(myThid,'iter',1,
       &     'long_name','iteration_count')
        CALL MNC_CW_ADD_VNAME(myThid, 'U', 'U_xy_Hn__C__t', 4,5)
        CALL MNC_CW_ADD_VATTR_TEXT(myThid,'U',1,'units','m/s')
\end{verbatim}
}
{\noindent initialize two \texttt{VNAME}s and add one NetCDF
  attribute to each.}
    
The two variables defined above are subsequently written at specific
time steps within
\filelink{model/src/write\_state.F}{model-src-write_state.F}
using the function calls:
{\footnotesize
\begin{verbatim}
  C     Write the DYNVARS.h variables using the MNC package
        mnc_iter = myIter
        CALL MNC_CW_RL_W_R(myThid,'state',0,0,'iter',-1,mnc_iter)
        CALL MNC_CW_RL_W_D(myThid,'state',0,0,'U', 0, uVel)
\end{verbatim}
}


\subsection{Key subroutines, parameters and files}

All of the variables used to implement the lookup tables are described
in \filelink{model/src/write\_state.F}{model-src-write_state.F}


\subsection{Package Reference}

1	% $Header: /u/u3/gcmpack/manual/part6/mnc.tex,v 1.5 2004/02/12 03:35:05 edhill Exp $
2	% $Name: $
3
4	\section{NetCDF I/O Integration: MNC}
5	\label{sec:pkg:mnc}
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
20
21	\subsection{Introduction}
22
23	The \texttt{mnc} package is a two-level convenience library (or
24	``wrapper'') for most of the NetCDF Fortran API. Its purpose is to
25	streamline the user interface to NetCDF by maintaining internal
26	relations (look-up tables) keyed with strings (or names) and entities
27	such as NetCDF files, variables, and attributes.
28
29	The two levels of the \texttt{mnc} package are:
30	\begin{description}
31
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	\textit{H0}: location & \textit{H1}: dimensions & \textit{H2}: halo
103	& \textit{V}: location & \textit{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
118	\subsubsection{An Example}
119
120	Writing variables to NetCDF files can be accomplished in as few as two
121	function calls. The first function call defines a variable type,
122	associates it with a name (character string), and provides additional
123	information about the indicies for the tile (\texttt{bi},\texttt{bj})
124	dimensions. The second function call will write the data at, if
125	necessary, the current time level within the model.
126
127	Examples of the initialization calls can be found in the file
128	\filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F}
129	where these four function calls:
130	{\footnotesize
131	\begin{verbatim}
132	C Create MNC definitions for DYNVARS.h variables
133	CALL MNC_CW_ADD_VNAME(myThid, 'iter', '-_-_--__-__t', 0,0)
134	CALL MNC_CW_ADD_VATTR_TEXT(myThid,'iter',1,
135	& 'long_name','iteration_count')
136	CALL MNC_CW_ADD_VNAME(myThid, 'U', 'U_xy_Hn__C__t', 4,5)
137	CALL MNC_CW_ADD_VATTR_TEXT(myThid,'U',1,'units','m/s')
138	\end{verbatim}
139	}
140	{\noindent initialize two \texttt{VNAME}s and add one NetCDF
141	attribute to each.}
142
143	The two variables defined above are subsequently written at specific
144	time steps within
145	\filelink{model/src/write\_state.F}{model-src-write_state.F}
146	using the function calls:
147	{\footnotesize
148	\begin{verbatim}
149	C Write the DYNVARS.h variables using the MNC package
150	mnc_iter = myIter
151	CALL MNC_CW_RL_W_R(myThid,'state',0,0,'iter',-1,mnc_iter)
152	CALL MNC_CW_RL_W_D(myThid,'state',0,0,'U', 0, uVel)
153	\end{verbatim}
154	}
155
156
157	\subsection{Key subroutines, parameters and files}
158
159	All of the variables used to implement the lookup tables are described
160	in \filelink{model/src/write\_state.F}{model-src-write_state.F}
161
162
163
164	\subsection{Package Reference}
165