--- manual/s_phys_pkgs/text/packages.tex 2004/02/12 03:35:05 1.2 +++ manual/s_phys_pkgs/text/packages.tex 2010/08/30 23:09:21 1.8 @@ -1,7 +1,11 @@ -% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/packages.tex,v 1.2 2004/02/12 03:35:05 edhill Exp $ +% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/packages.tex,v 1.8 2010/08/30 23:09:21 jmc Exp $ % $Name: $ \section{Using MITgcm Packages} +\label{sec:pkg:using} +\begin{rawhtml} + +\end{rawhtml} The set of packages that will be used within a partiucular model can be configured using a combination of both ``compile--time'' and @@ -16,7 +20,7 @@ There are numerous ways that one can specify compile--time package inclusion or exclusion and they are all implemented by the \texttt{genmake2} program which was previously described in Section -\ref{sect:buildingCode}. The options are as follows: +\ref{sec:buildingCode}. The options are as follows: \begin{enumerate} \item Setting the \texttt{genamake2} options \texttt{--enable PKG} and/or \texttt{--disable PKG} specifies inclusion or exclusion. @@ -37,8 +41,9 @@ automatically obtains all packages in that group. \item By default (that is, if a \texttt{packages.conf} file is not - found), the \texttt{genmake2} program will use the contents of the - \texttt{pkg/pkg\_default} file to obtain a list of packages. + found), the \texttt{genmake2} program will use the + package group default ``\texttt{default\_pkg\_list}'' as defined + in \texttt{pkg/pkg\_groups} file. \item To help prevent users from creating unusable package groups, the \texttt{genmake2} program will parse the contents of the @@ -75,12 +80,12 @@ still be aware of the dependency. -\section{Package Coding Standards} +\subsection{Package Coding Standards} The following sections describe how to modify and/or create new MITgcm packages. -\subsection{Packages are Not Libraries} +\subsubsection{Packages are Not Libraries} To a beginner, the MITgcm packages may resemble libraries as used in myriad software projects. While future versions are likely to @@ -88,7 +93,7 @@ the current packages (FORTRAN77) are \textbf{not} based upon any concept of libraries. -\subsubsection{File ``Hiding'' Rules} +\subsubsection{File Inclusion Rules} Instead, packages should be viewed only as directories containing ``sets of source files'' that are built using some simple mechanisms @@ -111,12 +116,14 @@ previously encountered) then the file within the newer (more recently visited) package will superseed (or ``hide'') any previous file(s) with the same name. - + \item Packages are visited (and thus files discovered) {\it in the order that the packages are enabled} within \texttt{genmake2}. Thus, the files in \texttt{PackB} may superseed the files in - \texttt{PackA} if \texttt{PackA} is enabled before - \texttt{PackB}. Thus, package ordering can be significant! + \texttt{PackA} if \texttt{PackA} is enabled before \texttt{PackB}. + Thus, package ordering can be significant! For this reason, + \texttt{genmake2} honors the order in which packages are + specified. \end{enumerate} \end{enumerate} @@ -157,20 +164,98 @@ \end{verbatim} which is included from the file \filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F} +and shows how both the compile--time \texttt{ALLOW\_GMREDI} flag and the +run--time \texttt{useGMRedi} are nested. -There are some benefits to using this technique. The first is that -code snippets or subroutines associated with packages can be placed or -called from almost anywhere else within the code. The second benefit -is related to the memory footprint and performance. Since unused code -can be removed, there is no performance penalty due to unnecessary -memory allocation or unused function calls. The major problems with -this approach are difficult-to-read and difficult-to-test code caused -by the numerous CPP statements. Developers should exerecise some -discipline and avoid ``smearing'' implementation details across -numerous files in a haphazard fashion. - +There are some benefits to using the technique described here. The +first is that code snippets or subroutines associated with packages +can be placed or called from almost anywhere else within the code. +The second benefit is related to memory footprint and performance. +Since unused code can be removed, there is no performance penalty due +to unnecessary memory allocation, unused function calls, or extra +run-time \texttt{IF (...)} conditions. The major problems with this +approach are the potentially difficult-to-read and difficult-to-debug +code caused by an overuse of CPP statements. So while it can be done, +developers should exerecise some discipline and avoid unnecesarily +``smearing'' their package implementation details across numerous +files. + + +\subsubsection{Package Startup or Boot Sequence} + +Calls to package routines within the core code timestepping loop can +vary. However, all packages should follow a required "boot" sequence +outlined here: - -\subsection{Interfaces} +{\footnotesize +\begin{verbatim} + 1. S/R PACKAGES_BOOT() + : + CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... ) + + + 2. S/R PACKAGES_READPARMS() + : + #ifdef ALLOW_${PKG} + if ( use${Pkg} ) + & CALL ${PKG}_READPARMS( retCode ) + #endif + + 3. S/R PACKAGES_INIT_FIXED() + : + #ifdef ALLOW_${PKG} + if ( use${Pkg} ) + & CALL ${PKG}_INIT_FIXED( retCode ) + #endif + + 4. S/R PACKAGES_CHECK() + : + #ifdef ALLOW_${PKG} + if ( use${Pkg} ) + & CALL ${PKG}_CHECK( retCode ) + #else + if ( use${Pkg} ) + & CALL PACKAGES_CHECK_ERROR('${PKG}') + #endif + + 5. S/R PACKAGES_INIT_VARIABLES() + : + #ifdef ALLOW_${PKG} + if ( use${Pkg} ) + & CALL ${PKG}_INIT_VARIA( ) + #endif + + 6. S/R DO_THE_MODEL_IO + + #ifdef ALLOW_${PKG} + if ( use${Pkg} ) + & CALL ${PKG}_OUTPUT( ) + #endif + + 7. S/R PACKAGES_WRITE_PICKUP() + + #ifdef ALLOW_${PKG} + if ( use${Pkg} ) + & CALL ${PKG}_WRITE_PICKUP( ) + #endif\end{verbatim} +} + + +\subsubsection{Adding a package to PARAMS.h and packages\_boot()} + +An MITgcm package directory contains all the code needed for that package apart +from one variable for each package. This variable is the {\it use\$\{Pkg\} } +flag. This flag, which is of type logical, {\bf must} be declared in the +shared header file {\it PARAMS.h} in the {\it PARM\_PACKAGES} block. This +convention is used to support a single runtime control file {\it data.pkg} +which is read by the startup routine {\it packages\_boot()} and that sets a +flag controlling the runtime use of a package. This routine needs to be able to +read the flags for packages that were not built at compile time. Therefore +when adding a new package, in addition to creating the per-package directory +in the {\it pkg/} subdirectory a developer should add a {\it use\$\{Pkg\} } +flag to {\it PARAMS.h} and a {\it use\$\{Pkg\} } entry to the +{\it packages\_boot()} {\it PACKAGES} namelist. +The only other package specific code that should appear outside the individual +package directory are calls to the specific package API.