Developer Corner

Guidelines

Criterion for Recommending Adding New Modules to the CESM Trunk.

Spring 2013

Addition of new code or chemical mechanism to the trunk will be considered if this addition fits within one or more of the following categories:

  1. Reduces known biases relevant to a CESM science question
  2. Provides a benchmark representation of a process
  3. Adds new feedbacks that have been demonstrated to be important for a CESM science question
  4. Provides a new approach to science questions of interest to the CESM enterprise
  5. Provides diagnostics needed to constrain simulations
  6. Significantly reduces the cost of simulations

The addition is subject to the following requirements:

  1. It does not significantly degrade the overall simulated climate or atmospheric composition.  This will be documented through the use of existing and upcoming diagnostics and specific requested simulations (e.g., present-day and pre-industrial for indirect effect estimates, if applicable).
  2. It does not increase cost substantially unless it provides a benchmark

Protocol for inclusion in CESM trunk

The present document identifies rules to be followed by CAM-chem developers in order for additional/modified code to be considered for inclusion in the CESM trunk.  Its purpose is to describe necessary steps to be taken with the help of the Chemistry-Climate Working Group (ChemClimWG) software liaison to facilitate integration of new or updated features.

  1. A branch is created for the work (usually by the ChemClimWG software liaison). We highly recommend that during the development process, the developer's branch should be updated to the trunk or main development branch on a regular basis.
  2. Changes are made to the branch version of the code by the developer. They are then checked in, using svn, by the developer. We recommend that the developer reviews and follows (where possible) the code guidelines outlined below prior to undertaking their model development.
  3. The added code is demonstrated to significantly improve process representation and/or reduce model biases against observations and other diagnostics. Decision on moving forward with the process of integration is made by the ChemClimWG co-chairs in consultation with the ChemClimWG members.
  4. Code is reviewed by the ChemClimWG software liaison. As a result of the code review, improvements to the code may be required, which once completed should be checked into the branch by the developer. Note that the more discussion and collaboration that takes place earlier in the process, the more likely the changes can be quickly approved.
  5. Any CAM-Chem tools that need to be modified to create new datasets will need to be updated as well.  Similarly, tests for the new features might need to be added to the standard CAM-Chem testing (in general this is done by the ChemClimWG software liaison in close collaboration with the developer)
  6. At this stage, the developer, with the help of the ChemClimWG software liaison,  should run the CESM test suites. If possible, the test suites should be run on more than one machine (three machines and/or compilers is our current target).
  7. Once the testing is complete and results are satisfactory, the code is ready to be brought onto the trunk or main development branch by the ChemClimWG software liaison. Note that especially for large code changes, we recommend that testing is done frequently throughout the code development process.
  8. Depending on additional factors such as timing of tags, other development activities, resources, etc, additional updates to the trunk or main development branch will be conducted by either the ChemClimWG software liaison software liaison or the developer until the developer's branch can be moved to the trunk or main development branch.
  9. The developer's branch is moved to the trunk or the main development branch by the ChemClimWG software liaison. This code becomes available to the wider community through CESM release.