[MITgcm] Contents of /MITgcm/doc/devel

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

	ViewVC Help
Powered by ViewVC 1.1.22

Contents of /MITgcm/doc/devel_HOWTO.sgml