% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/Attic/mnc.tex,v 1.10 2004/07/05 16:35:32 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} \end{rawhtml} \begin{verbatim} http://www.unidata.ucar.edu/packages/netcdf/ \end{verbatim} \begin{rawhtml} \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 \\ \textbf{H0}: location & \textbf{H1}: dimensions & \textbf{H2}: halo & \textbf{V}: location & \textbf{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} The variable type is an association between a variable type name and the following items: \begin{center} \begin{tabular}[h]{|l|l|}\hline \textbf{Item} & \textbf{Purpose} \\\hline grid type & defines the in-memory arrangement \\ \texttt{bi,bj} dimensions & tiling indices, if present \\\hline \end{tabular} \end{center} and is used by the \texttt{mnc\_cw\_*\_[R|W]} subroutines for reading and writing variables. \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/ini\_mnc\_io.F}{model-src-ini_mnc_io.F} where these function calls: {\footnotesize \begin{verbatim} C Create MNC definitions for DYNVARS.h variables CALL MNC_CW_ADD_VNAME('iter', '-_-_--__-__t', 0,0, myThid) CALL MNC_CW_ADD_VATTR_TEXT('iter',1, & 'long_name','iteration_count', myThid) CALL MNC_CW_ADD_VNAME('model_time', '-_-_--__-__t', 0,0, myThid) CALL MNC_CW_ADD_VATTR_TEXT('model_time',1, & 'long_name','Model Time', myThid) CALL MNC_CW_ADD_VATTR_TEXT('model_time',1,'units','s', myThid) CALL MNC_CW_ADD_VNAME('U', 'U_xy_Hn__C__t', 4,5, myThid) CALL MNC_CW_ADD_VATTR_TEXT('U',1,'units','m/s', myThid) CALL MNC_CW_ADD_VATTR_TEXT('U',1, & 'coordinates','XU YU RC iter', myThid) CALL MNC_CW_ADD_VNAME('T', 'Cen_xy_Hn__C__t', 4,5, myThid) CALL MNC_CW_ADD_VATTR_TEXT('T',1,'units','degC', myThid) CALL MNC_CW_ADD_VATTR_TEXT('T',1,'long_name', & 'potential_temperature', myThid) CALL MNC_CW_ADD_VATTR_TEXT('T',1, & 'coordinates','XC YC RC iter', myThid) \end{verbatim} } {\noindent initialize four \texttt{VNAME}s and add one or more NetCDF attributes to each.} The four 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 dynvars using the MNC package CALL MNC_CW_SET_UDIM('state', -1, myThid) CALL MNC_CW_I_W('I','state',0,0,'iter', myIter, myThid) CALL MNC_CW_SET_UDIM('state', 0, myThid) CALL MNC_CW_RL_W('D','state',0,0,'model_time',myTime, myThid) CALL MNC_CW_RL_W('D','state',0,0,'U', uVel, myThid) CALL MNC_CW_RL_W('D','state',0,0,'T', theta, myThid) \end{verbatim} } \subsubsection{Parameters} All the MNC parameters are contained within a file named \texttt{data.mnc}. If this file does not exist, then the MNC package will interpret that as an indication that it is not to be used. If the \texttt{data.mnc} does exist, then it may contain the following parameters: \begin{center} {\footnotesize \begin{tabular}[htb]{|l|l|l|l|}\hline & & & \\ \textbf{Name} & \textbf{Type} & \textbf{Default} & \textbf{Description} \\\hline & & & \\ \texttt{useMNC} & Logical & \texttt{.FALSE.} & \textbf{overall MNC ON/OFF switch} \\ \texttt{mnc\_echo\_gvtypes} & Logical & \texttt{.FALSE.} & echo pre-defined ``types'' to STDOUT? \\ \texttt{mnc\_use\_outdir} & Logical & \texttt{.FALSE.} & create a directory for output? \\ \texttt{mnc\_outdir\_str} & String & \texttt{'mnc\_'} & output directory name \\ \texttt{mnc\_outdir\_date} & Logical & \texttt{.FALSE.} & embed date in output directory name? \\ \texttt{mnc\_pickup\_write} & Logical & \texttt{.FALSE.} & use MNC to write (create) pickup files? \\ \texttt{mnc\_pickup\_read} & Logical & \texttt{.FALSE.} & use MNC to read pickup files? \\ \texttt{mnc\_use\_indir} & Logical & \texttt{.FALSE.} & use a directory (path) for input? \\ \texttt{mnc\_indir\_str} & String & \texttt{''} & input directory (or path) name \\ \texttt{mnc\_use\_for\_mon} & Logical & \texttt{.FALSE.} & write \texttt{monitor} output using MNC? \\\hline \end{tabular} } \end{center} %\subsection{Package Reference}