[MITgcm] Contents of /MITgcm/doc/devel

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

	ViewVC Help
Powered by ViewVC 1.1.22

Contents of /MITgcm/doc/devel_HOWTO.sgml