manual/s_phys_pkgs/mnc.tex

% $Header: /u/u3/gcmpack/manual/part6/mnc.tex,v 1.3 2004/01/29 21:12:31 edhill Exp $
% $Name:  $

\section{NetCDF I/O Integration}
\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{Key subroutines, parameters and files}

All of the variables used to implement the lookup tables are described
in \filelink{pkg/mnc/mnc\_common.h}{pkg/mnc/mnc_common}.


\subsection{Package Reference}
1	edhill	1.4	% $Header: /u/u3/gcmpack/manual/part6/mnc.tex,v 1.3 2004/01/29 21:12:31 edhill Exp $
2	edhill	1.1	% $Name: $
3
4	edhill	1.3	\section{NetCDF I/O Integration}
5			\label{sec:pkg:mnc}
6	edhill	1.1
7	edhill	1.3	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	edhill	1.1
20
21			\subsection{Introduction}
22
23	edhill	1.3	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
27			entities 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	edhill	1.1
68
69	edhill	1.3	\subsection{Key subroutines, parameters and files}
70	edhill	1.1
71	edhill	1.3	All of the variables used to implement the lookup tables are described
72	edhill	1.4	in \filelink{pkg/mnc/mnc\_common.h}{pkg/mnc/mnc_common}.
73	edhill	1.1
74
75
76	edhill	1.3	\subsection{Package Reference}