/[MITgcm]/MITgcm/doc/devel_HOWTO.sgml
ViewVC logotype

Annotation of /MITgcm/doc/devel_HOWTO.sgml

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


Revision 1.18 - (hide annotations) (download) (as text)
Tue Dec 19 18:38:40 2017 UTC (6 years, 5 months ago) by jmc
Branch: MAIN
Changes since 1.17: +3 -3 lines
File MIME type: text/x-sgml
update links to MITgcm mailing list

1 edhill 1.1 <!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
2 jmc 1.13 <!--
3 jmc 1.18 $Header: /u/gcmpack/MITgcm/doc/devel_HOWTO.sgml,v 1.17 2012/05/16 02:33:48 jmc Exp $
4 jmc 1.13 $Name: $
5     -->
6 edhill 1.1
7     <article id="MITgcm-Development-HOWTO">
8    
9     <articleinfo>
10     <title>MITgcm Development HOWTO</title>
11    
12     <author>
13     <firstname>Ed</firstname>
14     <surname>Hill III</surname>
15     <affiliation>
16     <address><email>eh3@mit.edu</email></address>
17     </affiliation>
18     </author>
19    
20     <revhistory>
21     <revision>
22     <revnumber>0.01</revnumber>
23 edhill 1.2 <date>2003-08-07</date>
24 edhill 1.1 <authorinitials>eh3</authorinitials>
25     <revremark>
26     Initial version.
27     </revremark>
28     </revision>
29 jmc 1.10 <revision>
30     <revnumber>0.02</revnumber>
31     <date>2010-01-21</date>
32     <authorinitials>jmc</authorinitials>
33     <revremark>
34 jmc 1.16 Update links.
35 jmc 1.10 </revremark>
36     </revision>
37 jmc 1.11 <revision>
38     <revnumber>0.03</revnumber>
39     <date>2010-04-25</date>
40     <authorinitials>jmc</authorinitials>
41     <revremark>
42     Add subsection "Developer settings" (under CVS Repository).
43     </revremark>
44     </revision>
45 jmc 1.16 <revision>
46     <revnumber>0.04</revnumber>
47     <date>2011-04-24</date>
48     <authorinitials>jmc</authorinitials>
49     <revremark>
50     Update subsection "The verification suite".
51     </revremark>
52     </revision>
53 edhill 1.1 </revhistory>
54    
55     <abstract>
56     <para>This document describes how to develop software for the
57     MITgcm project.</para>
58     </abstract>
59     </articleinfo>
60    
61     <sect1 id="intro">
62     <title>Introduction</title> <para>The purpose of this document is
63     to help new developers get "up to speed" with MITgcm
64     development.</para>
65     <sect2>
66     <title>New Versions of This Document</title> <para>You can
67     obtain the latest version of this document <ulink
68 jmc 1.10 url="http://mitgcm.org/public/docs.html">online</ulink> in
69 edhill 1.1 various formats.</para>
70     </sect2>
71     <sect2>
72     <title>Feedback and corrections</title> <para>If you have
73     questions or comments about this document, please feel free to
74     <ulink url="mailto:MITgcm-support@mitgcm.org">contact the
75     authors</ulink>.
76     </para>
77     </sect2>
78     </sect1>
79    
80     <sect1 id="background">
81     <title>Background</title>
82    
83     <sect2>
84     <title>User Manual</title>
85    
86 edhill 1.5 <para>Before jumping into development, please familiarize yourself with
87 jmc 1.10 the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
88 edhill 1.5 </ulink>. This document contains volumes of useful information and is
89     included here by reference.</para>
90 edhill 1.1
91 edhill 1.5 <!--
92     <para>Also, a "snapshot" or <ulink
93 edhill 1.1 url="http://mitgcm.org/dev_docs/">development version</ulink> of
94     the user manual may be available, though this is only put on the
95     web for testing purposes.</para>
96 edhill 1.5 -->
97 edhill 1.1 </sect2>
98    
99     <sect2>
100     <title>Prerequisites</title> <para>To develop for MITgcm project
101     you will need a UNIX or UNIX-like set of build tools including
102     the following:</para>
103     <blockquote>
104     <simplelist type="inline">
105     <member>CVS client</member>
106     <member>make or (preferably) GNU make</member>
107     <member>FORTRAN compiler</member>
108     <member>C compiler</member>
109     <member>[ba]sh and [t]csh shells</member>
110     <member>PERL</member>
111     <member>LaTeX and LaTeX2HTML</member>
112     </simplelist>
113     </blockquote>
114     <para>Essentially all of the work described here has been tested
115     on recent versions of Red Hat Linux (eg. 7.3 through 9). Except
116     where noted, all shell commands will be provided using bash
117     syntax.
118     </para>
119     </sect2>
120    
121     </sect1>
122    
123     <sect1 id="cvs">
124     <title>CVS Repository</title>
125 jmc 1.11
126 edhill 1.1 <sect2>
127     <title>Layout</title>
128    
129     <para>Unlike many open source projects, the MITgcm CVS tree does
130     not follow a simple "src", "docs", "share", and "test" directory
131     layout. Instead, there are multiple higher-level directories
132     that each, to some extent, depend upon the presence of the
133     others. The tree currently resembles:</para>
134    
135     <programlisting>gcmpack/
136 jmc 1.11 CVSROOT -hidden-
137 edhill 1.1
138     MITgcm code
139 jmc 1.11 bin empty
140     doc basic developpment documentation
141     eesupp execution environment support code (wrapper)
142     exe empty
143 jmc 1.16 jobs runtime shell scripts for
144 jmc 1.11 various platforms (not maintained)
145     lsopt line search
146     model main dynamics (core)
147     optim line search interface
148     pkg alternate and optional numerics, etc.
149     tools scripts to build (and test)
150     utils pre/post processing tools (matlab, ..)
151     verification standard regression tests + examples
152     + documented examples (tutorials)
153     tutorial_examples (only in release1 branch)
154 edhill 1.1
155 jmc 1.11 MITgcm_contrib contributed code
156 edhill 1.1
157 jmc 1.11 acesgrid.org build acesgrid web site
158     development experimental stuff
159     gfd_lab -?-
160 jmc 1.13 manual source of MITgcm documentation
161 edhill 1.1 mitgcm.org build web site
162 jmc 1.16 old_develop old and early development source
163 jmc 1.13 misc -?-
164     models -?-
165     packages -?-
166     preprocess -?-
167 jmc 1.11 pdfs some pdfs
168     planetinabottle.org unfinished web site
169     www.ecco-group.org build ecco web site ?
170 edhill 1.1 </programlisting>
171    
172 jmc 1.11 <!--
173 edhill 1.1 <para>Efforts are underway to reduce the complexity.</para>
174 jmc 1.11 -->
175 edhill 1.1
176     </sect2>
177    
178     <!--
179     <sect2>
180     <title>Releases</title> <para>Currently, there are two main
181     branches:</para>
182     <itemizedlist mark="bullet">
183     <listitem>
184     <para>Development</para>
185     <itemizedlist mark="bullet">
186     <listitem>
187     <para>MAIN</para>
188     </listitem>
189     <listitem>
190     <para>ecco-branch</para>
191     </listitem>
192     </itemizedlist>
193     </listitem>
194     <listitem>
195     <para>Production</para>
196     <itemizedlist mark="bullet">
197     <listitem>
198     <para>Release1</para>
199     </listitem>
200     <listitem>
201     <para>Release2</para>
202     </listitem>
203     </itemizedlist>
204     </listitem>
205     </itemizedlist>
206     </sect2>
207     -->
208    
209     <sect2>
210     <title>Branches</title>
211    
212     <para>As shown in the online <ulink
213 jmc 1.11 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?view=graph">
214 dimitri 1.12 ViewCVS-generated tree</ulink>, the MITgcm codebase is split into
215     branches or "lines" under which development proceeds. The main line
216     of development is referred to as the "MAIN" version of the code.
217 edhill 1.1 </para>
218    
219     <para>Periodically, a "Release" branch is formed from the "MAIN"
220 edhill 1.7 development branch. This is done in order to create a relatively stable
221     reference point for both users and developers. The intent is that once a
222 dimitri 1.12 release branch has been created, only bug-fixes will be added to it.
223 edhill 1.7 Meanwhile, development (which might "break" or otherwise render invalid
224     the documentation, tutorials, and/or examples contained within a release
225 dimitri 1.12 branch) is allowed to continue along the MAIN line.</para>
226 edhill 1.1 </sect2>
227    
228     <sect2>
229 jmc 1.11 <title> Developer settings </title>
230    
231 jmc 1.16 <para>CVS is a convenient tool to keep up-to-date a personal copy of the
232     MITgcm code (see: <ulink url="http://mitgcm.org/public/using_cvs.html">
233     using CVS </ulink>). The same tool is used by developers to
234 jmc 1.11 incorporate any change into the repository. However, this later
235 jmc 1.17 function requires specific settings, as detailed here after</para>
236 jmc 1.11 <orderedlist>
237     <listitem>
238 jmc 1.17 <para> You will need an account (login access) to the server
239     "mitgcm.org" (curently: <filename>forge.csail.mit.edu</filename>)
240     with the proper group setting (e.g., group "gcmctrb" to add/modify
241     code into MITgcm_contrib).
242     This kind of account is granted only upon well motivated request
243     (we recommend to ask your senior MITgcm-collaborator to send such
244     request to marshall-admin at techsquare.com with Cc to Chris Hill
245     for approval).</para>
246     <para> The access to the server <filename>mitgcm.org</filename> is
247     through ssh-key authorization which will need to be set properly on
248     both side (on your local machine and on your server account).
249     You need to be able to ssh to <filename>mitgcm.org</filename>
250     (or <filename>ssh MY_USER_NAME@mitgcm.org</filename>
251     in case of different user-name on both sides) to proceed further.</para>
252 jmc 1.11 </listitem>
253    
254     <listitem>
255 jmc 1.16 <para> You need to register to the
256 jmc 1.18 <ulink url="http://mailman.mitgcm.org/mailman/listinfo/mitgcm-cvs">
257 jmc 1.17 mitgcm-cvs </ulink> mailing list.
258 jmc 1.16 This ensures that other developers will receive email notification
259 jmc 1.17 when you make changes; you will also receive such email
260 jmc 1.11 when others make changes to the repository.
261     </para>
262     </listitem>
263    
264     <listitem>
265 jmc 1.16 <para> It is highly recommended that you register also to the
266 jmc 1.18 <ulink url="http://mailman.mitgcm.org/mailman/listinfo/mitgcm-devel">
267 jmc 1.17 mitgcm-devel </ulink> mailing list (expect a short delay for
268 jmc 1.11 this request to be processed).
269     This list is intended for developer discussions.
270     </para>
271     </listitem>
272    
273     <listitem>
274 jmc 1.17 <para> The standard CVS-anonymous mode (using "cvsanon",
275     as mentionned <ulink url="http://mitgcm.org/public/source_code.html">
276     here </ulink>) does not provide check-in ("cvs commit") permission.
277 jmc 1.11 Instead, you will need to set our CVS environment as follow:</para>
278     <screen>
279     $ export CVS_RSH=ssh
280     $ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
281     </screen>
282 jmc 1.17 <para> The reason for such limitation is that when downloading a directory,
283     e.g.: <filename>myCopy</filename>, from the CVS repository (e.g.,
284 jmc 1.11 <filename>MITgcm_contrib/thisPart</filename>) using the command:</para>
285     <screen>
286     $ cvs co -P -d myCopy MITgcm_contrib/thisPart
287     </screen>
288 jmc 1.16 <para> the type of CVS environment which has been used
289 jmc 1.17 is stored in the file <filename>myCopy/CVS/Root</filename>.
290     This prevent to re-use, for cvs-commit purpose,
291 jmc 1.16 a cvs local copy (<filename>myCopy</filename>) which was obtained
292 jmc 1.11 using the CVS anonymous mode.</para>
293     </listitem>
294    
295     <listitem>
296 jmc 1.16 <para> At this stage, you should be able to send your modified source
297     file (e.g., <filename>src_file</filename>) from your local copy directory
298 jmc 1.11 (<filename>myCopy</filename>) to the CVS repository
299     (<filename>MITgcm_contrib/thisPart</filename>) using the command
300     "cvs commit":</para>
301     <screen>
302     $ cd myCopy
303     $ cvs -n update (optional; check if new changes have been made)
304     $ cvs diff src_file (optional; list your changes)
305     $ cvs commit src_file
306     </screen>
307 jmc 1.16 <para> It is essential that you provide a short description of the
308     changes you made to <filename>src_file</filename> as you check-in
309     this file (the "cvs commit" command automatically opens your standard
310 jmc 1.11 editor for this purpose).</para>
311 jmc 1.17 <para> Note:
312     Please ignore the following warnings that the "cvs commit" command
313     produces if you are not part of the "gcmpack" group:
314     <screen>
315     cvs commit: failed to create lock directory for `/u/gcmpack/CVSROOT'
316     (/u/gcmpack/CVSROOT/#cvs.history.lock): Permission denied
317     cvs commit: failed to obtain history lock in repository `/u/gcmpack'
318     </screen>
319     These warnings are not affecting the changes you made to the CVS repository.
320     </para>
321 jmc 1.11 </listitem>
322    
323     </orderedlist>
324    
325     </sect2>
326    
327     <sect2>
328     <title>Main code development</title>
329 jmc 1.14 <para><emphasis>(formerly named "Tagging" ; this section needs an update)
330     </emphasis></para>
331 edhill 1.1
332 edhill 1.7 <para>The intent of tagging is to create "known-good" checkpoints that
333     developers can use as references. Traditionally, MITgcm tagging has
334     maintained the following conventions:</para>
335 edhill 1.1
336     <orderedlist>
337     <listitem>
338 edhill 1.7 <para>Developer checks out code into a local CVS-managed directory,
339     makes various changes/additions, tests these edits, and eventually
340     reaches a point where (s)he is satisfied that the changes form a new
341     "useful" point in the evolution of the code.</para>
342 edhill 1.1 </listitem>
343    
344     <listitem>
345     <para>The developer then runs the <ulink
346 jmc 1.10 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
347     testreport</ulink> shell script to see if any problems are introduced.
348 edhill 1.7 While not intended to be exhaustive, the test cases within the
349     verification directory do provide some indication whether gross errors
350     have been introduced.
351 edhill 1.1 </para>
352     </listitem>
353    
354     <listitem>
355     <para>Having satisfied him- or herself that the changes are
356     ready to be committed to the CVS repository, the developer
357     then:</para>
358     <orderedlist>
359     <listitem>
360 edhill 1.7 <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
361     number and Y is a letter) to the <ulink
362 jmc 1.10 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">
363 edhill 1.7 tag-index</ulink> file and checks it into the CVS
364     repository</para>
365 edhill 1.1 </listitem>
366     <listitem>
367 edhill 1.7 <para>submits the set of changes to the CVS repository and adds
368     comments to <filename>tag-index</filename> describing what the
369     changes are along with a matching "checkpointXY_post" entry</para>
370 edhill 1.1 </listitem>
371     </orderedlist>
372     </listitem>
373     </orderedlist>
374    
375 edhill 1.7 <para>The result of this tagging procedure is a sequence of development
376     checkpoints with comments which resembles:</para>
377 edhill 1.1
378     <programlisting>
379     checkpoint50e_post
380     o make KPP work with PTRACERS
381     - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is
382     nearly a copy of kpp_transport_s
383 jmc 1.16 - there is no analogue to SurfaceTendencyS, so I have to use
384 edhill 1.1 gPtr(of the surface layer) instead
385     o add a new platform SunFire+mpi (SunFire 15000) to genmake
386     checkpoint50e_pre
387    
388     checkpoint50d_post
389 jmc 1.16 o change kpp output from multiple-record state files to single-record state
390 edhill 1.1 files analogous to write_state.F
391 jmc 1.16 o reduce the output frequency of cg3d-related stuff to the monitor frequency,
392     analogous to the cg2d-related output.
393     o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
394 edhill 1.1 so that writing to internal file fn (with length 512) fails.
395     checkpoint50d_pre
396     </programlisting>
397    
398 edhill 1.7 <para>This information can be used to refer to various stages of the code
399     development. For example, bugs can be traced to individual sets of CVS
400     checkins based upon their first appearance when comparing the results from
401     different checkpoints.</para>
402 edhill 1.1
403     </sect2>
404     </sect1>
405    
406    
407 edhill 1.2 <sect1 id="coding">
408 edhill 1.3 <title>Coding for MITgcm</title>
409    
410     <sect2 id="build_tools">
411     <title>Build Tools</title>
412    
413 edhill 1.4 <para>Many Open Source projects use the "GNU Autotools" to help streamline
414     the build process for various Unix and Unix-like architectures. For a
415     user, the result is the common "configure" (that is,
416     "<filename>./configure && make && make install</filename>") commands.
417     For MITgcm, the process is similar. Typical commands are:</para>
418 edhill 1.3
419     <screen>
420 jmc 1.14 $ genmake2 -mods=../code
421 edhill 1.5 $ make depend
422     $ make
423 edhill 1.3 </screen>
424    
425 edhill 1.4 <para>The following sections describe the individual steps in the build
426     process.</para>
427 jmc 1.16
428 edhill 1.3 <sect3 id="genmake">
429     <title>The <filename>genmake2</> Utility</title>
430    
431 jmc 1.14 <para><emphasis>(Note: the older <filename>genmake</>
432     has been replaced by <filename>genmake2</>)</emphasis></para>
433 edhill 1.4
434     <para>The first step in any MITgcm build is to create a Unix-style
435     <filename>Makefile</filename> which will be parsed by
436     <filename>make</filename> to specify how to compile the MITgcm source
437     files. For more detailed descriptions of what the make tools are and
438     how they are used, please see:</para>
439 edhill 1.3
440     <itemizedlist>
441     <listitem>
442 edhill 1.4 <para><ulink url="http://www.gnu.org/software/make/make.html">
443     http://www.gnu.org/software/make/make.html</></para>
444 edhill 1.3 </listitem>
445     <listitem>
446 edhill 1.4 <para><ulink url="http://www.oreilly.com/catalog/make2/">
447     http://www.oreilly.com/catalog/make2/</></para>
448 edhill 1.3 </listitem>
449     </itemizedlist>
450    
451 edhill 1.4 <para>Genmake can often be invoked successfully with a command line as
452     simple as:</para>
453    
454     <screen>
455 edhill 1.5 $ genmake2 -mods=../code
456 edhill 1.4 </screen>
457    
458     <para>However, some systems (particularly commercial Unixes that lack a
459     more modern "/bin/sh" implementation or that have shells installed in
460     odd locations) may require an explicit shell invocation such as one of
461     the following: </para>
462    
463     <screen>
464 edhill 1.5 $ /usr/bin/sh genmake2 -make=gmake -mods=../code
465     $ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
466 edhill 1.4 </screen>
467    
468     <para>The genmake2 code has been written in a Bourne and BASH (v1)
469     compatible syntax so it should work with most "sh" and all recent "bash"
470     implementations.</para>
471    
472     <para>As the name implies, <filename>genmake2</filename> generates a
473     <filename>Makefile</filename>. It does so by first parsing the
474     information supplied from the following sources</para>
475 edhill 1.3
476     <orderedlist>
477     <listitem>
478 jmc 1.6 <para>a <filename>gemake_local</filename> file in the current
479 edhill 1.4 directory</para>
480 edhill 1.3 </listitem>
481     <listitem>
482     <para>directly from command-line options</para>
483     </listitem>
484     <listitem>
485 edhill 1.4 <para>an "options file" as specified by the command-line option
486     <filename>-optfile='FILENAME'</filename></para>
487 edhill 1.3 </listitem>
488 jmc 1.14 <listitem>
489     <para> a <filename>packages.conf</filename> file (in the current
490     directory or in one of the "MODS" directories, see below)
491     which contains the specific list of packages to compile
492     </para>
493     </listitem>
494 edhill 1.3 </orderedlist>
495    
496 edhill 1.4 <para>then checking certain dependency rules (the package dependencies),
497     and finally writing a <filename>Makefile</filename> based upon the
498     source code that it finds. For convenience within various Unix
499     shells, <filename>genmake2</> supports both "long"- and "short"-style
500     options. A complete list of the available options can be obtained
501     from:</para>
502 edhill 1.3
503     <screen>
504 edhill 1.5 $ genmake2 -help
505 edhill 1.3 </screen>
506    
507 edhill 1.4 <para>The most important options for <filename>genmake2</> are:</para>
508 edhill 1.3
509     <variablelist>
510    
511     <varlistentry>
512     <term><filename>--optfile=/PATH/FILENAME</></term>
513 edhill 1.4
514 edhill 1.3 <listitem>
515 edhill 1.4 <para>This specifies the "options file" that should be used for a
516     particular build. The options file is a convenient and
517     machine-indepenent way of specifying parameters such as the
518     FORTRAN compiler (<filename>FC=</>), FORTRAN compiler
519     optimization flags (<filename>FFLAGS=</>), and the locations of
520     various platform- and/or machine-specific tools
521     (eg. <filename>MAKEDEPEND=</>). As with <filename>genmake2</>,
522     all options files should be written to be compatible with
523     Bourne--shell ("sh" or "BASH v1") syntax. Examples of various
524     options files can be found in
525     <filename>$ROOTDIR/tools/build_options</>.</para>
526    
527     <para>If no "optfile" is specified (either through the command lin
528     or the environment variable), genmake2 will try to make a
529     reasonable guess from the list provided in
530     <filename>$ROOTDIR/tools/build_options</>. The method used for
531     making this guess is to first determine the combination of
532     operating system and hardware (eg. "linux_ia32") and then find a
533     working Fortran compiler within the user's path. When these
534     three items have been identified, genmake2 will try to find an
535     optfile that has a matching name. </para>
536    
537     <para>Everyone is encouraged to submit their options files to the
538     MITgcm project for inclusion (please send to
539     <email>MITgcm-support@mitgcm.org</email>). We are particularly
540     grateful for options files tested on new or unique
541     platforms!</para>
542 edhill 1.3 </listitem>
543 edhill 1.4
544 edhill 1.3 </varlistentry>
545    
546     <varlistentry>
547 edhill 1.5 <term><filename>-adof=/path/to/file</></term>
548     <term><filename>-adoptfile=/path/to/file</></term>
549     <listitem>
550     <para>This option specifies the "adjoint" or automatic
551     differentiation options file to be used. The file is analogous
552     to the "optfile" defined above but it specifies information for
553     the AD build process. The default file is located in <filename>
554     $ROOTDIR/tools/adjoint_options/adjoint_default </> and it
555     defines the "TAF" and "TAMC" compilers. An alternate version is
556     also available at <filename>
557     $ROOTDIR/tools/adjoint_options/adjoint_staf </> that selects the
558     newer "STAF" compiler. As with any compilers, it is helpful to
559     have their directories listed in your $PATH environment
560     variable.</para>
561     </listitem>
562     </varlistentry>
563    
564     <varlistentry>
565 edhill 1.4 <term><filename>-mods=DIR</></term>
566     <term><filename>-mods='DIR1 [DIR2 ...]'</></term>
567 edhill 1.3 <listitem>
568 edhill 1.4 <para>This option specifies a list of directories containing
569     "modifications". These directories contain files with names
570     that may (or may not) exist in the main MITgcm source tree but
571     will be overridden by any identically-named sources within the
572     "MODS" directories. The order of precedence for this
573     "name-hiding" is as follows:</para>
574     <itemizedlist>
575     <listitem><para>"MODS" directories (in the order given)
576     </para></listitem>
577     <listitem><para>Packages either explicitly specified or
578     provided by default (in the order given)</para></listitem>
579     <listitem><para>Packages included due to package dependencies
580 jmc 1.16 (in the order that that package dependencies are
581 edhill 1.4 parsed)</para></listitem>
582     <listitem><para>The "standard dirs" (which may have been
583     specified by the "-standarddirs" option)</para></listitem>
584     </itemizedlist>
585 jmc 1.14 </listitem>
586     </varlistentry>
587    
588     <varlistentry>
589     <term><filename>-pgroups=/PATH/FILENAME</></term>
590     <listitem>
591     <para>This option specifies the file where package groups are
592     defined. If not set, the package-groups definition will
593     be read from
594     <filename>$ROOTDIR/pkg/pkg_groups</>.</para>
595     <para>
596     It also contains the default list of packages (defined
597     as the group <filename>"default_pkg_list"</>) which is used
598     when no specific package list (file: <filename>packages.conf</>)
599     is found in current directory or in any "MODS" directory.
600     </para>
601     </listitem>
602     </varlistentry>
603 edhill 1.4
604 jmc 1.14 <varlistentry>
605     <term><filename>-pdepend=/PATH/FILENAME</></term>
606    
607     <listitem>
608     <para>This specifies the dependency file used for packages. If
609     not specified, the default dependency file is
610     <filename>$ROOTDIR/pkg/pkg_depend</>. The syntax for this file is
611     parsed on a line-by-line basis where each line containes either a
612     comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
613     where the "+" or "-" symbol specifies a "must be used with" or a
614     "must not be used with" relationship, respectively. If no rule is
615     specified, then it is assumed that the two packages are compatible
616     and will function either with or without each other.</para>
617 edhill 1.4 </listitem>
618     </varlistentry>
619    
620     <varlistentry>
621     <term><filename>-make=/path/to/gmake</></term>
622     <listitem>
623     <para>Due to the poor handling of soft-links and other bugs common
624     with the <filename>make</> versions provided by commercial Unix
625     vendors, GNU <filename>make</filename> (sometimes called
626     <filename>gmake</filename>) should be preferred. This option
627     provides a means for specifying the make program to be
628     used.</para>
629 edhill 1.3 </listitem>
630     </varlistentry>
631    
632     </variablelist>
633    
634 edhill 1.4 <para>A successful run of <filename>genmake2</> will produce a
635     <filename>Makefile</>, a <filename>PACKAGES_CONFIG.h</> file, and
636     various convenience files used for the automatic differentiation
637     process.</para>
638    
639     <para>In general, it is best to use <filename>genmake2</> on a "clean"
640     directory that is free of all source (*.[F,f],*.[F,f]90) and header
641     (*.h,*.inc) files. Generally, this can be accomplished in an
642 jmc 1.14 "un-clean" directory by running "make Clean" followed by "make
643 edhill 1.4 makefile".</para>
644 edhill 1.3
645     </sect3>
646    
647     <sect3 id="makefile_use">
648 edhill 1.5 <title>Using the <filename>Makefile</></title>
649 edhill 1.3
650 edhill 1.5 <para>Once a <filename>Makefile</> has been created using
651     <filename>genmake2</>, one can build a "standard" (forward
652     simulator) executable using:</para>
653 edhill 1.3
654     <screen>
655 jmc 1.14 $ make Clean
656 edhill 1.5 $ make depend
657     $ make
658 edhill 1.3 </screen>
659    
660 jmc 1.14 <para>The "make Clean" step will remove any stale source files, include
661 edhill 1.4 files, and links. It is strongly recommended for "un-clean"
662     directories which may contain the (perhaps partial) results of
663 jmc 1.14 previous builds. Such "debris" can interfere with the next stage of
664 jmc 1.16 the build.
665     A more agressive cleaning option, "make CLEAN", can be used to also
666 jmc 1.14 remove the executable and output files from a previous run.</para>
667 edhill 1.4
668     <para>The "make depend" step will create a large number of symbolic
669     links from the local directory to the source file locations. It also
670     parses these files and creates an extensive list of dependencies
671     within the <filename>Makefile</> itself. The links that exist at this
672     stage are mostly "large F" files (*.F and *.F90) that need to be
673     processed by a C preprocessor ("CPP"). Since "make depend" edits the
674     <filename>Makefile</>, it is important not to skip this step!</para>
675    
676     <para>The final "make" invokes the C preprocessor to produce the "little
677     f" files (*.f and *.f90) and then compiles them to object code using
678     the specified FORTRAN compiler and options. An intermediate script is
679     often used during this stage to further process (usually, make simple
680     substitutions) custom definitions such as variable types within the
681     source files. This additional stage is necessary in order to overcome
682     some of the inconsistencies in the sizes of objects (bytes) between
683 edhill 1.5 different compilers. The result of the build process is an executable
684     with the name <filename>mitgcmuv</>.</para>
685    
686     <para>In addition to the forward simulator described above, the
687     <filename>Makefile</> also has a number of targets that can be used to
688     produce various adjoint and tangent-linear builds for optimization and
689     other parameter-sensitivity problems. The additional targets within
690     the <filename>Makefile</> are:</para>
691    
692     <variablelist>
693    
694     <varlistentry>
695     <term><filename>make adall</></term>
696     <listitem>
697     <para>This target produces an <filename>mitgcmuv_ad</> executable
698     using the <filename>taf</> or <filename>staf</> adjoint
699 jmc 1.16 compiler. See the <filename>genmake2</> "-adof" option for
700 edhill 1.5 compiler selection.</para>
701     </listitem>
702     </varlistentry>
703    
704     <varlistentry>
705     <term><filename>make ftlall</></term>
706     <listitem>
707     <para>Similar to <filename>make adall</> above, this
708     produces...</para>
709     </listitem>
710     </varlistentry>
711    
712     </variablelist>
713 edhill 1.3
714 edhill 1.5 <para>Please report any compilation failures or other build problems to
715     the <email>MITgcm-support@mitgcm.org</email> list.</para>
716 edhill 1.3
717     </sect3>
718    
719     </sect2>
720    
721     <sect2 id="verification">
722     <title>The Verification Suite</title>
723    
724 edhill 1.4 <para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
725 jmc 1.15 directory) includes many (> 90) examples intended for regression
726 jmc 1.16 testing. Each one of these test-experiment directories contains "known-good"
727 edhill 1.4 output files along with all the input (including both code and data
728 jmc 1.16 files) required for their re-calculation.
729     Also included in <filename>$ROOTDIR/verification/</> is the shell
730     script <filename>testreport</> to perform regression tests.</para>
731    
732     <sect3 id="test-experiment">
733     <title>Test-experiment Directory Content</title>
734    
735     <para> Each test-experiment directory (<filename>TESTDIR</>) contains
736     several standard subdirectories and files which <filename>testreport</>
737     recognizes and uses when running a regression test.
738     The directories/files that <filename>testreport</> uses are different
739     for a forward test and an adjoint test (<filename>testreport -adm</>)
740     and some test-experiments are set-up for only one type of regression
741     test whereas others allow both types of tests (forward and adjoint).</para>
742     <para>Also some test-experiment allows, using the same MITgcm executable,
743     to perform multiple tests using different parameters and input files,
744     with a primary input set-up
745     (<filename>input/ </> or <filename>input_ad/ </>)
746     and corresponding results (<filename>results/output.txt</> or
747     <filename>results/output_adm.txt</>) and with one or several secondary
748     inputs (<filename>input.OTHER/ </> or <filename>input_ad.OTHER/ </>)
749     and corresponding results (<filename>results/output.OTHER.txt </>
750     or <filename>results/output_adm.OTHER.txt</>).</para>
751     <variablelist>
752    
753     <varlistentry>
754     <term>directory <filename>TESTDIR/results/</></term>
755     <listitem>
756     <para>contains reference standard output used for test comparison.
757     <filename>results/output.txt</> and
758     <filename>results/output_adm.txt</>
759     correspond respectively to primary forward and adjoint test
760     run on the reference platform (currently
761     <filename>baudelaire.csail.mit.edu</>)
762     on one processor (no MPI, single thread)
763     using the reference compiler (curently the GNU fortran
764     compiler <filename>gfortran</>).
765     The presence of these files determines whether or not
766     <filename>testreport</> is testing or skipping
767     this test-experiment.
768     Reference standard output for secondary tests
769     (<filename>results/output.OTHER.txt</>
770     or <filename>results/output_adm.OTHER.txt</>) are
771     also expected here.</para>
772     <para>The test comparison involves few model variables output, which are,
773     by default and for a forward test, the 2-D solver initial residual
774     (<filename>cg2d_init_res</>) and 3-D state variables (T,S,U,V)
775     monitor output, and, by default and for an adjoint test, the
776     cost-function and gradient-check. However, some test-experiments
777     use some package-specific variable/monitor output according to
778     the file <filename>TESTDIR/input[_ad][.OTHER]/tr_checklist</>
779     specification.</para>
780     </listitem>
781     </varlistentry>
782    
783     <varlistentry>
784     <term>directory <filename>TESTDIR/build/</></term>
785     <listitem>
786     <para> initially empty directory where <filename>testreport</>
787     will build the MITgcm executable for forward and adjoint test.
788     It might contains an experiment specific
789     <filename>genmake_local</> file (see <xref linkend="genmake">).
790     </para>
791     <para> Note that the original <filename>code[_ad]/SIZE.h_mpi</>
792     is not directly used as "SIZE.h" to build an MPI-executable ;
793     instead, a local copy <filename>build/SIZE.h.mpi</> is derived
794     from <filename>code[_ad]/SIZE.h_mpi</>
795     by adjusting the number of processors (nPx,nPy) according to
796     <filename>NUMBER_OF_PROCS</> (see <xref linkend="testreport">,
797     <filename>testreport -MPI</>) ; then it is linked to "SIZE.h"
798     (<filename> ln -s SIZE.h.mpi SIZE.h </>) before building
799     the MPI-executable.</para>
800     </listitem>
801     </varlistentry>
802    
803     <varlistentry>
804     <term>directory <filename>TESTDIR/code/</></term>
805     <listitem>
806     <para>contains the test-experiment specific source code
807     used to build the MITgcm executable (<filename>mitgcmuv</>)
808     for forward-test (using <filename>genmake2 -mods=../code</>).
809     </para>
810     <para> It can also contain specific source files with the suffix
811     "<filename>_mpi</>" to be used
812     <!--
813     in the <filename>TESTDIR/build/</> directory
814     -->
815     in place of the corresponding file (without suffix)
816     for an MPI test (see <xref linkend="testreport">).
817     The presence or absence of <filename>SIZE.h_mpi</>
818     determines whether or not an MPI test on this
819     test-experiment is performed or skipped.</para>
820     </listitem>
821     </varlistentry>
822    
823     <varlistentry>
824     <term>directory <filename>TESTDIR/code_ad/</></term>
825     <listitem>
826     <para>contains the test-experiment specific source code
827     used to build the MITgcm executable (<filename>mitgcmuv_ad</>)
828     for adjoint-test (using <filename>genmake2 -mods=../code_ad</>).
829     It can also contain specific source files with the suffix
830     "<filename>_mpi</>" (see above).</para>
831     </listitem>
832     </varlistentry>
833    
834     <varlistentry>
835     <term>directory <filename>TESTDIR/input/</></term>
836     <listitem>
837     <para>contains the input and parameter files
838     used to run the primary forward test of this test-experiment.
839     </para>
840     <para>It can also contain specific parameter files with the suffix
841     "<filename>.mpi</>" to be used
842     <!--
843     in the <filename>TESTDIR/run/</> directory
844     -->
845     in place of the corresponding file (without suffix) for MPI
846     test, or with suffix "<filename>.mth</>" to be used for
847     multi-threaded test (see <xref linkend="testreport">).
848     The presence or absence of <filename>eedata.mth</>
849     determines whether or not a multi-threaded test on this
850     test-experiment is performed or skipped.</para>
851     <para>To save disk space and reduce downloading time, multiple
852     copies of the same input file is avoided by using a shell
853     script <filename>prepare_run</>.
854     When such a script is found in <filename>TESTDIR/input/ </>,
855     <filename>testreport</> run this script in directory
856     <filename>TESTDIR/run/ </> after linking all the input file
857     from <filename>TESTDIR/input/ </>.
858     </para>
859     </listitem>
860     </varlistentry>
861    
862     <varlistentry>
863     <term>directory <filename>TESTDIR/input_ad/</></term>
864     <listitem>
865     <para>contains the input and parameter files
866     used to run the primary adjoint test of this test-experiment.
867     It can also contain specific parameter files with the suffix
868     "<filename>.mpi</>" and shell script <filename>prepare_run</>
869     as described above.</para>
870     </listitem>
871     </varlistentry>
872    
873     <varlistentry>
874     <term>directory <filename>TESTDIR/input.OTHER/</></term>
875     <listitem>
876     <para>contains the input and parameter files
877     used to run the secondary OTHER forward test of this test-experiment.
878     It can also contain specific parameter files with suffix
879     "<filename>.mpi</>" or "<filename>.mth</>" and shell script
880     <filename>prepare_run</> (see above).</para>
881     <para> The presence or absence the file <filename>eedata.mth</>
882     determines whether or not a secondary multi-threaded test on this
883     test-experiment is performed or skipped.</para>
884     </listitem>
885     </varlistentry>
886    
887     <varlistentry>
888     <term>directory <filename>TESTDIR/input_ad.OTHER/</></term>
889     <listitem>
890     <para>contains the input and parameter files
891     used to run the secondary OTHER adjoint test of this test-experiment.
892     It can also contain specific parameter files with the suffix
893     "<filename>.mpi</>" and shell script <filename>prepare_run</>
894     (see above).</para>
895     </listitem>
896     </varlistentry>
897     <!--
898     -->
899     <varlistentry>
900     <term>directory <filename>TESTDIR/run/</></term>
901     <listitem>
902     <para> initially empty directory where <filename>testreport</>
903     will run the MITgcm executable for primary forward and adjoint
904     test.</para>
905     <para>Symbolic links (using command "<filename>ln -s</>") are made
906     for input and parameter files (from <filename>../input/ </>
907     or from <filename>../input_ad/ </>) and for MITgcm executable
908     (from <filename>../build/ </>) before the run proceeds.
909     The sequence of links (function <filename>linkdata</> within shell
910     script <filename>testreport</>) for a forward test is:</para>
911     <screen>
912     * link+rename or remove links
913     to special files with suffix ".mpi" or ".mth" from ../input/
914     * link files from ../input/
915     * execute ../input/prepare_run (if it exists)
916     </screen>
917     <para>The sequence for an ajoint test is similar, with
918     <filename>../input_ad/ </> replacing <filename>../input/ </>.
919     </para>
920     </listitem>
921     </varlistentry>
922    
923     <varlistentry>
924     <term>directory <filename>TESTDIR/tr_run.OTHER/</></term>
925     <listitem>
926     <para> directory created by <filename>testreport</>
927     to run the MITgcm executable for secondary "OTHER" forward
928     or adjoint test.</para>
929     <para> The sequence of links for a forward secondary test is:</para>
930     <screen>
931     * link+rename or remove links
932     to special files with suffix ".mpi" or ".mth" from ../input.OTHER/
933     * link files from ../input.OTHER/
934     * execute ../input.OTHER/prepare_run (if it exists)
935     * link files from ../input/
936     * execute ../input/prepare_run (if it exists)
937     </screen>
938     <para>The sequence for an ajoint test is similar, with
939     <filename>../input_ad.OTHER/ </> and <filename>../input_ad/ </>
940     replacing <filename>../input.OTHER/ </> and <filename>../input/ </>.
941     </para>
942     </listitem>
943     </varlistentry>
944    
945     </variablelist>
946     </sect3>
947 edhill 1.3
948     <sect3 id="testreport">
949     <title>The <filename>testreport</> Utility</title>
950    
951 jmc 1.16 <para> The shell script <filename>testreport</> (in
952     <filename>$ROOTDIR/verification/</>), which was written to work with
953     <filename>genmake2</>, can be used to build different versions
954     of the MITgcm code, run the various examples, compare the output,
955     and (if specified) email the results of each one of these tests to a
956     central repository.</para>
957 edhill 1.4
958     <para>On some systems, the testreport script can be run with a command
959     line as simple as:</para>
960    
961     <screen>
962 edhill 1.5 $ cd verification
963 jmc 1.15 $ ./testreport
964 edhill 1.4 </screen>
965    
966     <para>However, some systems (those lacking or wiht a broken "/bin/sh")
967     may require an explicit shell invocation such as:</para>
968    
969     <screen>
970 jmc 1.15 $ sh ./testreport -t 'exp2 exp4'
971     $ /some/path/to/bash ./testreport -t 'ideal_2D_oce lab_sea natl_box'
972 edhill 1.4 </screen>
973 edhill 1.3
974     <para>The <filename>testreport</> script accepts a number of
975 edhill 1.4 command-line options which can be listed using the <filename>-help</>
976     option. The most important ones are:</para>
977 edhill 1.3
978     <variablelist>
979    
980     <varlistentry>
981 jmc 1.15 <term><filename>-ieee</> (default) / <filename>-noieee</></term>
982 edhill 1.4 <listitem>
983     <para>If allowed by the compiler (as defined in the "optfile"),
984 jmc 1.16 use IEEE arithmetic (<filename>genmake2 -ieee</>).
985 jmc 1.15 This option, along with the gfortran / gcc compiler,
986     is how the standard results are produced.</para>
987     </listitem>
988     </varlistentry>
989    
990     <varlistentry>
991     <term><filename>-optfile=/PATH/FILENAME</></term>
992     <term><filename>-optfile '/PATH/F1 [/PATH/F2 ...]'</></term>
993     <listitem>
994     <para>This specifies a list of "options files" that will be passed
995     to <filename>genmake2</>. If multiple options files are used
996     (say, to test different compilers or different sets of options
997     for the same compiler), then each options file will be used with
998     each of the test directories.</para>
999 edhill 1.4 </listitem>
1000     </varlistentry>
1001    
1002     <varlistentry>
1003 edhill 1.3 <term><filename>-tdir TESTDIR</></term>
1004     <term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
1005     <listitem>
1006 edhill 1.4 <para>This option specifies the test directory or list of test
1007     directories that should be used. Each of these entries should
1008     exactly (note: they are case sensitive!) match the names of
1009 jmc 1.15 directories in <filename>$ROOTDIR/verification/</>. If this
1010 edhill 1.4 option is omitted, then all directories that are properly
1011     formatted (that is, containing an <filename>input</>
1012     sub-directory and a <filename>results/output.txt</> file) will
1013     be used.</para>
1014 edhill 1.3 </listitem>
1015     </varlistentry>
1016    
1017     <varlistentry>
1018     <term><filename>-addr EMAIL</></term>
1019     <term><filename>-addr 'EMAIL1 EMAIL2 [...]'</></term>
1020     <listitem>
1021     <para>Send the results (namely, <filename>output.txt</>,
1022 edhill 1.4 <filename>genmake_local</>, <filename>genmake_state</>, and
1023     <filename>Makefile</>) to the specified email addresses. The
1024     results are gzipped, placed in a tar file, MIME encoded, and
1025     sent to the specified address. If no email addresses are
1026     specified, no mail is sent.</para>
1027     </listitem>
1028     </varlistentry>
1029    
1030     <varlistentry>
1031 jmc 1.15 <term><filename>-MPI NUMBER_OF_PROCS</></term>
1032 edhill 1.4 <term><filename>-mpi</></term>
1033     <listitem>
1034 jmc 1.16 <para>If the necessary file (<filename>TESTDIR/code/SIZE.h_mpi</>)
1035 jmc 1.15 exists, then use it (and all <filename>TESTDIR/code/*_mpi</> files)
1036 jmc 1.16 for an MPI--enabled run. The new option (<filename>-MPI</> followed
1037     by the maximum number of processors) enable to build and run each
1038 jmc 1.15 test-experiment using variable number of MPI processors (multiple
1039 jmc 1.16 of <filename>nPx*nPy</> from <filename>TESTDIR/code/SIZE.h_mpi</>
1040     and not larger than <filename>NUMBER_OF_PROCS</>).
1041     The short option ("-mpi") can only be used to build and run on 2 MPI
1042     processors (equivalent to "<filename>-MPI 2</>").</para>
1043 jmc 1.15 <para>Note that the use of MPI typically requires a
1044 edhill 1.4 special command option (see "-command" below) to invoke the MPI
1045 jmc 1.15 executable. Examples of PBS scripts using testreport with MPI can be
1046 edhill 1.4 found in the <ulink
1047 jmc 1.15 url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
1048     tools/example_scripts directory</ulink>.</para>
1049 edhill 1.4 </listitem>
1050     </varlistentry>
1051    
1052     <varlistentry>
1053     <term><filename>-command='some command to run'</></term>
1054     <listitem>
1055 jmc 1.15 <para>For some tests, particularly MPI runs, a specific command
1056     might be needed to run the executable. This option allows a more general
1057 edhill 1.4 command (or shell script) to be invoked. Examples of PBS scripts
1058 jmc 1.15 using testreport with MPI can be found in the <ulink
1059     url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
1060     tools/example_scripts directory</ulink>.</para>
1061 jmc 1.16 <para>
1062     For the case where the number of MPI processors varies according
1063     to each test-experiment, some key-words within the command-to-run
1064     argument will be replaced by their effective value:</para>
1065     <para>
1066     <filename>TR_NPROC </> will be replaced by the actual number
1067     of MPI processors needed to run the current test-experiment.</para>
1068     <para>
1069     <filename>TR_MFILE </> will be replaced by the name of local-file
1070     that testreport creates from the full list of machines which
1071     "<filename>testreport -mf MACHINE_FILE</>" provides, but truncated
1072     to the exact number of machines.</para>
1073     </listitem>
1074     </varlistentry>
1075    
1076     <varlistentry>
1077     <term><filename>-mf MACHINE_FILE</></term>
1078     <listitem>
1079     <para>
1080     To use with <filename>-MPI NUMBER_OF_PROCS</> option, to specify
1081     the file containing the full list of <filename>NUMBER_OF_PROCS</>
1082     machines to use for the MPI runs.</para>
1083     </listitem>
1084     </varlistentry>
1085    
1086     <varlistentry>
1087     <term><filename>-mth</></term>
1088     <listitem>
1089     <para>compile (with <filename>genmake2 -omp</>) and run with
1090     multiple threads (using eedata.mth).</para>
1091 edhill 1.3 </listitem>
1092     </varlistentry>
1093    
1094     </variablelist>
1095    
1096 jmc 1.16 <para>The <filename>testreport</> script will create an output directory
1097     <filename>tr_NAME_DATE_N/ </>, with <filename>hostname</> as default
1098     <filename>NAME</>, <filename>DATE</> the current date followed by
1099     a suffix number "N" to distinguish from previous
1100     <filename>testreport</> output directories.
1101     <filename>testreport</> writes progress to the screen (stdout)
1102     and reports into the ouput directory as it runs.
1103     In particular, one can find, in the ouput directory,
1104     the <filename>summary.txt</> file that contains a brief comparison
1105     of the current output with the "known-good" output.
1106     At the end of the testing process, the <filename>tr_out.txt</> file
1107     is generated in <filename>$ROOTDIR/verification/ </>
1108     as a compact version of <filename>summry.txt</> file.</para>
1109    
1110     </sect3>
1111 edhill 1.3
1112 jmc 1.16 <sect3 id="tst_2plus2">
1113     <title>The <filename>do_tst_2+2</> Utility</title>
1114     <para> The shell script <filename>do_tst_2+2</> (in
1115     <filename>$ROOTDIR/tools/ </>)
1116     can be used to check the accuracy of the restart procedure.
1117     </para>
1118 edhill 1.3 </sect3>
1119    
1120     </sect2>
1121 edhill 1.2
1122 edhill 1.4
1123 edhill 1.2 <sect2 id="packages">
1124 edhill 1.3 <title>Creating MITgcm Packages</title>
1125 edhill 1.2
1126 edhill 1.4 <para>Optional parts of code have been separated from the MITgcmUV core
1127     driver code and organised into packages. The packaging structure
1128     provides a mechanism for maintaining suites of code, specific to
1129     particular classes of problems, in a way that is cleanly separated from
1130     the generic fluid dynamical engine.</para>
1131    
1132     <para>The MITgcmUV packaging structure is described below using generic
1133 jmc 1.11 package names ${pkg}. A concrete examples of a package is the code for
1134 edhill 1.4 implementing GM/Redi mixing. This code uses the package name</para>
1135 edhill 1.2
1136     </sect2>
1137    
1138     </sect1>
1139    
1140     <sect1>
1141     <title>Chris's Notes...</title>
1142    
1143     <programlisting>
1144     MITgcmUV Packages
1145     =================
1146    
1147     Optional parts of code are separated from
1148     the MITgcmUV core driver code and organised into
1149     packages. The packaging structure provides a mechanism for
1150     maintaining suites of code, specific to particular
1151     classes of problem, in a way that is cleanly
1152     separated from the generic fluid dynamical engine.
1153    
1154     The MITgcmUV packaging structure is describe
1155     below using generic package names ${pkg}.
1156     A concrete examples of a package is the code
1157     for implementing GM/Redi mixing. This code uses
1158 jmc 1.16 the package name
1159 edhill 1.2 * ${PKG} = GMREDI
1160     * ${pkg} = gmredi
1161     * ${Pkg} = gmRedi
1162    
1163     Package states
1164     ==============
1165    
1166     Packages can be any one of four states, included,
1167     excluded, enabled, disabled as follows:
1168    
1169     included(excluded) compile time state which
1170     includes(excludes) package
1171     code and routine calls from
1172     compilation/linking etc...
1173    
1174     enabled(disabled) run-time state which
1175     enables(disables) package code
1176     execution.
1177    
1178     Every call to a ${pkg}_... routine from outside the package
1179     should be placed within both a
1180     #ifdef ALLOW_${PKG} ... block and a
1181     if ( use${Pkg} ) ... then block.
1182     Package states are generally not expected to change during
1183     a model run.
1184    
1185     Package structure
1186     =================
1187    
1188     o Each package gets its runtime configuration
1189     parameters from a file named "data.${pkg}"
1190     Package runtime config. options are imported
1191     into a common block held in a header file
1192     called "${PKG}.h".
1193 jmc 1.16 Note: In some packages, the header file "${PKG}.h" is splitted
1194     into "${PKG}_PARAMS.h" that contains the package parameters and
1195 jmc 1.8 ${PKG}_VARS.h" for the field arrays.
1196 edhill 1.2
1197     o The core driver part of the model can check
1198     for runtime enabling or disabling of individual packages
1199     through logical flags use${Pkg}.
1200     The information is loaded from a
1201     global package setup file called "data.pkg".
1202     The use${Pkg} flags are not used within
1203     individual packages.
1204    
1205     o Included in "${PKG}.h" is a logical flag
1206     called ${Pkg}IsOn. The "${PKG}.h" header file can be imported
1207     by other packages to check dependencies and requirements
1208     from other packages ( see "Package Boot Sequence" section).
1209     NOTE: This procedure is not presently implemented,
1210     ----- neither for kpp nor for gmRedi.
1211    
1212     CPP Flags
1213     =========
1214    
1215     1. Within the core driver code flags of the form
1216     ALLOW_${PKG} are used to include or exclude
1217     whole packages. The ALLOW_${PKG} flags are included
1218 jmc 1.16 from a PACKAGES_CONFIG.h file that is automatically
1219 jmc 1.8 generated by genmake2 (see genmake2 section).
1220 edhill 1.2 held in-line in the CPP_OPTIONS.h header file.
1221     e.g.
1222    
1223     Core model code .....
1224    
1225 jmc 1.8 #include "PACKAGES_CONFIG.h"
1226 edhill 1.2 #include "CPP_OPTIONS.h"
1227     :
1228     :
1229     :
1230    
1231     #ifdef ALLOW_${PKG}
1232     if ( use${Pkg} ) CALL ${PKG}_DO_SOMETHING(...)
1233     #endif
1234    
1235     2. Within an individual package a header file,
1236     "${PKG}_OPTIONS.h", is used to set CPP flags
1237 jmc 1.16 specific to that package. It also includes
1238 jmc 1.8 "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
1239 edhill 1.2
1240    
1241     Package Boot Sequence
1242     =====================
1243    
1244     Calls to package routines within the core code timestepping
1245     loop can vary. However, all packages follow a required
1246     "boot" sequence outlined here:
1247    
1248     1. S/R PACKAGES_BOOT()
1249     :
1250     CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
1251 jmc 1.16
1252 edhill 1.2
1253     2. S/R PACKAGES_READPARMS()
1254     :
1255     #ifdef ALLOW_${PKG}
1256     if ( use${Pkg} )
1257     & CALL ${PKG}_READPARMS( retCode )
1258     #endif
1259    
1260 jmc 1.6 3. S/R PACKAGES_INIT_FIXED()
1261     :
1262     #ifdef ALLOW_${PKG}
1263     if ( use${Pkg} )
1264     & CALL ${PKG}_INIT_FIXED( retCode )
1265     #endif
1266    
1267     4. S/R PACKAGES_CHECK()
1268 edhill 1.2 :
1269     #ifdef ALLOW_${PKG}
1270     if ( use${Pkg} )
1271     & CALL ${PKG}_CHECK( retCode )
1272     #else
1273     if ( use${Pkg} )
1274     & CALL PACKAGES_CHECK_ERROR('${PKG}')
1275     #endif
1276    
1277 jmc 1.6 5. S/R PACKAGES_INIT_VARIABLES()
1278 edhill 1.2 :
1279     #ifdef ALLOW_${PKG}
1280     if ( use${Pkg} )
1281 jmc 1.6 & CALL ${PKG}_INIT_VARIA( )
1282     #endif
1283    
1284     Package Output
1285     ==============
1286     6. S/R DO_THE_MODEL_IO
1287    
1288     #ifdef ALLOW_${PKG}
1289     if ( use${Pkg} )
1290 jmc 1.9 & CALL ${PKG}_OUTPUT( )
1291 edhill 1.2 #endif
1292    
1293 jmc 1.6 7. S/R PACKAGES_WRITE_PICKUP()
1294    
1295     #ifdef ALLOW_${PKG}
1296     if ( use${Pkg} )
1297     & CALL ${PKG}_WRITE_PICKUP( )
1298     #endif
1299 edhill 1.2
1300     Description
1301     ===========
1302    
1303 jmc 1.16 - ${PKG}_READPARMS()
1304 edhill 1.2 is responsible for reading
1305     in the package parameters file data.${pkg}, and storing
1306 jmc 1.8 the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
1307 jmc 1.6 -> called from INITIALISE_FIXED in PACKAGES_READPARMS
1308    
1309 jmc 1.16 - ${PKG}_INIT_FIXED()
1310     is responsible for completing the internal setup of a package.
1311 jmc 1.6 -> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
1312     note: 1) some pkg use instead:
1313     CALL ${PKG}_INITIALISE ( or the old form CALL ${PKG}_INIT )
1314     2) for simple pkg setup, this part is done inside ${PKG}_READPARMS
1315 edhill 1.2
1316 jmc 1.16 - ${PKG}_CHECK()
1317 edhill 1.2 is responsible for validating
1318     basic package setup and inter-package dependencies.
1319     ${PKG}_CHECK can import other package parameters it may
1320     need to check. This is done through header files "${PKG}.h".
1321     It is assumed that parameters owned by other packages
1322     will not be reset during ${PKG}_CHECK().
1323 jmc 1.6 -> called from INITIALISE_FIXED in PACKAGES_CHECK
1324 edhill 1.2
1325 jmc 1.16 - ${PKG}_INIT_VARIA()
1326 jmc 1.6 is responsible for fill-in all package variables with an initial value.
1327     Contains eventually a call to ${PKG}_READ_PICKUP that will read
1328     from a pickup file the package variables required to restart the model.
1329 jmc 1.16 This routine is called after the core model state has been completely
1330 jmc 1.6 initialised but before the core model timestepping starts.
1331     -> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
1332 jmc 1.16 note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
1333     use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
1334 jmc 1.6 form ${PKG}_INIT
1335    
1336 jmc 1.9 - ${PKG}_OUTPUT( )
1337 jmc 1.8 is responsible for writing time-average fields to output files
1338     (but the cumulating step is done within the package main S/R).
1339 jmc 1.16 Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1340     and write snap-shot fields that are hold in common blocks. Other
1341 jmc 1.6 temporary fields are directly dump to file where they are available.
1342 jmc 1.16 NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
1343 jmc 1.9 but is beeing replaced by ${PKG}_OUTPUT
1344 jmc 1.8 to avoid confusion with pkg/diagnostics functionality.
1345     2) the output part is not yet in a standard form and might still
1346     evolve a lot.
1347 jmc 1.6 -> called within DO_THE_MODEL_IO
1348    
1349 jmc 1.16 - ${PKG}_WRITE_PICKUP()
1350     is responsible for writing a package pickup file when necessary for
1351 jmc 1.6 a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1352     -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1353 edhill 1.2
1354     Summary
1355     =======
1356    
1357     - CPP options:
1358     -----------------------
1359     * ALLOW_${PKG} include/exclude package for compilation
1360    
1361     - FORTRAN logical:
1362     -----------------------
1363     * use${Pkg} enable package for execution at runtime
1364     -> declared in PARAMS.h
1365     * ${Pkg}IsOn for package cross-dependency check
1366     -> declared in ${PKG}.h
1367     N.B.: Not presently used!
1368    
1369     - header files
1370     -----------------------
1371     * ${PKG}_OPTIONS.h has further package-specific CPP options
1372     * ${PKG}.h package-specific common block variables, fields
1373 jmc 1.8 or ${PKG}_PARAMS.h package-specific common block parameters
1374     and ${PKG}_VARS.h package-specific common block fields
1375 edhill 1.2
1376     - FORTRAN source files
1377     -----------------------
1378 jmc 1.6 * ${pkg}_readparms.F reads parameters from file data.${pkg}
1379     * ${pkg}_init_fixed.F complete the package setup
1380     * ${pkg}_check.F checks package dependencies and consistencies
1381     * ${pkg}_init_varia.F initialises package-related fields
1382     * ${pkg}_... .F package source code
1383 jmc 1.9 * ${pkg}_output.F write output to file.
1384 jmc 1.6 * ${pkg}_write_pickup.F write a package pickup file to restart the model
1385 edhill 1.2
1386 jmc 1.16 New: Subroutine in one package (pkgA) that only contains code which
1387 jmc 1.8 is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
1388     will be named: pkgA_pkgB_something.F
1389    
1390 edhill 1.2 - parameter file
1391     -----------------------
1392     * data.${pkg} parameter file
1393     </programlisting>
1394    
1395     </sect1>
1396 edhill 1.1
1397    
1398 jmc 1.11 <sect1 id="documentation">
1399     <title>Editing the Documentation</title>
1400    
1401     <sect2 id="documentation_getting">
1402     <title>Getting the Docs and Code</title>
1403    
1404     <para>The first step towards editing the documentation is to checkout a
1405     copy of code, docs, and build scripts from the CVS server using:</para>
1406    
1407     <screen>
1408     $ export CVS_RSH=ssh
1409     $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
1410     $ mkdir scratch
1411     $ cvs co -P MITgcm manual mitgcm.org
1412     </screen>
1413    
1414     <para>These commands extract the necessary information from the CVS server
1415     and create a temporary (called <filename>scratch</filename>) directory for
1416     the storage of the HTML and other files that will be created. Please note
1417     that you must either create <filename>scratch</filename> as shown or edit
1418     the various <filename>Makefile</filename>s and scripts used to create the
1419     documentation.</para>
1420     </sect2>
1421    
1422     <sect2>
1423     <title>Editing the Documentation</title>
1424    
1425     <para>The documentation is contained in the <filename>manual</filename>
1426     directory in a raw LaTeX format. The main document is
1427     <filename>manual.tex</filename> and it uses <command>\input{}</command>s
1428     to include the chapters and subsections.</para>
1429    
1430     <para>Since the same LaTeX source is used to produce PostScript, PDF, and
1431     HTML output, care should be taken to follow certain conventions. Two of
1432     the most important are the usage of the <command>\filelink{}{}</command>
1433     and <command>\varlink{}{}</command> commands. Both of these commands have
1434     been defined to simplify the connection between the automatically
1435     generated ("code browser") HTML and the HTML version of the manual
1436     produced by LaTeX2HTML. They each take two arguments (corresponding to
1437     the contents of the two sets of curly braces) which are the text that the
1438     author wishes to be "wrapped" within the link, and a specially formatted
1439     link thats relative to the <filename>MITgcm</filename> directory within
1440     the CVS tree.</para>
1441    
1442     <para>The result is a command that resembles either</para>
1443 jmc 1.16
1444 jmc 1.11 <orderedlist>
1445     <listitem>
1446     <para>a reference to a variable or subroutine name such as
1447     <command>\varlink{tRef}{tRef}</command>, or </para>
1448     </listitem>
1449    
1450     <listitem>
1451     <para>a reference to a file such as
1452     <command>\varlink{tRef}{path-to-the-file_name.F}</command>
1453     where the absolute path to the file is of the form
1454     <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>
1455     <para>(please note how the leading "/foo/MITgcm"
1456     component of the path is dropped leaving the path
1457     <emphasis>relative</emphasis> to the head of the code
1458     directory and each directory separator "/" is turned
1459     into a "-")</para>
1460     </listitem>
1461     </orderedlist>
1462 jmc 1.16
1463 jmc 1.11
1464    
1465     </sect2>
1466    
1467     <sect2>
1468     <title>Building the Documentation</title>
1469 jmc 1.16
1470 jmc 1.11 <para>Given the directory structure of <xref
1471     linkend="documentation_getting">, the entire documentation for the web
1472     site can be built using:</para>
1473    
1474     <screen>
1475     $ cd mitgcm.org/devel/buildweb
1476     $ make All
1477     </screen>
1478    
1479     <para>Which builds the PDF from the LaTeX source, creates the HTML output
1480     from the LaTeX source, parses the FORTRAN code base to produce a
1481     hyperlinked HTML version of the source, and then determines the
1482     cross-linking between the various HTML components.</para>
1483    
1484     <para>If there are no errors, the result of the build process (which can
1485     take 30+ minutes on a P4/2.5Ghz) will be contained within a single
1486     directory called <filename>scratch/dev_docs</filename>. This is a freshly
1487     built version of the entire on-line users manual. If you have the correct
1488     permissions, it can be directly copied to the web server area:</para>
1489    
1490     <screen>
1491     $ mv scratch/dev_docs /u/u0/httpd/html
1492     </screen>
1493    
1494     <para>and the update is complete.</para>
1495    
1496     </sect2>
1497    
1498     </sect1>
1499    
1500 edhill 1.1 </article>
1501    
1502    

  ViewVC Help
Powered by ViewVC 1.1.22