2022/4/8: Original
2022/6/17: Revised to stress importance of not bundling features in a single PR
2022/8/31: Revised to remove duplicate terminology section
This document describes the policy for bringing in new features and changing existing code in the E3SM model. This new policy requires a significant amount of work improving the E3SM diagnostics, CIME test suites and developing documentation, collected /wiki/spaces/CNCL/pages/3315138566
...
BFB (bit-for-bit)
New code produces results which are bit-for-bit identical with old code
Does not contain stealth features
Roundoff
New code would match old code in exact arithmetic, but will diverge exponentially fast when using finite precision
Climate of new and old code will converge as the averaging time goes to infinity
Climate changing
New feature is brought into the model turned on
Other model configuration change (parameters, resolution, forcing data)
Stealth Feature
BFB code change that includes a new feature, turned off by default
...
Coupled model: B-case runs (~100 years) for WC, cryosphere and BGC configurations
Component models: F, I and G cases, typically much shorter (e.g. 5 year F case with cyclic year 2010 forcing)
Updated periodically when climate changes are integrated, or monthly ( to check for unintended changes)
New features will be evaluated with respect to these reference solutions, with documentation on the import metrics
Note: E3SM Reference solutions and related documentation not yet ready!
Section 1: New Feature Request Process and Documentation Requirements
...
Section 2: Collect documentation and simulation results needed for the Pull Request (PR)
...
Each of the four PR categories defined above require different levels of documentation and simulation results before a PR can be submitted
...
BFB (bit-for-bit): BFB changes which do not include stealth features.
...
Roundoff: These are usually infrastructure and code cleanup changes, compiler changes and system updates which introduce changes for which strong evidence can be provided that the changes do not effect the simulated climate.
...
Stealth Features: These are new features that are turned off by default and BFB with the previous code when turned off.
Stealth features that are not BFB when turned off should be split into two PRs.
...
.
BFB: no additional documentation is needed.
...