[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.15 2011/03/01 01:33:19 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	<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	</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	url="http://mitgcm.org/public/docs.html">online</ulink> in
69	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	<para>Before jumping into development, please familiarize yourself with
87	the <ulink url="http://mitgcm.org/public/docs.html"> MITgcm user manual
88	</ulink>. This document contains volumes of useful information and is
89	included here by reference.</para>
90
91	<!--
92	<para>Also, a "snapshot" or <ulink
93	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	-->
97	</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
126	<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	CVSROOT -hidden-
137
138	MITgcm code
139	bin empty
140	doc basic developpment documentation
141	eesupp execution environment support code (wrapper)
142	exe empty
143	jobs runtime shell scripts for
144	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
155	MITgcm_contrib contributed code
156
157	acesgrid.org build acesgrid web site
158	development experimental stuff
159	gfd_lab -?-
160	manual source of MITgcm documentation
161	mitgcm.org build web site
162	old_develop old and early development source
163	misc -?-
164	models -?-
165	packages -?-
166	preprocess -?-
167	pdfs some pdfs
168	planetinabottle.org unfinished web site
169	www.ecco-group.org build ecco web site ?
170	</programlisting>
171
172	<!--
173	<para>Efforts are underway to reduce the complexity.</para>
174	-->
175
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	url="http://mitgcm.org/viewvc/MITgcm/MITgcm/model/src/forward_step.F?view=graph">
214	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	</para>
218
219	<para>Periodically, a "Release" branch is formed from the "MAIN"
220	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	release branch has been created, only bug-fixes will be added to it.
223	Meanwhile, development (which might "break" or otherwise render invalid
224	the documentation, tutorials, and/or examples contained within a release
225	branch) is allowed to continue along the MAIN line.</para>
226	</sect2>
227
228	<sect2>
229	<title> Developer settings </title>
230
231	<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	incorporate any change into the repository. However, this later
235	function requires specific settings, as detailed here after:</para>
236	<orderedlist>
237	<listitem>
238	<para> You will need an account (loggin access) to the server
239	"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	to ssh to mitgcm.org (or <filename>ssh MY_USER_NAME@mitgcm.org</filename>
246	in case of different user-name on both sides) to proceed further.</para>
247	</listitem>
248
249	<listitem>
250	<para> You need to register to the
251	<ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-cvs">
252	mitgcm-cvs </ulink> mailing list.
253	This ensures that other developers will receive email notification
254	when you make changes; you will also receive as well such email
255	when others make changes to the repository.
256	</para>
257	</listitem>
258
259	<listitem>
260	<para> It is highly recommended that you register also to the
261	<ulink url="http://mitgcm.org/mailman/listinfo/mitgcm-devel">
262	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	<ulink url="http://mitgcm.org/public/source_code.html">
271	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	<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	using the CVS anonymous mode.</para>
288	</listitem>
289
290	<listitem>
291	<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	(<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	<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	editor for this purpose).</para>
306	</listitem>
307
308	</orderedlist>
309
310	</sect2>
311
312	<sect2>
313	<title>Main code development</title>
314	<para><emphasis>(formerly named "Tagging" ; this section needs an update)
315	</emphasis></para>
316
317	<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
321	<orderedlist>
322	<listitem>
323	<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	</listitem>
328
329	<listitem>
330	<para>The developer then runs the <ulink
331	url="http://mitgcm.org/viewvc/MITgcm/MITgcm/verification/testreport">
332	testreport</ulink> shell script to see if any problems are introduced.
333	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	</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	<para>adds a "checkpointXY_pre" comment (where X is a checkpoint
346	number and Y is a letter) to the <ulink
347	url="http://mitgcm.org/viewvc/MITgcm/MITgcm/doc/tag-index">
348	tag-index</ulink> file and checks it into the CVS
349	repository</para>
350	</listitem>
351	<listitem>
352	<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	</listitem>
356	</orderedlist>
357	</listitem>
358	</orderedlist>
359
360	<para>The result of this tagging procedure is a sequence of development
361	checkpoints with comments which resembles:</para>
362
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	- there is no analogue to SurfaceTendencyS, so I have to use
369	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	o change kpp output from multiple-record state files to single-record state
375	files analogous to write_state.F
376	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	so that writing to internal file fn (with length 512) fails.
380	checkpoint50d_pre
381	</programlisting>
382
383	<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
388	</sect2>
389	</sect1>
390
391
392	<sect1 id="coding">
393	<title>Coding for MITgcm</title>
394
395	<sect2 id="build_tools">
396	<title>Build Tools</title>
397
398	<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
404	<screen>
405	$ genmake2 -mods=../code
406	$ make depend
407	$ make
408	</screen>
409
410	<para>The following sections describe the individual steps in the build
411	process.</para>
412
413	<sect3 id="genmake">
414	<title>The <filename>genmake2</> Utility</title>
415
416	<para><emphasis>(Note: the older <filename>genmake</>
417	has been replaced by <filename>genmake2</>)</emphasis></para>
418
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
425	<itemizedlist>
426	<listitem>
427	<para><ulink url="http://www.gnu.org/software/make/make.html">
428	http://www.gnu.org/software/make/make.html</></para>
429	</listitem>
430	<listitem>
431	<para><ulink url="http://www.oreilly.com/catalog/make2/">
432	http://www.oreilly.com/catalog/make2/</></para>
433	</listitem>
434	</itemizedlist>
435
436	<para>Genmake can often be invoked successfully with a command line as
437	simple as:</para>
438
439	<screen>
440	$ genmake2 -mods=../code
441	</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	$ /usr/bin/sh genmake2 -make=gmake -mods=../code
450	$ /opt/gnu/bin/bash genmake2 -ieee -make=/usr/local/bin/gmake -mods=../code
451	</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
461	<orderedlist>
462	<listitem>
463	<para>a <filename>gemake_local</filename> file in the current
464	directory</para>
465	</listitem>
466	<listitem>
467	<para>directly from command-line options</para>
468	</listitem>
469	<listitem>
470	<para>an "options file" as specified by the command-line option
471	<filename>-optfile='FILENAME'</filename></para>
472	</listitem>
473	<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	</orderedlist>
480
481	<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
488	<screen>
489	$ genmake2 -help
490	</screen>
491
492	<para>The most important options for <filename>genmake2</> are:</para>
493
494	<variablelist>
495
496	<varlistentry>
497	<term><filename>--optfile=/PATH/FILENAME</></term>
498
499	<listitem>
500	<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	</listitem>
528
529	</varlistentry>
530
531	<varlistentry>
532	<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	<term><filename>-mods=DIR</></term>
551	<term><filename>-mods='DIR1 [DIR2 ...]'</></term>
552	<listitem>
553	<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	(in the order that that package dependencies are
566	parsed)</para></listitem>
567	<listitem><para>The "standard dirs" (which may have been
568	specified by the "-standarddirs" option)</para></listitem>
569	</itemizedlist>
570	</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
589	<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	</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	</listitem>
615	</varlistentry>
616
617	</variablelist>
618
619	<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	"un-clean" directory by running "make Clean" followed by "make
628	makefile".</para>
629
630	</sect3>
631
632	<sect3 id="makefile_use">
633	<title>Using the <filename>Makefile</></title>
634
635	<para>Once a <filename>Makefile</> has been created using
636	<filename>genmake2</>, one can build a "standard" (forward
637	simulator) executable using:</para>
638
639	<screen>
640	$ make Clean
641	$ make depend
642	$ make
643	</screen>
644
645	<para>The "make Clean" step will remove any stale source files, include
646	files, and links. It is strongly recommended for "un-clean"
647	directories which may contain the (perhaps partial) results of
648	previous builds. Such "debris" can interfere with the next stage of
649	the build.
650	A more agressive cleaning option, "make CLEAN", can be used to also
651	remove the executable and output files from a previous run.</para>
652
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	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	compiler. See the <filename>genmake2</> "-adof" option for
685	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
699	<para>Please report any compilation failures or other build problems to
700	the <email>MITgcm-support@mitgcm.org</email> list.</para>
701
702	</sect3>
703
704	</sect2>
705
706	<sect2 id="verification">
707	<title>The Verification Suite</title>
708
709	<para>The MITgcm CVS tree (within the <filename>$ROOTDIR/verification/</>
710	directory) includes many (> 90) examples intended for regression
711	testing. Each one of these test-experiment directories contains "known-good"
712	output files along with all the input (including both code and data
713	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
933	<sect3 id="testreport">
934	<title>The <filename>testreport</> Utility</title>
935
936	<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
943	<para>On some systems, the testreport script can be run with a command
944	line as simple as:</para>
945
946	<screen>
947	$ cd verification
948	$ ./testreport
949	</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	$ sh ./testreport -t 'exp2 exp4'
956	$ /some/path/to/bash ./testreport -t 'ideal_2D_oce lab_sea natl_box'
957	</screen>
958
959	<para>The <filename>testreport</> script accepts a number of
960	command-line options which can be listed using the <filename>-help</>
961	option. The most important ones are:</para>
962
963	<variablelist>
964
965	<varlistentry>
966	<term><filename>-ieee</> (default) / <filename>-noieee</></term>
967	<listitem>
968	<para>If allowed by the compiler (as defined in the "optfile"),
969	use IEEE arithmetic (<filename>genmake2 -ieee</>).
970	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	</listitem>
985	</varlistentry>
986
987	<varlistentry>
988	<term><filename>-tdir TESTDIR</></term>
989	<term><filename>-tdir 'TDIR1 TDIR2 [...]'</></term>
990	<listitem>
991	<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	directories in <filename>$ROOTDIR/verification/</>. If this
995	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	</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	<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	<term><filename>-MPI NUMBER_OF_PROCS</></term>
1017	<term><filename>-mpi</></term>
1018	<listitem>
1019	<para>If the necessary file (<filename>TESTDIR/code/SIZE.h_mpi</>)
1020	exists, then use it (and all <filename>TESTDIR/code/*_mpi</> files)
1021	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	test-experiment using variable number of MPI processors (multiple
1024	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	<para>Note that the use of MPI typically requires a
1029	special command option (see "-command" below) to invoke the MPI
1030	executable. Examples of PBS scripts using testreport with MPI can be
1031	found in the <ulink
1032	url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
1033	tools/example_scripts directory</ulink>.</para>
1034	</listitem>
1035	</varlistentry>
1036
1037	<varlistentry>
1038	<term><filename>-command='some command to run'</></term>
1039	<listitem>
1040	<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	command (or shell script) to be invoked. Examples of PBS scripts
1043	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	<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	</listitem>
1077	</varlistentry>
1078
1079	</variablelist>
1080
1081	<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
1097	<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	</sect3>
1104
1105	</sect2>
1106
1107
1108	<sect2 id="packages">
1109	<title>Creating MITgcm Packages</title>
1110
1111	<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	package names ${pkg}. A concrete examples of a package is the code for
1119	implementing GM/Redi mixing. This code uses the package name</para>
1120
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	the package name
1144	* ${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	Note: In some packages, the header file "${PKG}.h" is splitted
1179	into "${PKG}_PARAMS.h" that contains the package parameters and
1180	${PKG}_VARS.h" for the field arrays.
1181
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	from a PACKAGES_CONFIG.h file that is automatically
1204	generated by genmake2 (see genmake2 section).
1205	held in-line in the CPP_OPTIONS.h header file.
1206	e.g.
1207
1208	Core model code .....
1209
1210	#include "PACKAGES_CONFIG.h"
1211	#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	specific to that package. It also includes
1223	"PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
1224
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
1237
1238	2. S/R PACKAGES_READPARMS()
1239	:
1240	#ifdef ALLOW_${PKG}
1241	if ( use${Pkg} )
1242	& CALL ${PKG}_READPARMS( retCode )
1243	#endif
1244
1245	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	:
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	5. S/R PACKAGES_INIT_VARIABLES()
1263	:
1264	#ifdef ALLOW_${PKG}
1265	if ( use${Pkg} )
1266	& 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	& CALL ${PKG}_OUTPUT( )
1276	#endif
1277
1278	7. S/R PACKAGES_WRITE_PICKUP()
1279
1280	#ifdef ALLOW_${PKG}
1281	if ( use${Pkg} )
1282	& CALL ${PKG}_WRITE_PICKUP( )
1283	#endif
1284
1285	Description
1286	===========
1287
1288	- ${PKG}_READPARMS()
1289	is responsible for reading
1290	in the package parameters file data.${pkg}, and storing
1291	the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
1292	-> called from INITIALISE_FIXED in PACKAGES_READPARMS
1293
1294	- ${PKG}_INIT_FIXED()
1295	is responsible for completing the internal setup of a package.
1296	-> 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
1301	- ${PKG}_CHECK()
1302	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	-> called from INITIALISE_FIXED in PACKAGES_CHECK
1309
1310	- ${PKG}_INIT_VARIA()
1311	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	This routine is called after the core model state has been completely
1315	initialised but before the core model timestepping starts.
1316	-> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
1317	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	form ${PKG}_INIT
1320
1321	- ${PKG}_OUTPUT( )
1322	is responsible for writing time-average fields to output files
1323	(but the cumulating step is done within the package main S/R).
1324	Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
1325	and write snap-shot fields that are hold in common blocks. Other
1326	temporary fields are directly dump to file where they are available.
1327	NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
1328	but is beeing replaced by ${PKG}_OUTPUT
1329	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	-> called within DO_THE_MODEL_IO
1333
1334	- ${PKG}_WRITE_PICKUP()
1335	is responsible for writing a package pickup file when necessary for
1336	a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
1337	-> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
1338
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	or ${PKG}_PARAMS.h package-specific common block parameters
1359	and ${PKG}_VARS.h package-specific common block fields
1360
1361	- FORTRAN source files
1362	-----------------------
1363	* ${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	* ${pkg}_output.F write output to file.
1369	* ${pkg}_write_pickup.F write a package pickup file to restart the model
1370
1371	New: Subroutine in one package (pkgA) that only contains code which
1372	is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
1373	will be named: pkgA_pkgB_something.F
1374
1375	- parameter file
1376	-----------------------
1377	* data.${pkg} parameter file
1378	</programlisting>
1379
1380	</sect1>
1381
1382
1383	<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
1429	<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
1448
1449
1450	</sect2>
1451
1452	<sect2>
1453	<title>Building the Documentation</title>
1454
1455	<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	</article>

	ViewVC Help
Powered by ViewVC 1.1.22

Contents of /MITgcm/doc/devel_HOWTO.sgml