--- MITgcm/doc/devel_HOWTO.sgml 2010/05/15 01:44:50 1.13
+++ MITgcm/doc/devel_HOWTO.sgml 2012/05/16 02:33:48 1.17
@@ -1,6 +1,6 @@
@@ -31,7 +31,7 @@
2010-01-21
jmc
- update links.
+ Update links.
@@ -42,6 +42,14 @@
Add subsection "Developer settings" (under CVS Repository).
+
+ 0.04
+ 2011-04-24
+ jmc
+
+ Update subsection "The verification suite".
+
+
@@ -132,7 +140,7 @@
doc basic developpment documentation
eesupp execution environment support code (wrapper)
exe empty
- jobs runtime shell scripts for
+ jobs runtime shell scripts for
various platforms (not maintained)
lsopt line search
model main dynamics (core)
@@ -151,7 +159,7 @@
gfd_lab -?-
manual source of MITgcm documentation
mitgcm.org build web site
- old_develop old and early development source
+ old_develop old and early development source
misc -?-
models -?-
packages -?-
@@ -220,68 +228,73 @@
Developer settings
- CVS is a convenient tool to keep up-to-date a personal copy of the
- MITgcm code (see:
- using CVS ). The same tool is used by developers to
+ CVS is a convenient tool to keep up-to-date a personal copy of the
+ MITgcm code (see:
+ using CVS ). The same tool is used by developers to
incorporate any change into the repository. However, this later
- function requires specific settings, as detailed here after:
+ function requires specific settings, as detailed here after
- You will need an account (loggin access) to the server
- "mitgcm.org" with the proper group setting (e.g.,
- group "gcmctrb" to add/modify code into MITgcm_contrib).
- This kind of account is granted only upon well motivated request.
- The access to the server mitgcm.org is through ssh-key authorization
- which will need to be set properly on both side (on your local machine
- and on your server account). You need to be able to
- to ssh to mitgcm.org (or ssh MY_USER_NAME@mitgcm.org
- in case of different user-name on both sides) to proceed further.
+ You will need an account (login access) to the server
+ "mitgcm.org" (curently: forge.csail.mit.edu)
+ with the proper group setting (e.g., group "gcmctrb" to add/modify
+ code into MITgcm_contrib).
+ This kind of account is granted only upon well motivated request
+ (we recommend to ask your senior MITgcm-collaborator to send such
+ request to marshall-admin at techsquare.com with Cc to Chris Hill
+ for approval).
+ The access to the server mitgcm.org is
+ through ssh-key authorization which will need to be set properly on
+ both side (on your local machine and on your server account).
+ You need to be able to ssh to mitgcm.org
+ (or ssh MY_USER_NAME@mitgcm.org
+ in case of different user-name on both sides) to proceed further.
- You need to register to the
-
- mitgcm-cvs mailing list.
- This ensures that other developers will receive email notification
- when you make changes; you will also receive as well such email
+ You need to register to the
+
+ mitgcm-cvs mailing list.
+ This ensures that other developers will receive email notification
+ when you make changes; you will also receive such email
when others make changes to the repository.
- It is highly recommended that you register also to the
-
- mitgcm-devel mailing list (expect a short delay for
+ It is highly recommended that you register also to the
+
+ mitgcm-devel mailing list (expect a short delay for
this request to be processed).
This list is intended for developer discussions.
- The standard anonymous mode (using "cvsanon", as mentionned
-
- here ) does not allow check-in ("cvs commit") permission.
+ The standard CVS-anonymous mode (using "cvsanon",
+ as mentionned
+ here ) does not provide check-in ("cvs commit") permission.
Instead, you will need to set our CVS environment as follow:
$ export CVS_RSH=ssh
$ export CVSROOT=':ext:MY_USER_NAME@mitgcm.org:/u/gcmpack'
- After downloading a directory, e.g.: myCopy,
- from the CVS repository (e.g.,
+ The reason for such limitation is that when downloading a directory,
+ e.g.: myCopy, from the CVS repository (e.g.,
MITgcm_contrib/thisPart) using the command:
$ cvs co -P -d myCopy MITgcm_contrib/thisPart
- the type of CVS environment which has been used
- is stored in the file myCopy/CVS/Root
- and makes it difficult to re-use, for cvs-commit purpose,
- a cvs local copy (myCopy) which was obtained
+ the type of CVS environment which has been used
+ is stored in the file myCopy/CVS/Root.
+ This prevent to re-use, for cvs-commit purpose,
+ a cvs local copy (myCopy) which was obtained
using the CVS anonymous mode.
- At this stage, you should be able to send your modified source
- file (e.g., src_file) from your local copy directory
+ At this stage, you should be able to send your modified source
+ file (e.g., src_file) from your local copy directory
(myCopy) to the CVS repository
(MITgcm_contrib/thisPart) using the command
"cvs commit":
@@ -291,10 +304,20 @@
$ cvs diff src_file (optional; list your changes)
$ cvs commit src_file
- It is essential that you provide a short description of the
- changes you made to src_file as you check-in
- this file (the "cvs commit" command automatically opens your standard
+ It is essential that you provide a short description of the
+ changes you made to src_file as you check-in
+ this file (the "cvs commit" command automatically opens your standard
editor for this purpose).
+ Note:
+ Please ignore the following warnings that the "cvs commit" command
+ produces if you are not part of the "gcmpack" group:
+
+ cvs commit: failed to create lock directory for `/u/gcmpack/CVSROOT'
+ (/u/gcmpack/CVSROOT/#cvs.history.lock): Permission denied
+ cvs commit: failed to obtain history lock in repository `/u/gcmpack'
+
+ These warnings are not affecting the changes you made to the CVS repository.
+
@@ -303,7 +326,8 @@
Main code development
- (formerly named "Tagging" ; this section needs an update)
+ (formerly named "Tagging" ; this section needs an update)
+
The intent of tagging is to create "known-good" checkpoints that
developers can use as references. Traditionally, MITgcm tagging has
@@ -356,17 +380,17 @@
o make KPP work with PTRACERS
- fix gad_calc_rhs to call new routine kpp_transport_ptr, which is
nearly a copy of kpp_transport_s
- - there is no analogue to SurfaceTendencyS, so I have to use
+ - there is no analogue to SurfaceTendencyS, so I have to use
gPtr(of the surface layer) instead
o add a new platform SunFire+mpi (SunFire 15000) to genmake
checkpoint50e_pre
checkpoint50d_post
-o change kpp output from multiple-record state files to single-record state
+o change kpp output from multiple-record state files to single-record state
files analogous to write_state.F
-o reduce the output frequency of cg3d-related stuff to the monitor frequency,
- analogous to the cg2d-related output.
-o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
+o reduce the output frequency of cg3d-related stuff to the monitor frequency,
+ analogous to the cg2d-related output.
+o fix small problem with in ptracers_write_checkpoint.F: len(suff)=512,
so that writing to internal file fn (with length 512) fails.
checkpoint50d_pre
@@ -393,20 +417,19 @@
For MITgcm, the process is similar. Typical commands are:
- $ genmake -mods=../code
+ $ genmake2 -mods=../code
$ make depend
$ make
The following sections describe the individual steps in the build
process.
-
+
The genmake2> Utility
- Please note that the older genmake> is
- deprecated and will eventually be replaced by genmake2>.
- This HOWTO only describes the newer tool.
+ (Note: the older genmake>
+ has been replaced by genmake2>)
The first step in any MITgcm build is to create a Unix-style
Makefile which will be parsed by
@@ -462,6 +485,12 @@
an "options file" as specified by the command-line option
-optfile='FILENAME'
+
+ a packages.conf file (in the current
+ directory or in one of the "MODS" directories, see below)
+ which contains the specific list of packages to compile
+
+
then checking certain dependency rules (the package dependencies),
@@ -515,33 +544,6 @@
- -pdepend=/PATH/FILENAME>
-
-
- This specifies the dependency file used for packages. If
- not specified, the default dependency file is
- $ROOTDIR/pkg/pkg_depend>. The syntax for this file is
- parsed on a line-by-line basis where each line containes either a
- comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
- where the "+" or "-" symbol specifies a "must be used with" or a
- "must not be used with" relationship, respectively. If no rule is
- specified, then it is assumed that the two packages are compatible
- and will function either with or without each other.
-
-
-
-
- -pdefault=PKG>
- -pdefault='PKG1 [PKG2 PKG3 ...]'>
-
- This option specifies the default set of packages
- to be used. If not set, the default package list will
- be read from
- $ROOTDIR/pkg/pkg_default>.
-
-
-
-
-adof=/path/to/file>
-adoptfile=/path/to/file>
@@ -569,19 +571,49 @@
will be overridden by any identically-named sources within the
"MODS" directories. The order of precedence for this
"name-hiding" is as follows:
-
"MODS" directories (in the order given)
Packages either explicitly specified or
provided by default (in the order given)
Packages included due to package dependencies
- (in the order that that package dependencies are
+ (in the order that that package dependencies are
parsed)
The "standard dirs" (which may have been
specified by the "-standarddirs" option)
+
+
+
+
+ -pgroups=/PATH/FILENAME>
+
+ This option specifies the file where package groups are
+ defined. If not set, the package-groups definition will
+ be read from
+ $ROOTDIR/pkg/pkg_groups>.
+
+ It also contains the default list of packages (defined
+ as the group "default_pkg_list">) which is used
+ when no specific package list (file: packages.conf>)
+ is found in current directory or in any "MODS" directory.
+
+
+
+
+
+ -pdepend=/PATH/FILENAME>
+
+ This specifies the dependency file used for packages. If
+ not specified, the default dependency file is
+ $ROOTDIR/pkg/pkg_depend>. The syntax for this file is
+ parsed on a line-by-line basis where each line containes either a
+ comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule
+ where the "+" or "-" symbol specifies a "must be used with" or a
+ "must not be used with" relationship, respectively. If no rule is
+ specified, then it is assumed that the two packages are compatible
+ and will function either with or without each other.
@@ -607,7 +639,7 @@
In general, it is best to use genmake2> on a "clean"
directory that is free of all source (*.[F,f],*.[F,f]90) and header
(*.h,*.inc) files. Generally, this can be accomplished in an
- "un-clean" directory by running "make CLEAN" followed by "make
+ "un-clean" directory by running "make Clean" followed by "make
makefile".
@@ -620,16 +652,18 @@
simulator) executable using:
- $ make CLEAN
+ $ make Clean
$ make depend
$ make
- The "make CLEAN" step will remove any stale source files, include
+ The "make Clean" step will remove any stale source files, include
files, and links. It is strongly recommended for "un-clean"
directories which may contain the (perhaps partial) results of
- previous builds. Such "debris" can interfere with the next stage of
- the build.
+ previous builds. Such "debris" can interfere with the next stage of
+ the build.
+ A more agressive cleaning option, "make CLEAN", can be used to also
+ remove the executable and output files from a previous run.
The "make depend" step will create a large number of symbolic
links from the local directory to the source file locations. It also
@@ -662,7 +696,7 @@
This target produces an mitgcmuv_ad> executable
using the taf> or staf> adjoint
- compiler. See the genmake2> "-adof" option for
+ compiler. See the genmake2> "-adof" option for
compiler selection.
@@ -688,39 +722,253 @@
The Verification Suite
The MITgcm CVS tree (within the $ROOTDIR/verification/>
- directory) includes more than a dozen examples intended for regression
- testing. Each one of these example directories contains "known-good"
+ directory) includes many (> 90) examples intended for regression
+ testing. Each one of these test-experiment directories contains "known-good"
output files along with all the input (including both code and data
- files) required for their re-calculation. These example directories are
- further broken down into sets of subdirectories
- (eg. /input>, /code>) intended to expedite the
- testing process.
+ files) required for their re-calculation.
+ Also included in $ROOTDIR/verification/> is the shell
+ script testreport> to perform regression tests.
+
+
+ Test-experiment Directory Content
+
+ Each test-experiment directory (TESTDIR>) contains
+ several standard subdirectories and files which testreport>
+ recognizes and uses when running a regression test.
+ The directories/files that testreport> uses are different
+ for a forward test and an adjoint test (testreport -adm>)
+ and some test-experiments are set-up for only one type of regression
+ test whereas others allow both types of tests (forward and adjoint).
+ Also some test-experiment allows, using the same MITgcm executable,
+ to perform multiple tests using different parameters and input files,
+ with a primary input set-up
+ (input/ > or input_ad/ >)
+ and corresponding results (results/output.txt> or
+ results/output_adm.txt>) and with one or several secondary
+ inputs (input.OTHER/ > or input_ad.OTHER/ >)
+ and corresponding results (results/output.OTHER.txt >
+ or results/output_adm.OTHER.txt>).
+
+
+
+ directory TESTDIR/results/>
+
+ contains reference standard output used for test comparison.
+ results/output.txt> and
+ results/output_adm.txt>
+ correspond respectively to primary forward and adjoint test
+ run on the reference platform (currently
+ baudelaire.csail.mit.edu>)
+ on one processor (no MPI, single thread)
+ using the reference compiler (curently the GNU fortran
+ compiler gfortran>).
+ The presence of these files determines whether or not
+ testreport> is testing or skipping
+ this test-experiment.
+ Reference standard output for secondary tests
+ (results/output.OTHER.txt>
+ or results/output_adm.OTHER.txt>) are
+ also expected here.
+ The test comparison involves few model variables output, which are,
+ by default and for a forward test, the 2-D solver initial residual
+ (cg2d_init_res>) and 3-D state variables (T,S,U,V)
+ monitor output, and, by default and for an adjoint test, the
+ cost-function and gradient-check. However, some test-experiments
+ use some package-specific variable/monitor output according to
+ the file TESTDIR/input[_ad][.OTHER]/tr_checklist>
+ specification.
+
+
+
+
+ directory TESTDIR/build/>
+
+ initially empty directory where testreport>
+ will build the MITgcm executable for forward and adjoint test.
+ It might contains an experiment specific
+ genmake_local> file (see ).
+
+ Note that the original code[_ad]/SIZE.h_mpi>
+ is not directly used as "SIZE.h" to build an MPI-executable ;
+ instead, a local copy build/SIZE.h.mpi> is derived
+ from code[_ad]/SIZE.h_mpi>
+ by adjusting the number of processors (nPx,nPy) according to
+ NUMBER_OF_PROCS> (see ,
+ testreport -MPI>) ; then it is linked to "SIZE.h"
+ ( ln -s SIZE.h.mpi SIZE.h >) before building
+ the MPI-executable.
+
+
+
+
+ directory TESTDIR/code/>
+
+ contains the test-experiment specific source code
+ used to build the MITgcm executable (mitgcmuv>)
+ for forward-test (using genmake2 -mods=../code>).
+
+ It can also contain specific source files with the suffix
+ "_mpi>" to be used
+
+ in place of the corresponding file (without suffix)
+ for an MPI test (see ).
+ The presence or absence of SIZE.h_mpi>
+ determines whether or not an MPI test on this
+ test-experiment is performed or skipped.
+
+
+
+
+ directory TESTDIR/code_ad/>
+
+ contains the test-experiment specific source code
+ used to build the MITgcm executable (mitgcmuv_ad>)
+ for adjoint-test (using genmake2 -mods=../code_ad>).
+ It can also contain specific source files with the suffix
+ "_mpi>" (see above).
+
+
+
+
+ directory TESTDIR/input/>
+
+ contains the input and parameter files
+ used to run the primary forward test of this test-experiment.
+
+ It can also contain specific parameter files with the suffix
+ ".mpi>" to be used
+
+ in place of the corresponding file (without suffix) for MPI
+ test, or with suffix ".mth>" to be used for
+ multi-threaded test (see ).
+ The presence or absence of eedata.mth>
+ determines whether or not a multi-threaded test on this
+ test-experiment is performed or skipped.
+ To save disk space and reduce downloading time, multiple
+ copies of the same input file is avoided by using a shell
+ script prepare_run>.
+ When such a script is found in TESTDIR/input/ >,
+ testreport> run this script in directory
+ TESTDIR/run/ > after linking all the input file
+ from TESTDIR/input/ >.
+
+
+
+
+
+ directory TESTDIR/input_ad/>
+
+ contains the input and parameter files
+ used to run the primary adjoint test of this test-experiment.
+ It can also contain specific parameter files with the suffix
+ ".mpi>" and shell script prepare_run>
+ as described above.
+
+
+
+
+ directory TESTDIR/input.OTHER/>
+
+ contains the input and parameter files
+ used to run the secondary OTHER forward test of this test-experiment.
+ It can also contain specific parameter files with suffix
+ ".mpi>" or ".mth>" and shell script
+ prepare_run> (see above).
+ The presence or absence the file eedata.mth>
+ determines whether or not a secondary multi-threaded test on this
+ test-experiment is performed or skipped.
+
+
+
+
+ directory TESTDIR/input_ad.OTHER/>
+
+ contains the input and parameter files
+ used to run the secondary OTHER adjoint test of this test-experiment.
+ It can also contain specific parameter files with the suffix
+ ".mpi>" and shell script prepare_run>
+ (see above).
+
+
+
+
+ directory TESTDIR/run/>
+
+ initially empty directory where testreport>
+ will run the MITgcm executable for primary forward and adjoint
+ test.
+ Symbolic links (using command "ln -s>") are made
+ for input and parameter files (from ../input/ >
+ or from ../input_ad/ >) and for MITgcm executable
+ (from ../build/ >) before the run proceeds.
+ The sequence of links (function linkdata> within shell
+ script testreport>) for a forward test is:
+
+* link+rename or remove links
+ to special files with suffix ".mpi" or ".mth" from ../input/
+* link files from ../input/
+* execute ../input/prepare_run (if it exists)
+
+ The sequence for an ajoint test is similar, with
+ ../input_ad/ > replacing ../input/ >.
+
+
+
+
+
+ directory TESTDIR/tr_run.OTHER/>
+
+ directory created by testreport>
+ to run the MITgcm executable for secondary "OTHER" forward
+ or adjoint test.
+ The sequence of links for a forward secondary test is:
+
+* link+rename or remove links
+ to special files with suffix ".mpi" or ".mth" from ../input.OTHER/
+* link files from ../input.OTHER/
+* execute ../input.OTHER/prepare_run (if it exists)
+* link files from ../input/
+* execute ../input/prepare_run (if it exists)
+
+ The sequence for an ajoint test is similar, with
+ ../input_ad.OTHER/ > and ../input_ad/ >
+ replacing ../input.OTHER/ > and ../input/ >.
+
+
+
+
+
+
The testreport> Utility
- Also included in $ROOTDIR/verification/> are shell
- scripts for automated testing. The newest script (which was written
- to work with genmake2>) is called testreport>.
- This script can be used to build different versions of the MITgcm
- code, run the various examples, compare the output, and (if specified)
- email the results of each one of these tests to a central
- repository.
+ The shell script testreport> (in
+ $ROOTDIR/verification/>), which was written to work with
+ genmake2>, can be used to build different versions
+ of the MITgcm code, run the various examples, compare the output,
+ and (if specified) email the results of each one of these tests to a
+ central repository.
On some systems, the testreport script can be run with a command
line as simple as:
$ cd verification
- $ ./testreport -ieee
+ $ ./testreport
However, some systems (those lacking or wiht a broken "/bin/sh")
may require an explicit shell invocation such as:
- $ sh ./testreport -ieee -t 'exp0 exp4'
- $ /some/path/to/bash ./testreport -ieee -t 'ideal_2D_oce lab_sea natl_box'
+ $ sh ./testreport -t 'exp2 exp4'
+ $ /some/path/to/bash ./testreport -t 'ideal_2D_oce lab_sea natl_box'
The testreport> script accepts a number of
@@ -730,11 +978,24 @@
- -ieee>
+ -ieee> (default) / -noieee>
If allowed by the compiler (as defined in the "optfile"),
- use IEEE arithmetic. This option, along with the GCC compiler,
- is how the standard results were produced.
+ use IEEE arithmetic (genmake2 -ieee>).
+ This option, along with the gfortran / gcc compiler,
+ is how the standard results are produced.
+
+
+
+
+ -optfile=/PATH/FILENAME>
+ -optfile '/PATH/F1 [/PATH/F2 ...]'>
+
+ This specifies a list of "options files" that will be passed
+ to genmake2>. If multiple options files are used
+ (say, to test different compilers or different sets of options
+ for the same compiler), then each options file will be used with
+ each of the test directories.
@@ -745,7 +1006,7 @@
This option specifies the test directory or list of test
directories that should be used. Each of these entries should
exactly (note: they are case sensitive!) match the names of
- directries in $ROOTDIR/verification/>. If this
+ directories in $ROOTDIR/verification/>. If this
option is omitted, then all directories that are properly
formatted (that is, containing an input>
sub-directory and a results/output.txt> file) will
@@ -754,18 +1015,6 @@
- -optfile=/PATH/FILENAME>
- -optfile '/PATH/F1 [/PATH/F2 ...]'>
-
- This specifies a list of "options files" that will be passed
- to genmake2>. If multiple options files are used
- (say, to test different compilers or different sets of options
- for the same compiler), then each options file will be used with
- each of the test directories.
-
-
-
-
-addr EMAIL>
-addr 'EMAIL1 EMAIL2 [...]'>
@@ -779,39 +1028,93 @@
+ -MPI NUMBER_OF_PROCS>
-mpi>
- If the necessary files
- (TESTDIR/code/CPP_EEOPTIONS.h_mpi> and
- TESTDIR/code/SIZE.h_mpi>) exist, then use them for an
- MPI--enabled run. Note that the use of MPI typically requires a
+ If the necessary file (TESTDIR/code/SIZE.h_mpi>)
+ exists, then use it (and all TESTDIR/code/*_mpi> files)
+ for an MPI--enabled run. The new option (-MPI> followed
+ by the maximum number of processors) enable to build and run each
+ test-experiment using variable number of MPI processors (multiple
+ of nPx*nPy> from TESTDIR/code/SIZE.h_mpi>
+ and not larger than NUMBER_OF_PROCS>).
+ The short option ("-mpi") can only be used to build and run on 2 MPI
+ processors (equivalent to "-MPI 2>").
+ Note that the use of MPI typically requires a
special command option (see "-command" below) to invoke the MPI
- executable. Examples of PBS scripts using MPI with testreport can be
+ executable. Examples of PBS scripts using testreport with MPI can be
found in the
- MITgcm-contrib area
+ url="http://mitgcm.org/viewvc/MITgcm/MITgcm/tools/example_scripts/">
+ tools/example_scripts directory.
-command='some command to run'>
- For some tests, particularly MPI runs, the default "make
- output.txt" is not sufficient. This option allows a more general
+ For some tests, particularly MPI runs, a specific command
+ might be needed to run the executable. This option allows a more general
command (or shell script) to be invoked. Examples of PBS scripts
- using MPI with testreport can be found in the
- MITgcm-contrib area
+ using testreport with MPI can be found in the
+ tools/example_scripts directory.
+
+ For the case where the number of MPI processors varies according
+ to each test-experiment, some key-words within the command-to-run
+ argument will be replaced by their effective value:
+
+ TR_NPROC > will be replaced by the actual number
+ of MPI processors needed to run the current test-experiment.
+
+ TR_MFILE > will be replaced by the name of local-file
+ that testreport creates from the full list of machines which
+ "testreport -mf MACHINE_FILE>" provides, but truncated
+ to the exact number of machines.
+
+
+
+
+ -mf MACHINE_FILE>
+
+
+ To use with -MPI NUMBER_OF_PROCS> option, to specify
+ the file containing the full list of NUMBER_OF_PROCS>
+ machines to use for the MPI runs.
+
+
+
+
+ -mth>
+
+ compile (with genmake2 -omp>) and run with
+ multiple threads (using eedata.mth).
- The testreport> script will write progress to the
- screen (stdout) as it runs. In addition, it will create a
- tr_out.txt> file that contains a brief comparison of the
- current output with the "known-good" output.
+ The testreport> script will create an output directory
+ tr_NAME_DATE_N/ >, with hostname> as default
+ NAME>, DATE> the current date followed by
+ a suffix number "N" to distinguish from previous
+ testreport> output directories.
+ testreport> writes progress to the screen (stdout)
+ and reports into the ouput directory as it runs.
+ In particular, one can find, in the ouput directory,
+ the summary.txt> file that contains a brief comparison
+ of the current output with the "known-good" output.
+ At the end of the testing process, the tr_out.txt> file
+ is generated in $ROOTDIR/verification/ >
+ as a compact version of summry.txt> file.
+
+
+
+ The do_tst_2+2> Utility
+ The shell script do_tst_2+2> (in
+ $ROOTDIR/tools/ >)
+ can be used to check the accuracy of the restart procedure.
+
@@ -852,7 +1155,7 @@
below using generic package names ${pkg}.
A concrete examples of a package is the code
for implementing GM/Redi mixing. This code uses
-the package name
+the package name
* ${PKG} = GMREDI
* ${pkg} = gmredi
* ${Pkg} = gmRedi
@@ -887,8 +1190,8 @@
Package runtime config. options are imported
into a common block held in a header file
called "${PKG}.h".
- Note: In some packages, the header file "${PKG}.h" is splitted
- into "${PKG}_PARAMS.h" that contains the package parameters and
+ Note: In some packages, the header file "${PKG}.h" is splitted
+ into "${PKG}_PARAMS.h" that contains the package parameters and
${PKG}_VARS.h" for the field arrays.
o The core driver part of the model can check
@@ -912,7 +1215,7 @@
1. Within the core driver code flags of the form
ALLOW_${PKG} are used to include or exclude
whole packages. The ALLOW_${PKG} flags are included
- from a PACKAGES_CONFIG.h file that is automatically
+ from a PACKAGES_CONFIG.h file that is automatically
generated by genmake2 (see genmake2 section).
held in-line in the CPP_OPTIONS.h header file.
e.g.
@@ -931,7 +1234,7 @@
2. Within an individual package a header file,
"${PKG}_OPTIONS.h", is used to set CPP flags
- specific to that package. It also includes
+ specific to that package. It also includes
"PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
@@ -945,7 +1248,7 @@
1. S/R PACKAGES_BOOT()
:
CALL OPEN_COPY_DATA_FILE( 'data.pkg', 'PACKAGES_BOOT', ... )
-
+
2. S/R PACKAGES_READPARMS()
:
@@ -997,20 +1300,20 @@
Description
===========
- - ${PKG}_READPARMS()
+ - ${PKG}_READPARMS()
is responsible for reading
in the package parameters file data.${pkg}, and storing
the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
-> called from INITIALISE_FIXED in PACKAGES_READPARMS
- - ${PKG}_INIT_FIXED()
- is responsible for completing the internal setup of a package.
+ - ${PKG}_INIT_FIXED()
+ is responsible for completing the internal setup of a package.
-> called from INITIALISE_FIXED in PACKAGES_INIT_FIXED
note: 1) some pkg use instead:
CALL ${PKG}_INITIALISE ( or the old form CALL ${PKG}_INIT )
2) for simple pkg setup, this part is done inside ${PKG}_READPARMS
- - ${PKG}_CHECK()
+ - ${PKG}_CHECK()
is responsible for validating
basic package setup and inter-package dependencies.
${PKG}_CHECK can import other package parameters it may
@@ -1019,32 +1322,32 @@
will not be reset during ${PKG}_CHECK().
-> called from INITIALISE_FIXED in PACKAGES_CHECK
- - ${PKG}_INIT_VARIA()
+ - ${PKG}_INIT_VARIA()
is responsible for fill-in all package variables with an initial value.
Contains eventually a call to ${PKG}_READ_PICKUP that will read
from a pickup file the package variables required to restart the model.
- This routine is called after the core model state has been completely
+ This routine is called after the core model state has been completely
initialised but before the core model timestepping starts.
-> called from INITIALISE_VARIA in PACKAGES_INIT_VARIABLES
- note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
- use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
+ note: the name ${PKG}_INIT_VARIA is not yet standard and some pkg
+ use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old
form ${PKG}_INIT
- ${PKG}_OUTPUT( )
is responsible for writing time-average fields to output files
(but the cumulating step is done within the package main S/R).
- Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
- and write snap-shot fields that are hold in common blocks. Other
+ Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR)
+ and write snap-shot fields that are hold in common blocks. Other
temporary fields are directly dump to file where they are available.
- NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
+ NOTE: 1) the S/R old name ${PKG}_DIAGS is used in some packages
but is beeing replaced by ${PKG}_OUTPUT
to avoid confusion with pkg/diagnostics functionality.
2) the output part is not yet in a standard form and might still
evolve a lot.
-> called within DO_THE_MODEL_IO
- - ${PKG}_WRITE_PICKUP()
- is responsible for writing a package pickup file when necessary for
+ - ${PKG}_WRITE_PICKUP()
+ is responsible for writing a package pickup file when necessary for
a restart. (found also the old name: ${PKG}_WRITE_CHECKPOINT )
-> called from FORWARD_STEP and THE_MODEL_MAIN in PACKAGES_WRITE_PICKUP
@@ -1080,7 +1383,7 @@
* ${pkg}_output.F write output to file.
* ${pkg}_write_pickup.F write a package pickup file to restart the model
- New: Subroutine in one package (pkgA) that only contains code which
+ New: Subroutine in one package (pkgA) that only contains code which
is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
will be named: pkgA_pkgB_something.F
@@ -1137,7 +1440,7 @@
the CVS tree.
The result is a command that resembles either
-
+
a reference to a variable or subroutine name such as
@@ -1156,14 +1459,14 @@
into a "-")
-
+
Building the Documentation
-
+
Given the directory structure of , the entire documentation for the web
site can be built using: