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