/[MITgcm]/manual/s_phys_pkgs/text/packages.tex

Diff of /manual/s_phys_pkgs/text/packages.tex

Parent Directory | Revision Log | View Revision Graph Revision Graph | View Patch Patch

-revision 1.2 by edhill,
Thu Feb 12 03:35:05 2004 UTC
+revision 1.8 by jmc,
Mon Aug 30 23:09:21 2010 UTC
 Line 2
  % $Name$
  \section{Using MITgcm Packages}
+ \label{sec:pkg:using}
+ \begin{rawhtml}
+ <!-- CMIREDIR:package_using: -->
+ \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
-Line 16 
 set of subsequent run--time options.
+Line 20 
 set of subsequent run--time options.
  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.
-Line 37 
 inclusion or exclusion and they are all
+Line 41 
 inclusion or exclusion and they are all
    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
+   found), the \texttt{genmake2} program will use the
-   \texttt{pkg/pkg\_default} file to obtain a list of packages.
+   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
-Line 75 
 detected and reported as errors by the c
+Line 80 
 detected and reported as errors by the c
  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
-Line 88 
 implement packages as libraries (perhaps
+Line 93 
 implement packages as libraries (perhaps
  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
-Line 111 
 files as they are found and proceeds acc
+Line 116 
 files as they are found and proceeds acc
      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{PackA} if \texttt{PackA} is enabled before \texttt{PackB}.
-     \texttt{PackB}.  Thus, package ordering can be significant!
+     Thus, package ordering can be significant!  For this reason,
+     \texttt{genmake2} honors the order in which packages are
+     specified.
    \end{enumerate}
  \end{enumerate}
-Line 157 
 An example illustrating the use of these
+Line 164 
 An example illustrating the use of these
  \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
+ There are some benefits to using the technique described here.  The
- code snippets or subroutines associated with packages can be placed or
+ first is that code snippets or subroutines associated with packages
- called from almost anywhere else within the code.  The second benefit
+ can be placed or called from almost anywhere else within the code.
- is related to the memory footprint and performance.  Since unused code
+ The second benefit is related to memory footprint and performance.
- can be removed, there is no performance penalty due to unnecessary
+ Since unused code can be removed, there is no performance penalty due
- memory allocation or unused function calls.  The major problems with
+ to unnecessary memory allocation, unused function calls, or extra
- this approach are difficult-to-read and difficult-to-test code caused
+ run-time \texttt{IF (...)} conditions.  The major problems with this
- by the numerous CPP statements.  Developers should exerecise some
+ approach are the potentially difficult-to-read and difficult-to-debug
- discipline and avoid ``smearing'' implementation details across
+ code caused by an overuse of CPP statements.  So while it can be done,
- numerous files in a haphazard fashion.
+ 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:
+ {\footnotesize
- \subsection{Interfaces}
+ \begin{verbatim}
+. S/R PACKAGES_BOOT()
+             :
+         CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
+. S/R PACKAGES_READPARMS()
+             :
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_READPARMS( retCode )
+         #endif
+. S/R PACKAGES_INIT_FIXED()
+             :
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_INIT_FIXED( retCode )
+         #endif
+. S/R PACKAGES_CHECK()
+             :
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_CHECK( retCode )
+         #else
+           if ( use${Pkg} )
+      &       CALL PACKAGES_CHECK_ERROR('${PKG}')
+         #endif
+. S/R PACKAGES_INIT_VARIABLES()
+             :
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_INIT_VARIA( )
+         #endif
+. S/R DO_THE_MODEL_IO
+         #ifdef ALLOW_${PKG}
+           if ( use${Pkg} )
+      &       CALL ${PKG}_OUTPUT( )
+         #endif
+. 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.

 Legend:



Removed from v.1.2
 


changed lines


 
Added in v.1.8
 Legend:



Removed from v.1.2
 


changed lines


 
Added in v.1.8
-Removed from v.1.2
+Added in v.1.8

	ViewVC Help
Powered by ViewVC 1.1.22