/[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.8 - (show annotations) (download) (as text)
Wed Jan 5 03:45:24 2005 UTC (17 years, 8 months ago) by jmc
Branch: MAIN
CVS Tags: checkpoint57t_post, checkpoint57o_post, checkpoint57v_post, checkpoint57m_post, checkpoint57s_post, checkpoint57k_post, checkpoint57d_post, checkpoint57g_post, checkpoint57c_pre, checkpoint57i_post, checkpoint57y_post, checkpoint57e_post, checkpoint57g_pre, checkpoint57y_pre, checkpoint57f_pre, checkpoint57r_post, checkpoint58, eckpoint57e_pre, checkpoint57h_done, checkpoint57x_post, checkpoint57n_post, checkpoint58d_post, checkpoint58c_post, checkpoint57w_post, checkpoint57p_post, checkpint57u_post, checkpoint57f_post, checkpoint58a_post, checkpoint57q_post, checkpoint57z_post, checkpoint57c_post, checkpoint57j_post, checkpoint58b_post, checkpoint57h_pre, checkpoint57l_post, checkpoint57h_post
Changes since 1.7: +25 -11 lines
File MIME type: text/x-sgml
update package part (Chris's notes)

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 </revhistory>
26
27 <abstract>
28 <para>This document describes how to develop software for the
29 MITgcm project.</para>
30 </abstract>
31 </articleinfo>
32
33 <sect1 id="intro">
34 <title>Introduction</title> <para>The purpose of this document is
35 to help new developers get "up to speed" with MITgcm
36 development.</para>
37 <sect2>
38 <title>New Versions of This Document</title> <para>You can
39 obtain the latest version of this document <ulink
40 url="http://mitgcm.org/dev_docs/devel_HOWTO/">online</ulink> in
41 various formats.</para>
42 </sect2>
43 <sect2>
44 <title>Feedback and corrections</title> <para>If you have
45 questions or comments about this document, please feel free to
46 <ulink url="mailto:MITgcm-support@mitgcm.org">contact the
47 authors</ulink>.
48 </para>
49 </sect2>
50 </sect1>
51
52 <sect1 id="background">
53 <title>Background</title>
54
55 <sect2>
56 <title>User Manual</title>
57
58 <para>Before jumping into development, please familiarize yourself with
59 the <ulink url="http://mitgcm.org/docs.html"> MITgcm user manual
60 </ulink>. This document contains volumes of useful information and is
61 included here by reference.</para>
62
63 <!--
64 <para>Also, a "snapshot" or <ulink
65 url="http://mitgcm.org/dev_docs/">development version</ulink> of
66 the user manual may be available, though this is only put on the
67 web for testing purposes.</para>
68 -->
69 </sect2>
70
71 <sect2>
72 <title>Prerequisites</title> <para>To develop for MITgcm project
73 you will need a UNIX or UNIX-like set of build tools including
74 the following:</para>
75 <blockquote>
76 <simplelist type="inline">
77 <member>CVS client</member>
78 <member>make or (preferably) GNU make</member>
79 <member>FORTRAN compiler</member>
80 <member>C compiler</member>
81 <member>[ba]sh and [t]csh shells</member>
82 <member>PERL</member>
83 <member>LaTeX and LaTeX2HTML</member>
84 </simplelist>
85 </blockquote>
86 <para>Essentially all of the work described here has been tested
87 on recent versions of Red Hat Linux (eg. 7.3 through 9). Except
88 where noted, all shell commands will be provided using bash
89 syntax.
90 </para>
91 </sect2>
92
93 </sect1>
94
95 <sect1 id="cvs">
96 <title>CVS Repository</title>
97 <sect2>
98 <title>Layout</title>
99
100 <para>Unlike many open source projects, the MITgcm CVS tree does
101 not follow a simple "src", "docs", "share", and "test" directory
102 layout. Instead, there are multiple higher-level directories
103 that each, to some extent, depend upon the presence of the
104 others. The tree currently resembles:</para>
105
106 <programlisting>gcmpack/
107 MITgcm-contrib contributed code
108 CS-regrid goes into utils
109 cvspolicy.html -save-
110 CVSROOT -save-
111 development experimental stuff
112 manual -save-
113 misc -?-
114
115 MITgcm code
116 adjoint fold into genmake
117 bin stub for ecco build
118 compare01 old from 20th century
119 diags timeave f77 in pkgs now
120 doc tags -- connect to real docs?
121 eesupp cnh?
122 exe ecco user build
123 ,- jobs runtime shell scripts for
124 | various platforms
125 | lsopt line search
126 m| model main dynamics (core)
127 e| optimization_drivers ?
128 r| optim line search interface
129 g| pkg alternate and optional numerics, etc.
130 e|- tools
131 ?| tutorial_examples documented tests
132 | only populated on release1 branch
133 | and not validated during "testscript"
134 '- utils
135 verification std tests
136
137
138 mitgcmdoc -> manual -remove-
139 mitgcm.org build web site
140 models -?-
141 packages -?-
142 preprocess -?-
143 tmp -?-
144 </programlisting>
145
146 <para>Efforts are underway to reduce the complexity.</para>
147
148 </sect2>
149
150 <!--
151 <sect2>
152 <title>Releases</title> <para>Currently, there are two main
153 branches:</para>
154 <itemizedlist mark="bullet">
155 <listitem>
156 <para>Development</para>
157 <itemizedlist mark="bullet">
158 <listitem>
159 <para>MAIN</para>
160 </listitem>
161 <listitem>
162 <para>ecco-branch</para>
163 </listitem>
164 </itemizedlist>
165 </listitem>
166 <listitem>
167 <para>Production</para>
168 <itemizedlist mark="bullet">
169 <listitem>
170 <para>Release1</para>
171 </listitem>
172 <listitem>
173 <para>Release2</para>
174 </listitem>
175 </itemizedlist>
176 </listitem>
177 </itemizedlist>
178 </sect2>
179 -->
180
181 <sect2>
182 <title>Branches</title>
183
184 <para>As shown in the online <ulink
185 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index?graph=1.174">
186 ViewCVS-generated tree</ulink>, the MITgcm codebase is split into to two
187 branches or "lines" under which development proceeds. These two lines are
188 referred to as the "MAIN" and "ecco" versions of the code. While not
189 identical, the bulk of the MAIN and ecco lines are composed of files from
190 the same codebase.
191 </para>
192
193 <para>Periodically, a "Release" branch is formed from the "MAIN"
194 development branch. This is done in order to create a relatively stable
195 reference point for both users and developers. The intent is that once a
196 relese branch has been created, only bug-fixes will be added to it.
197 Meanwhile, development (which might "break" or otherwise render invalid
198 the documentation, tutorials, and/or examples contained within a release
199 branch) is allowed to continue along the MAIN and ecco lines.</para>
200 </sect2>
201
202 <sect2>
203 <title>Tagging</title>
204
205 <para>The intent of tagging is to create "known-good" checkpoints that
206 developers can use as references. Traditionally, MITgcm tagging has
207 maintained the following conventions:</para>
208
209 <orderedlist>
210 <listitem>
211 <para>Developer checks out code into a local CVS-managed directory,
212 makes various changes/additions, tests these edits, and eventually
213 reaches a point where (s)he is satisfied that the changes form a new
214 "useful" point in the evolution of the code.</para>
215 </listitem>
216
217 <listitem>
218 <para>The developer then runs the <ulink
219 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/verification/testscript">
220 testscript</ulink> shell script to see if any problems are introduced.
221 While not intended to be exhaustive, the test cases within the
222 verification directory do provide some indication whether gross errors
223 have been introduced.
224 </para>
225 </listitem>
226
227 <listitem>
228 <para>Having satisfied him- or herself that the changes are
229 ready to be committed to the CVS repository, the developer
230 then:</para>
231 <orderedlist>
232 <listitem>
233 <para>adds a "checkpointXY_pre" comment (where X is a checkpoint
234 number and Y is a letter) to the <ulink
235 url="http://dev.mitgcm.org/cgi-bin/viewcvs.cgi/MITgcm/doc/tag-index">
236 tag-index</ulink> file and checks it into the CVS
237 repository</para>
238 </listitem>
239 <listitem>
240 <para>submits the set of changes to the CVS repository and adds
241 comments to <filename>tag-index</filename> describing what the
242 changes are along with a matching "checkpointXY_post" entry</para>
243 </listitem>
244 </orderedlist>
245 </listitem>
246 </orderedlist>
247
248 <para>The result of this tagging procedure is a sequence of development
249 checkpoints with comments which resembles:</para>
250
251 <programlisting>
252 checkpoint50e_post
253 o make KPP work with PTRACERS
254 - fix gad_calc_rhs to call new routine kpp_transport_ptr, which is
255 nearly a copy of kpp_transport_s
256 - there is no analogue to SurfaceTendencyS, so I have to use
257 gPtr(of the surface layer) instead
258 o add a new platform SunFire+mpi (SunFire 15000) to genmake
259 checkpoint50e_pre
260
261 checkpoint50d_post
262 o change kpp output from multiple-record state files to single-record state
263 files analogous to write_state.F
264 o reduce the output frequency of cg3d-related stuff to the monitor frequency,
265 analogous to the cg2d-related output.
266 o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
267 so that writing to internal file fn (with length 512) fails.
268 checkpoint50d_pre
269 </programlisting>
270
271 <para>This information can be used to refer to various stages of the code
272 development. For example, bugs can be traced to individual sets of CVS
273 checkins based upon their first appearance when comparing the results from
274 different checkpoints.</para>
275
276 </sect2>
277 </sect1>
278
279
280 <sect1 id="documentation">
281 <title>Editing the Documentation</title>
282
283 <sect2 id="documentation_getting">
284 <title>Getting the Docs and Code</title>
285
286 <para>The first step towards editing the documentation is to checkout a
287 copy of code, docs, and build scripts from the CVS server using:</para>
288
289 <screen>
290 $ export CVS_RSH=ssh
291 $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
292 $ mkdir scratch
293 $ cvs co MITgcm manual mitgcm.org
294 </screen>
295
296 <para>These commands extract the necessary information from the CVS server
297 and create a temporary (called <filename>scratch</filename>) directory for
298 the storage of the HTML and other files that will be created. Please note
299 that you must either create <filename>scratch</filename> as shown or edit
300 the various <filename>Makefile</filename>s and scripts used to create the
301 documentation.</para>
302 </sect2>
303
304 <sect2>
305 <title>Editing the Documentation</title>
306
307 <para>The documentation is contained in the <filename>manual</filename>
308 directory in a raw LaTeX format. The main document is
309 <filename>manual.tex</filename> and it uses <command>\input{}</command>s
310 to include the chapters and subsections.</para>
311
312 <para>Since the same LaTeX source is used to produce PostScript, PDF, and
313 HTML output, care should be taken to follow certain conventions. Two of
314 the most important are the usage of the <command>\filelink{}{}</command>
315 and <command>\varlink{}{}</command> commands. Both of these commands have
316 been defined to simplify the connection between the automatically
317 generated ("code browser") HTML and the HTML version of the manual
318 produced by LaTeX2HTML. They each take two arguments (corresponding to
319 the contents of the two sets of curly braces) which are the text that the
320 author wishes to be "wrapped" within the link, and a specially formatted
321 link thats relative to the <filename>MITgcm</filename> directory within
322 the CVS tree.</para>
323
324 <para>The result is a command that resembles either</para>
325
326 <orderedlist>
327 <listitem>
328 <para>a reference to a variable or subroutine name such as
329 <command>\varlink{tRef}{tRef}</command>, or </para>
330 </listitem>
331
332 <listitem>
333 <para>a reference to a file such as
334 <command>\varlink{tRef}{path-to-the-file_name.F}</command>
335 where the absolute path to the file is of the form
336 <filename>/foo/MITgcm/path/to/the/file_name.F</filename></para>
337 <para>(please note how the leading "/foo/MITgcm"
338 component of the path is dropped leaving the path
339 <emphasis>relative</emphasis> to the head of the code
340 directory and each directory separator "/" is turned
341 into a "-")</para>
342 </listitem>
343 </orderedlist>
344
345
346
347 </sect2>
348
349 <sect2>
350 <title>Building the Documentation</title>
351
352 <para>Given the directory structure of <xref
353 linkend="documentation_getting">, the entire documentation for the web
354 site can be built using:</para>
355
356 <screen>
357 $ cd mitgcm.org/devel/buildweb
358 $ make All
359 </screen>
360
361 <para>Which builds the PDF from the LaTeX source, creates the HTML output
362 from the LaTeX source, parses the FORTRAN code base to produce a
363 hyperlinked HTML version of the source, and then determines the
364 cross-linking between the various HTML components.</para>
365
366 <para>If there are no errors, the result of the build process (which can
367 take 30+ minutes on a P4/2.5Ghz) will be contained within a single
368 directory called <filename>scratch/dev_docs</filename>. This is a freshly
369 built version of the entire on-line users manual. If you have the correct
370 permissions, it can be directly copied to the web server area:</para>
371
372 <screen>
373 $ mv scratch/dev_docs /u/u0/httpd/html
374 </screen>
375
376 <para>and the update is complete.</para>
377
378 </sect2>
379
380 </sect1>
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://dev.mitgcm.org/cgi-bin/viewcvs.cgi/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://dev.mitgcm.org/cgi-bin/viewcvs.cgi/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}_DIAGS( ) [ or 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}_DIAGS() [or ${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) ${PKG}_OUTPUT is progressively replacing ${PKG}_DIAGS()
1039 to avoid confusion with pkg/diagnostics functionality.
1040 2) the output part is not yet in a standard form and might still
1041 evolve a lot.
1042 -> called within DO_THE_MODEL_IO
1043
1044 - ${PKG}_WRITE_PICKUP()
1045 is responsible for writing a package pickup file when necessary for
1046 a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1047 -> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1048
1049 Summary
1050 =======
1051
1052 - CPP options:
1053 -----------------------
1054 * ALLOW_${PKG} include/exclude package for compilation
1055
1056 - FORTRAN logical:
1057 -----------------------
1058 * use${Pkg} enable package for execution at runtime
1059 -> declared in PARAMS.h
1060 * ${Pkg}IsOn for package cross-dependency check
1061 -> declared in ${PKG}.h
1062 N.B.: Not presently used!
1063
1064 - header files
1065 -----------------------
1066 * ${PKG}_OPTIONS.h has further package-specific CPP options
1067 * ${PKG}.h package-specific common block variables, fields
1068 or ${PKG}_PARAMS.h package-specific common block parameters
1069 and ${PKG}_VARS.h package-specific common block fields
1070
1071 - FORTRAN source files
1072 -----------------------
1073 * ${pkg}_readparms.F reads parameters from file data.${pkg}
1074 * ${pkg}_init_fixed.F complete the package setup
1075 * ${pkg}_check.F checks package dependencies and consistencies
1076 * ${pkg}_init_varia.F initialises package-related fields
1077 * ${pkg}_... .F package source code
1078 * ${pkg}_diags.F write output to file.
1079 or ${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 </article>

  ViewVC Help
Powered by ViewVC 1.1.22