[MITgcm] Annotation of /MITgcm/doc/devel

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

	ViewVC Help
Powered by ViewVC 1.1.22

Annotation of /MITgcm/doc/devel_HOWTO.sgml