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

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

Parent Directory Parent Directory | Revision Log 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.6 by molod, Mon Jul 18 20:45:27 2005 UTC
# Line 2  Line 2 
2  % $Name$  % $Name$
3    
4  \section{Using MITgcm Packages}  \section{Using MITgcm Packages}
5    \label{sec:pkg:using}
6    \begin{rawhtml}
7    <!-- CMIREDIR:package_using: -->
8    \end{rawhtml}
9    
10  The set of packages that will be used within a partiucular model can  The set of packages that will be used within a partiucular model can
11  be configured using a combination of both ``compile--time'' and  be configured using a combination of both ``compile--time'' and
# Line 75  detected and reported as errors by the c Line 79  detected and reported as errors by the c
79  still be aware of the dependency.  still be aware of the dependency.
80    
81    
82  \section{Package Coding Standards}  \subsection{Package Coding Standards}
83    
84  The following sections describe how to modify and/or create new MITgcm  The following sections describe how to modify and/or create new MITgcm
85  packages.  packages.
86    
87  \subsection{Packages are Not Libraries}  \subsubsection{Packages are Not Libraries}
88    
89  To a beginner, the MITgcm packages may resemble libraries as used in  To a beginner, the MITgcm packages may resemble libraries as used in
90  myriad software projects.  While future versions are likely to  myriad software projects.  While future versions are likely to
# Line 88  implement packages as libraries (perhaps Line 92  implement packages as libraries (perhaps
92  the current packages (FORTRAN77) are \textbf{not} based upon any  the current packages (FORTRAN77) are \textbf{not} based upon any
93  concept of libraries.  concept of libraries.
94    
95  \subsubsection{File ``Hiding'' Rules}  \subsubsection{File Inclusion Rules}
96    
97  Instead, packages should be viewed only as directories containing  Instead, packages should be viewed only as directories containing
98  ``sets of source files'' that are built using some simple mechanisms  ``sets of source files'' that are built using some simple mechanisms
# Line 111  files as they are found and proceeds acc Line 115  files as they are found and proceeds acc
115      previously encountered) then the file within the newer (more      previously encountered) then the file within the newer (more
116      recently visited) package will superseed (or ``hide'') any      recently visited) package will superseed (or ``hide'') any
117      previous file(s) with the same name.      previous file(s) with the same name.
118        
119    \item Packages are visited (and thus files discovered) {\it in the    \item Packages are visited (and thus files discovered) {\it in the
120        order that the packages are enabled} within \texttt{genmake2}.        order that the packages are enabled} within \texttt{genmake2}.
121      Thus, the files in \texttt{PackB} may superseed the files in      Thus, the files in \texttt{PackB} may superseed the files in
122      \texttt{PackA} if \texttt{PackA} is enabled before      \texttt{PackA} if \texttt{PackA} is enabled before \texttt{PackB}.
123      \texttt{PackB}.  Thus, package ordering can be significant!      Thus, package ordering can be significant!  For this reason,
124        \texttt{genmake2} honors the order in which packages are
125        specified.
126    \end{enumerate}    \end{enumerate}
127  \end{enumerate}  \end{enumerate}
128    
# Line 157  An example illustrating the use of these Line 163  An example illustrating the use of these
163  \end{verbatim}  \end{verbatim}
164  which is included from the file  which is included from the file
165  \filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F}  \filelink{calc\_diffusivity.F}{model-src-calc_diffusivity.F}
166    and shows how both the compile--time \texttt{ALLOW\_GMREDI} flag and the
167    run--time \texttt{useGMRedi} are nested.
168    
169  There are some benefits to using this technique.  The first is that  There are some benefits to using the technique described here.  The
170  code snippets or subroutines associated with packages can be placed or  first is that code snippets or subroutines associated with packages
171  called from almost anywhere else within the code.  The second benefit  can be placed or called from almost anywhere else within the code.
172  is related to the memory footprint and performance.  Since unused code  The second benefit is related to memory footprint and performance.
173  can be removed, there is no performance penalty due to unnecessary  Since unused code can be removed, there is no performance penalty due
174  memory allocation or unused function calls.  The major problems with  to unnecessary memory allocation, unused function calls, or extra
175  this approach are difficult-to-read and difficult-to-test code caused  run-time \texttt{IF (...)} conditions.  The major problems with this
176  by the numerous CPP statements.  Developers should exerecise some  approach are the potentially difficult-to-read and difficult-to-debug
177  discipline and avoid ``smearing'' implementation details across  code caused by an overuse of CPP statements.  So while it can be done,
178  numerous files in a haphazard fashion.  developers should exerecise some discipline and avoid unnecesarily
179    ``smearing'' their package implementation details across numerous
180    files.
181    
182    
183    \subsubsection{Package Startup or Boot Sequence}
184    
185    Calls to package routines within the core code timestepping loop can
186    vary.  However, all packages should follow a required "boot" sequence
187    outlined here:
188    
189    {\footnotesize
190  \subsection{Interfaces}  \begin{verbatim}
191        1. S/R PACKAGES_BOOT()
192                :
193            CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
194    
195    
196        2. S/R PACKAGES_READPARMS()
197                :
198            #ifdef ALLOW_${PKG}
199              if ( use${Pkg} )
200         &       CALL ${PKG}_READPARMS( retCode )
201            #endif
202    
203        3. S/R PACKAGES_INIT_FIXED()
204                :
205            #ifdef ALLOW_${PKG}
206              if ( use${Pkg} )
207         &       CALL ${PKG}_INIT_FIXED( retCode )
208            #endif
209    
210        4. S/R PACKAGES_CHECK()
211                :
212            #ifdef ALLOW_${PKG}
213              if ( use${Pkg} )
214         &       CALL ${PKG}_CHECK( retCode )
215            #else
216              if ( use${Pkg} )
217         &       CALL PACKAGES_CHECK_ERROR('${PKG}')
218            #endif
219    
220        5. S/R PACKAGES_INIT_VARIABLES()
221                :
222            #ifdef ALLOW_${PKG}
223              if ( use${Pkg} )
224         &       CALL ${PKG}_INIT_VARIA( )
225            #endif
226    
227         6. S/R DO_THE_MODEL_IO
228    
229            #ifdef ALLOW_${PKG}
230              if ( use${Pkg} )
231         &       CALL ${PKG}_DIAGS( )
232            #endif
233    
234         7. S/R PACKAGES_WRITE_PICKUP()
235    
236            #ifdef ALLOW_${PKG}
237              if ( use${Pkg} )
238         &       CALL ${PKG}_WRITE_PICKUP( )
239            #endif\end{verbatim}
240    }
241    
242    
243    \subsubsection{Adding a package to PARAMS.h and  packages\_boot()}
244    
245    An MITgcm package directory contains all the code needed for that package apart
246    from one variable for each package. This variable is the {\tt use\$\{Pkg\} }
247    flag. This flag, which is of type logical, {\bf must} be declared in the
248    shared header file {\it PARAMS.h} in the {\it PARM\_PACKAGES} block. This
249    convention is used to support a single runtime control file {\it data.pkg}
250    which is read by the startup routine {\it packages\_boot()} and that sets a
251    flag controlling the runtime use of a package. This routine needs to be able to
252    read the flags for packages that were not built at compile time. Therefore
253    when adding a new package, in addition to creating the per-package directory
254    in the {\it pkg/} subdirectory a developer should add a {\tt use\$\{Pkg\} }
255    flag to {\it PARAMS.h} and a {\tt use\$\{Pkg\} } entry to the
256    {\it packages\_boot()} {\it PACKAGES} namelist.
257    The only other package specific code that should appear outside the individual
258    package directory are calls to the specific package API.
259    
260    
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.6
  ViewVC Help
Powered by ViewVC 1.1.22