Unlike many open source projects, the MITgcm CVS tree does not follow a simple "src", "docs", "share", and "test" directory layout. Instead, there are multiple higher-level directories that each, to some extent, depend upon the presence of the others. The tree currently resembles:
gcmpack/
MITgcm-contrib contributed code
CS-regrid goes into utils
cvspolicy.html -save-
CVSROOT -save-
development experimental stuff
manual -save-
misc -?-
MITgcm code
adjoint fold into genmake
bin stub for ecco build
compare01 old from 20th century
diags timeave f77 in pkgs now
doc tags -- connect to real docs?
eesupp cnh?
exe ecco user build
,- jobs runtime shell scripts for
| various platforms
| lsopt line search
m| model main dynamics (core)
e| optimization_drivers ?
r| optim line search interface
g| pkg alternate and optional numerics, etc.
e|- tools
?| tutorial_examples documented tests
| only populated on release1 branch
| and not validated during "testscript"
'- utils
verification std tests
mitgcmdoc -> manual -remove-
mitgcm.org build web site
models -?-
packages -?-
preprocess -?-
tmp -?-Efforts are underway to reduce the complexity.
As shown in the online ViewCVS-generated tree, the MITgcm codebase is split into to two branches or "lines" under which development proceeds. These two lines are referred to as the "MAIN" and "ecco" versions of the code. While not identical, the bulk of the MAIN and ecco lines are composed of files from the same codebase.
Periodically, a "Release" branch is formed from the "MAIN" development branch. This is done in order to create a relatively stable reference point for both users and developers. The intent is that once a relese branch has been created, only bug-fixes will be added to it. Meanwhile, development (which might "break" or otherwise render invalid the documentation, tutorials, and/or examples contained within a release branch) is allowed to continue along the MAIN and ecco lines.
The intent of tagging is to create "known-good" checkpoints that developers can use as references. Traditionally, MITgcm tagging has maintained the following conventions:
Developer checks out code into a local CVS-managed directory, makes various changes/additions, tests these edits, and eventually reaches a point where (s)he is satisfied that the changes form a new "useful" point in the evolution of the code.
The developer then runs the testscript shell script to see if any problems are introduced. While not intended to be exhaustive, the test cases within the verification directory do provide some indication whether gross errors have been introduced.
Having satisfied him- or herself that the changes are ready to be committed to the CVS repository, the developer then:
adds a "checkpointXY_pre" comment (where X is a checkpoint number and Y is a letter) to the tag-index file and checks it into the CVS repository
submits the set of changes to the CVS repository and adds comments to tag-index describing what the changes are along with a matching "checkpointXY_post" entry
The result of this tagging procedure is a sequence of development checkpoints with comments which resembles:
checkpoint50e_post 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 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 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, so that writing to internal file fn (with length 512) fails. checkpoint50d_pre
This information can be used to refer to various stages of the code development. For example, bugs can be traced to individual sets of CVS checkins based upon their first appearance when comparing the results from different checkpoints.