Revised in this version: code documentation information in Section 8, CCSM references were changed to CESM, and old links were commented out.

Previous Version

The procedures contained in this guide, which apply only to the CESM version of pop2, are intended to

• provide guidance to developers who wish to contribute to CESM pop2 model development
• result in easy-to-understand and easy-to-maintain CESM pop2 code
• allow for the orderly and timely integration of model improvements onto the CESM pop2 repository trunk

These guidelines comprise a "living document," subject to occasional revisions and updates as procedures evolve or requirements change.

Collaboration

Developers are encouraged to contact local OMWG pop2 developers at any point during the development cycle to resolve questions regarding these guidelines. Phone calls, hallway discussions, or quick, informal meetings are all good ways to maintain communications during the development process.

Design Review

Prior to undertaking new, significant pop2 developments, developers are encouraged to engage with local Ocean Model Working Group (OMWG) members to discuss their prospective work. Informal design discussions can result in valuable, early feedback that can often ultimately reduce the time of the development cycle.

Code Base

New pop2 developments should originate from a version as close to the most recent pop2 trunk tag as is reasonably possible. Using an older, outdated code base increases the complexity of the code review and merging processes, and it increases the probability of errors. Merging new developments based on a highly outdated code base into the most recent pop2 trunk code is the responsibility of the developer.

Coding Guidelines

As closely as possible, all pop2 code developments should adhere to the following coding guidelines.

These guidelines are complicated by the fact that the present CESM pop2 code is undergoing a transition from LANL pop2-based coding style to the new LANL hypop/pop3-based style. In order to avoid internal inconsistencies, new code added to existing CESM pop2 modules should follow the coding style of the existing module; new modules should emulate the LANL hypop/pop3 modules.

• The "look and feel" of new code is as similar as possible to the LANL pop coding style. For examples, see any of the xyz.F90 or POP_xyz.F90 modules.
• The coding language is Fortran90; Fortran95 extensions are allowed.
• New module names are of the form POP_abcMod.F90, where "abc" is chosen to be a meaningful name.
• New module variable names:
  • follow most recent LANL POP examples as closely as possible
  • are of the form POP_variableName (to the same extent as in existing LANL POP_abc.F90 modules)
  • begin with the letter "l" when they are logical variables
• New subroutines in new modules are of the form POP_newSubroutineName.
• Modules maintain the LANL POP delimiter conventions (eg, at the beginning and end of module, inbetween subroutines, after Protex lines, etc).
• New "use" statements avoid the ", only" construct, and occur only at the module level, for as long as this is the LANL POP3 convention.
• Type declarations make use of the pop2 kinds, as defined in the pop kinds modules, kinds_mod.F90 and POP_KindsMod.F90.
• Module, subroutine, and code indentations follow the LANL POP conventions.
• Capitalization patterns follow the LANL POP conventions for variable names, array names, subroutine names, declarations, and commands. In particular, note that characters in multidimensional array names are all upper-case.
• Modules contain module-level comment lines that clearly describe the purpose of the module.
• Subroutines contain descriptive, meaningful subroutine-level comment lines.
• New modules and subroutines use Protex, as long as LANL requires it. New Protex code should follow the same conventions and style as in LANL code.
• The "intent" attribute of subroutine input/output variables is used, where possible.
• Subroutine comment lines follow the LANL POP conventions (horizontal and vertical spacing, delimiters, etc).
• Module and subroutine variables are documented, usually one per line.
• All variables are explicitly typed (explicit none).
• Module variables are typically saved (save).
• Modules typically declare default public/private values via the "public" and "private" statements at the module level.
• errorCode is used, following the LANL pop2 conventions. This is a new feature being phased into CESM pop2 code, but it is not yet fully functional.
• The "case" construct is preferred over if-then-else blocks.
• Fortran90 "deprecated features" are to be avoided (equivalence, common blocks, block data, etc).
• The initialization process (namelist read, documentation, etc) is done in the same format as LANL pop2 code.
• The stdout/POP_stdout units are "flushed" at the end of each initialization subroutine.
• Debugging statements should be eliminated prior to check-in. If debugging statements are allowed in checked-in code, they must be controlled by a logical control variable, and by default they must be disabled.
• C-preprossor (Cpp) options are to be avoided as much as possible; logical control variables are the highly preferred alternative. The use of new Cpp options will not be allowed in code that is checked into the pop2 trunk without OMWG review and approval. Even CESM-supported Cpp options are to be avoided, unless absolutely necessary.
• Existing, active pop2 trunk code must not be commented out, if-def'd out, removed, or otherwise deactivated unless approved by the code reviewers.
• Developers are encouraged to add option-conflict testing, where appropriate. The routine POP_check in module initial.F90 is the appropriate place for cross-module checking.
• Print statements are not allowed; use write instead.
• write(*,*) statements are not allowed; all write statements should be directed to an explicitly defined unit number.
• The CESM pop2 trunk code can be run in stand-alone mode, and new developments must not prevent the stand-alone model from compiling or running. Presently, the testing of the stand-alone model is done infrequently, by LANL staff. If future testing of the stand-alone version uncovers a problem with new code, the developer of that code will be asked to correct the problem.
• Remember the Turkish saying, "It takes 100 clever people to remove the stone thrown into the well by a crazy person."

Testing

Developers are responsible for testing their codes.
• Automated testing of pop2 developments is supported. A complete list of required tests is contained in each CESM tag, in the directory /scripts/ccsm_utils/Testlists/$machine.pop2.pretag.

  The most current test list is contained in the most recent CESM tag. The following is a list of required pop2 tests for code developed as of 28 March 2012:

  • ERS.T62_g16.C.bluefire
  • ERT.T62_g16.C.bluefire
  • PFS.T62_g16.C.bluefire
  • ERT.f19_g16.B1850CN.bluefire
  • ERH.f19_g16.B1850CN.bluefire
  • PET_PT.T31_g37.B.bluefire
  • ERS_PT.T31_g37.B.bluefire

• New pop2 developments must pass the $machine.pop2.pretag tests. The testing summary generated by the automated testing should be provided by the developer during the code-review process and sent to the gatekeeper after check-in approval is obtained.
• If any of the required tests fail, fixing the problem, which must be completed prior to check-in, is the developers' obligation, except under unusual circumstances.
• If testing of new developments identifies defects in existing pop2 code, the developer should file a CESM pop2 bug report with sufficient information for the problem to be replicated. Correcting the existing bug is usually the responsibility of local OWMG personnel.
• Note that testing of new codes is primarily targeted at the AR5 resolution. For pop2, that resolution is presently gx1v6, although that is subject to change. If a new development targets a particular resolution other than the AR5 resolution, then the developer should conduct tests at that resolution, in addition to the required tests described in this section.
• Testing of new physical parameterizations, in addition to the standard test suite, typically consist of the following. Coordination of these tests with the OMWG Co-chair is encouraged.
  • Ocean-only control run conducted at the AR5 target resolution
  • Series of sensitivity studies
  • Cost estimates and performance information
• Testing of new software-engineering developments, in addition to the standard test suite, typically consists of the following.
  • Cost estimates and performance information
  • For developments expected to be bit-for-bit identical, proof that solutions are bit-for-bit identical to the base code. This is demonstrated by differencing "old" and "new" binary ocean restart files after running for at least five days.
  • For developments expected to be the same "to roundoff level," correctness testing is more difficult and more subjective. A combination of the following tests is usually run:
    • Run an SMS.T62_g16.C case with the base code for several timesteps. This is the control case. Run a second case, identical to the control, except using the new code. Both cases should be configured to generate double-precision tavg history files and netCDF restart files at every model timestep. Difference the history and restart files and examine for obvious patterns or large (> 10^-8) diferences. Create timeseries of difference files, and examine for evolution of patterns (eg, use ncview in movie mode). Configure and run a third test, identical to the second, except using a different pe layout. Difference double-precision history and restart netCDF files from the control and third run, create a timeseries, and examine.
    • Run another SMS.T62_g16.C cases with the new code, identical to the second sensitivity test above, except with the solver convergence criterion smaller by one order of magnitude. Create a timeseries of RMS differences between the SSH solutions from this case and those from the second sensitivity test. Examine and review with the OMWG.

Code Review

When new developments are ready to be considered for the pop2 trunk, the developer schedules a code review/walkthrough with local OMWG members. To accomodate developers at remote sites, a walkthrough may be held via telecon or other such means.

The Code Review consists of the following elements:

• A summary description of the development, provided in writing by the developer, for documentation and education purposes. This summary is typically a short paragraph or two describing the development and/or changes made to the code, and it will be included in the formal documentation.
• A summary of all CESM tests passed, using the most recent CESM1 tag available.
• A summary of all special-purpose testing conducted by the developer. This summary lists all tests of the specific developments and confirms correctness of the new code. The special-purpose testing summary will be included as a part of the tag documentation.
• A walkthrough review of the actual code changes (additions,modifications,corrections). How the walkthrough is conducted is determined somewhat by the developer and the reviewers. Typically, the reviewers and the developer meet, and the developer walks everyone through the changes made to the base code. Usually, this involves:
  • a description of the development (equations, written summary, etc. Verbal descriptions are ok for simple mods, but written summary should be provided for check-in)
  • listings of new code
  • differences of old and new code (side-by side diffs and/or regular diffs, depending on the complexity of the differences)
  • information about any required datasets (plus full documentation -- see template)

  Paper or on-screen documentation is acceptable for listings and/or differences.

A Code Review meeting can often be completed in a one-hour session, although sometimes, more complicated reviews do take longer. The code reviewers generally ask questions, suggest or request changes or additional tests, and remind the developer of overlooked issues, elements, or interactions.

Often, a Code Review results in additional work that needs to be done by the developer prior to check-in. This might include additional error-detection code, new namelist control variables, additional comments, or other code changes or improvements. If the changes are extensive, the developer is expected to re-test, then schedule a follow-up session to review the new changes and test results with the reviewers.

These review sessions are intended to educate pop2 users, result in better code, and reduce errors. They are conducted in an informal, collegial manner, and although discussions are often spirited, professional conduct is the norm.

At the end of a successful Core Review cycle, the OMWG Co-chairs -- with input from the OMWG members -- determine if the code can be checked into the pop2 repository trunk.

Activation of New Code

The OMWG Co-chairs determine if new code on the pop2 trunk will be activated "out of the box." This determination typically is made with input from the OMWG, so a developer may be requested to present their results at an OMWG meeting prior to a decision.

It is possible that new code will be approved for the trunk, but with the code deactivated for the default, out-of-the-box configuration. This allows the developer to continue developments, testing, or even production runs while the option is under consideration.

Trunk Check-in and Documentation

Following the successful completion of the Code Review, the code will be checked onto the trunk of the pop2 repository in a timely manner by the pop2 gatekeeper and documented on the CESM pop2 documentation web page. The local OMWG Co-chair will prioritize the check-in by the repository gatekeeper. Typically, once all code and documentation are available, check-in will occur within days of approval for trunk check-in. During periods of intense scientific developments, such as the finalizing of the scientific code to be used in integrations for the IPCC Assessment Report, science modifications may take priority over software engineering mods.

Tags are documented in the $SVN/pop2/ChangeLog file, which is provided by the developer, following the existing template.

Input Datasets

If the new developments require new pop2 input datasets, these datasets must follow the inputdata filenaming conventions. All new pop2 input datasets must be fully documented, following the guidelines in the finenaming document.