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

Contents of /MITgcm/doc/devel_HOWTO.sgml

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


Revision 1.16 - (show annotations) (download) (as text)
Sun Apr 24 00:04:40 2011 UTC (12 years, 11 months ago) by jmc
Branch: MAIN
CVS Tags: checkpoint63l, checkpoint63m, checkpoint63h, checkpoint63i, checkpoint63j, checkpoint63k, checkpoint63d, checkpoint63e, checkpoint63f, checkpoint63g, checkpoint63a, checkpoint63b, checkpoint63c, checkpoint63, checkpoint62w, checkpoint62z, checkpoint62y, checkpoint62x
Changes since 1.15: +351 -82 lines
File MIME type: text/x-sgml
version 04: update section 4.2 (verification suite):
 - add sub-section "test-experiment directory content"
 - update sub-section "testreport"

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

  ViewVC Help
Powered by ViewVC 1.1.22