s_phys_pkgs/text/packages.tex

% $Header: /u/u3/gcmpack/manual/part6/packages.tex,v 1.1 2004/02/11 18:09:17 edhill Exp $
% $Name:  $

\section{Using MITgcm Packages}

The set of packages that will be used within a partiucular model can
be configured using a combination of both ``compile--time'' and
``run--time'' options.  Compile--time options are those used to select
which packages will be ``compiled in'' or implemented within the
program.  Packages excluded at compile time are completely absent from
the executable program(s) and thus cannot be later activated by any
set of subsequent run--time options.

\subsection{Package Inclusion/Exclusion}

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:
\begin{enumerate}
\item Setting the \texttt{genamake2} options \texttt{--enable PKG}
  and/or \texttt{--disable PKG} specifies inclusion or exclusion.
  This method is intended as a convenient way to perform a single
  (perhaps for a quick test) compilation.
  
\item By creating a text file with the name \texttt{packages.conf} in
  either the local build directory or the \texttt{-mods=DIR}
  directory, one can specify a list of packages (one package per line,
  with '\texttt{\#}' as the comment character) to be included.  Since
  the \texttt{packages.conf} file can be saved, this is the preferred
  method for setting and recording (for future reference) the package
  configuration.
  
\item For convenience, a list of ``standard'' package groups is
  contained in the \texttt{pkg/pkg\_groups} file.  By selecting one of
  the package group names in the \texttt{packages.conf} file, one
  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.

\item To help prevent users from creating unusable package groups, the
  \texttt{genmake2} program will parse the contents of the
  \texttt{pkg/pkg\_depend} file to determine:
  \begin{itemize}
  \item whether any two requested packages cannot be simultaneously
    included (\textit{eg.} \textit{seaice} and \textit{thsice} are
    mutually exclusive),
  \item whether additional packages must be included in order to
    satisfy package dependencies (\textit{eg.} \textit{rw} depends
    upon functionality within the \textit{mdsio} package), and
  \item whether the set of all requested packages is compatible with
    the dependencies (and producing an error if they aren't).
  \end{itemize}
  Thus, as a result of the dependencies, additional packages may be
  added to those originally requested.

\end{enumerate}


\subsection{Package Activation}

For run--time package control, MITgcm uses flags set through a
\texttt{data.pkg} file.  While some packages (\textit{eg.}
\texttt{debug}, \texttt{mnc}, \texttt{exch2}) may have their own usage
conventions, most follow a simple flag naming convention of the form:
\begin{verbatim}
  usePackageName=.TRUE.
\end{verbatim}
where the \texttt{usePackageName} variable can activate or disable the
package at runtime.  As mentioned previously, packages must be
included in order to be activated.  Generally, such mistakes will be
detected and reported as errors by the code.  However, users should
still be aware of the dependency.


\section{Package Coding Standards}

The following sections describe how to modify and/or create new MITgcm
packages.

\subsection{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
implement packages as libraries (perhaps using FORTRAN90/95 syntax)
the current packages (FORTRAN77) are \textbf{not} based upon any
concept of libraries.

\subsubsection{File ``Hiding'' Rules}

Instead, packages should be viewed only as directories containing
``sets of source files'' that are built using some simple mechanisms
provided by \texttt{genmake2}.  Conceptually, the build process adds
files as they are found and proceeds according to the following rules:
\begin{enumerate}
\item \texttt{genmake2} locates a ``core'' or main set of source files
  (the \texttt{-standarddirs} option sets these locations and the
  default value contains the directories \texttt{eesupp} and
  \texttt{model}).
  
\item \texttt{genmake2} then finds additional source files by
  inspecting the contents of each of the package directories:
  \begin{enumerate}
  \item As the new files are found, they are added to a list of source
    files.

  \item If there is a file name ``collision'' (that is, if one of the
    files in a package has the same name as one of the files
    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!
  \end{enumerate}
\end{enumerate}

These rules were adopted since they provide a relatively simple means
for rapidly including (or ``hiding'') existing files with modified
versions.

\subsubsection{Conditional Compilation and \texttt{PACKAGES\_CONFIG.h}}

Given that packages are simply groups of files that may be added or
removed to form a whole, one may wonder how linking (that is, FORTRAN
symbol resolution) is handled.  This is the second way that
\texttt{genmake2} supports the concept of packages.  Basically,
\texttt{genmake2} creates a \texttt{Makefile} that, in turn, is able
to create a file called \texttt{PACKAGES\_CONFIG.h} that contains a set
of C pre-processor (or ``CPP'') directives such as:
\begin{verbatim}
   #undef  ALLOW_KPP
   #undef  ALLOW_LAND
   ...
   #define ALLOW_GENERIC_ADVDIFF
   #define ALLOW_MDSIO
   ...
\end{verbatim}
These CPP symbols are then used throughout the code to conditionally
isolate variable definitions, function calls, or any other code that
depends upon the presence or absence of any particular package.

An example illustrating the use of these defines is:
\begin{verbatim}
   #ifdef ALLOW_GMREDI
         IF (useGMRedi) CALL GMREDI_CALC_DIFF(
        I        bi,bj,iMin,iMax,jMin,jMax,K,
        I        maskUp,
        O        KappaRT,KappaRS,
        I        myThid)
   #endif
\end{verbatim}
which is included from the file
\filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F}

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.


\subsection{Interfaces}


1	edhill	1.2	% $Header: /u/u3/gcmpack/manual/part6/packages.tex,v 1.1 2004/02/11 18:09:17 edhill Exp $
2	edhill	1.1	% $Name: $
3
4			\section{Using MITgcm Packages}
5
6			The set of packages that will be used within a partiucular model can
7			be configured using a combination of both ``compile--time'' and
8			``run--time'' options. Compile--time options are those used to select
9			which packages will be ``compiled in'' or implemented within the
10			program. Packages excluded at compile time are completely absent from
11			the executable program(s) and thus cannot be later activated by any
12			set of subsequent run--time options.
13
14			\subsection{Package Inclusion/Exclusion}
15
16			There are numerous ways that one can specify compile--time package
17			inclusion or exclusion and they are all implemented by the
18			\texttt{genmake2} program which was previously described in Section
19			\ref{sect:buildingCode}. The options are as follows:
20			\begin{enumerate}
21			\item Setting the \texttt{genamake2} options \texttt{--enable PKG}
22			and/or \texttt{--disable PKG} specifies inclusion or exclusion.
23			This method is intended as a convenient way to perform a single
24			(perhaps for a quick test) compilation.
25
26			\item By creating a text file with the name \texttt{packages.conf} in
27			either the local build directory or the \texttt{-mods=DIR}
28			directory, one can specify a list of packages (one package per line,
29			with '\texttt{\#}' as the comment character) to be included. Since
30			the \texttt{packages.conf} file can be saved, this is the preferred
31			method for setting and recording (for future reference) the package
32			configuration.
33
34			\item For convenience, a list of ``standard'' package groups is
35			contained in the \texttt{pkg/pkg\_groups} file. By selecting one of
36			the package group names in the \texttt{packages.conf} file, one
37			automatically obtains all packages in that group.
38
39			\item By default (that is, if a \texttt{packages.conf} file is not
40			found), the \texttt{genmake2} program will use the contents of the
41			\texttt{pkg/pkg\_default} file to obtain a list of packages.
42
43			\item To help prevent users from creating unusable package groups, the
44			\texttt{genmake2} program will parse the contents of the
45			\texttt{pkg/pkg\_depend} file to determine:
46			\begin{itemize}
47			\item whether any two requested packages cannot be simultaneously
48			included (\textit{eg.} \textit{seaice} and \textit{thsice} are
49			mutually exclusive),
50			\item whether additional packages must be included in order to
51			satisfy package dependencies (\textit{eg.} \textit{rw} depends
52			upon functionality within the \textit{mdsio} package), and
53			\item whether the set of all requested packages is compatible with
54			the dependencies (and producing an error if they aren't).
55			\end{itemize}
56			Thus, as a result of the dependencies, additional packages may be
57			added to those originally requested.
58
59			\end{enumerate}
60
61
62			\subsection{Package Activation}
63
64			For run--time package control, MITgcm uses flags set through a
65			\texttt{data.pkg} file. While some packages (\textit{eg.}
66	edhill	1.2	\texttt{debug}, \texttt{mnc}, \texttt{exch2}) may have their own usage
67			conventions, most follow a simple flag naming convention of the form:
68	edhill	1.1	\begin{verbatim}
69			usePackageName=.TRUE.
70			\end{verbatim}
71			where the \texttt{usePackageName} variable can activate or disable the
72	edhill	1.2	package at runtime. As mentioned previously, packages must be
73			included in order to be activated. Generally, such mistakes will be
74			detected and reported as errors by the code. However, users should
75			still be aware of the dependency.
76	edhill	1.1
77
78	edhill	1.2	\section{Package Coding Standards}
79
80			The following sections describe how to modify and/or create new MITgcm
81			packages.
82
83			\subsection{Packages are Not Libraries}
84
85			To a beginner, the MITgcm packages may resemble libraries as used in
86			myriad software projects. While future versions are likely to
87			implement packages as libraries (perhaps using FORTRAN90/95 syntax)
88			the current packages (FORTRAN77) are \textbf{not} based upon any
89			concept of libraries.
90
91			\subsubsection{File ``Hiding'' Rules}
92
93			Instead, packages should be viewed only as directories containing
94			``sets of source files'' that are built using some simple mechanisms
95			provided by \texttt{genmake2}. Conceptually, the build process adds
96			files as they are found and proceeds according to the following rules:
97			\begin{enumerate}
98			\item \texttt{genmake2} locates a ``core'' or main set of source files
99			(the \texttt{-standarddirs} option sets these locations and the
100			default value contains the directories \texttt{eesupp} and
101			\texttt{model}).
102
103			\item \texttt{genmake2} then finds additional source files by
104			inspecting the contents of each of the package directories:
105			\begin{enumerate}
106			\item As the new files are found, they are added to a list of source
107			files.
108
109			\item If there is a file name ``collision'' (that is, if one of the
110			files in a package has the same name as one of the files
111			previously encountered) then the file within the newer (more
112			recently visited) package will superseed (or ``hide'') any
113			previous file(s) with the same name.
114
115			\item Packages are visited (and thus files discovered) {\it in the
116			order that the packages are enabled} within \texttt{genmake2}.
117			Thus, the files in \texttt{PackB} may superseed the files in
118			\texttt{PackA} if \texttt{PackA} is enabled before
119			\texttt{PackB}. Thus, package ordering can be significant!
120			\end{enumerate}
121			\end{enumerate}
122
123			These rules were adopted since they provide a relatively simple means
124			for rapidly including (or ``hiding'') existing files with modified
125			versions.
126
127			\subsubsection{Conditional Compilation and \texttt{PACKAGES\_CONFIG.h}}
128
129			Given that packages are simply groups of files that may be added or
130			removed to form a whole, one may wonder how linking (that is, FORTRAN
131			symbol resolution) is handled. This is the second way that
132			\texttt{genmake2} supports the concept of packages. Basically,
133			\texttt{genmake2} creates a \texttt{Makefile} that, in turn, is able
134			to create a file called \texttt{PACKAGES\_CONFIG.h} that contains a set
135			of C pre-processor (or ``CPP'') directives such as:
136			\begin{verbatim}
137			#undef ALLOW_KPP
138			#undef ALLOW_LAND
139			...
140			#define ALLOW_GENERIC_ADVDIFF
141			#define ALLOW_MDSIO
142			...
143			\end{verbatim}
144			These CPP symbols are then used throughout the code to conditionally
145			isolate variable definitions, function calls, or any other code that
146			depends upon the presence or absence of any particular package.
147
148			An example illustrating the use of these defines is:
149			\begin{verbatim}
150			#ifdef ALLOW_GMREDI
151			IF (useGMRedi) CALL GMREDI_CALC_DIFF(
152			I bi,bj,iMin,iMax,jMin,jMax,K,
153			I maskUp,
154			O KappaRT,KappaRS,
155			I myThid)
156			#endif
157			\end{verbatim}
158			which is included from the file
159			\filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F}
160
161			There are some benefits to using this technique. The first is that
162			code snippets or subroutines associated with packages can be placed or
163			called from almost anywhere else within the code. The second benefit
164			is related to the memory footprint and performance. Since unused code
165			can be removed, there is no performance penalty due to unnecessary
166			memory allocation or unused function calls. The major problems with
167			this approach are difficult-to-read and difficult-to-test code caused
168			by the numerous CPP statements. Developers should exerecise some
169			discipline and avoid ``smearing'' implementation details across
170			numerous files in a haphazard fashion.
171
172
173
174			\subsection{Interfaces}
175
176	edhill	1.1