AMWG Developer's Guidelines

Getting a contribution into CAM

This section defines the process that must be followed for a contribution to be considered for the next generation of CAM. These guidelines comprise a "living document" subject to occasional revisions and updates as procedures evolve or requirements change.

General Recommendations (Suggested best practices)

As early as possible notify an AMWG co-chair of development plans so that these may be posted on the CAM Development webpage. Additionally, discuss software infrastructure needs with an internal (NCAR) member of the AMWG in order to avoid/minimize conflicts between this contribution and existing or concurrent model development by other contributors.

Code Base

The contribution must be compatible with recent versions of CAM in the development stream. This is required because of a lack of (NCAR) resources for porting codes.

• It implies that the contributor starts his/her work with the head of the trunk (or a version very close to the head) and during the development process, the contributor's code is updated to the head of the trunk on a regular basisunder guidance from the Software Engineering Working Group (SEWG) so as to not diverge significantly from it. The contributor’s codeneedstobe checked inasa branch on the SVN repository (request access). The branch is maintained by the contributor.

Code and software engineering requirement

The contribution should satisfy CESM coding guidelines and software engineering requirements

Testing requirement

Contributors are responsible for testing their code.

Pre-validation:

• The contributor should perform multiple CAM stand-alone (F case) simulations, at least 5 years in length,  to insure that the global radiative heat balance is within 1-2 W/m²  and the model produces a reasonable climate.

Scientific validation:

• The contributor should perform a 25-year coupled (1850 control). This simulation should be reasonably balanced with the global top-of-model radiative imbalance less than 0.5 W/m2. The contributor should produce diagnostics plots with the AMWG diagnostics package and generate a series of performance metrics to review. The diagnostics should be posted for the AMWG scientists to view.  
  
  
• If the contribution just adds functionality without changing the simulation (e.g. adding the COSP simulator) , the contributor might skip this step but should demonstrate that simulation is not affected by including the feature.
  
  
• Note that most changes will require further types of simulations (indirect effect, climate sensitivity) that will be coordinated later on (see: code and results review) with the AMWG co-chairs and liaison.

Software engineering validation

• CAM supports automated testing scripts. The contribution should satisfy this extensive suite of regression tests.  

Code and results review

• The contributor should present results to the AMWG or some subcommittee of the AMWG. The presentation should include a summary of the contribution, the tests performed, and scientific results and justification. At this stage, the AWMG will decide which further simulations are needed. 
  
  
• The code will be reviewed by the CAM gatekeeper to ensure that it satisfies the CAM coding guidelines.

Decision process

• The contributor will present results at an AMWG meeting to make the case for improvement or modification. Based on the review and the input of the AMWG, the AMWG co-chairs, with consultation to the SSC, will decide if the contribution can be included on the CAM trunk.
  
  
• If the contribution is approved for the trunk, it will be activated either as the default option (out-of-the-box configuration) or as an option. The decision to make the contribution the default or an option will be made by the AMWG co-chairs based on compatibility with other components, AWMG input and consultation with the SSC. If the decision is to just make the contribution an option a written response describing the reason will be provided to the contributor.