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