--- manual/s_phys_pkgs/mnc.tex 2004/01/28 21:27:45 1.2 +++ manual/s_phys_pkgs/mnc.tex 2004/02/12 03:35:05 1.5 @@ -1,35 +1,164 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.2 2004/01/28 21:27:45 cnh Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.5 2004/02/12 03:35:05 edhill Exp $ % $Name: $ -%% * Introduction -%% o what it does, citations (refs go into mitgcm_manual.bib, -%% 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} +\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} \end{rawhtml} +\begin{verbatim} +http://www.unidata.ucar.edu/packages/netcdf/ +\end{verbatim} +\begin{rawhtml} \end{rawhtml} -\section{MNC: the MITgcm NetCDF Package} -\label{sec:pkg:mnc} \subsection{Introduction} -The MNC package is a set of convenience routines written to expedite -the process of creating, appending, and reading NetCDF files. NetCDF -is a self-describing file format \cite{rew:97} intended primarily for -scientific data. NetCDF reference papers, user guides, FAQs, and other -information can be obtained from UCAR's web site at: - -\begin{itemize} -\item http://www.unidata.ucar.edu/packages/netcdf/ -\end{itemize} +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,H1,H2,V,T} can be almost any combination of +the following: +\begin{center} + \begin{tabular}[h]{|ccc|c|c|}\hline + \multicolumn{3}{|c|}{Horizontal} & Vertical & \\ + Location & Direction & Halo & Location & Time \\\hline + H0 & H1 & H2 & V & T \\\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 \texttt{bi,bj} dimensions. The +second function call will write variable at, if necessary, the +current time level within the model. + +Examples of the initialization calls can be found in the file +\begin{center} + \filelink{model/src/initialise\_fixed.F}{model-src-initialise_fixed.F} +\end{center} +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 attribute to each.} + +The two variables are subsequently written at specific time steps +within +\begin{center} + \filelink{model/src/write\_state.F}{model-src-write_state.F} +\end{center} +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{Key Routines} +\subsection{Package Reference} -\subsection{References}