Atmospheric Modeling and Analysis Research
CMAQ Model Developer's Guidance
Procedures for submitting CMAQ model and system code external contributions for inclusion in public model releases:
- CMAQ model code will be frozen as beta version six months in advance of intended new release date, and made available from EPA. Contact Jon Pleim of EPA if you intend to make a contribution to the upcoming model release; you will be provided access to the beta code.
- Use consistency in coding practices, including naming conventions, inline documentation, and specification of compile-time vs. run-time parameters.
- Prior to submission of code to EPA, check that the code is consistent with the beta model version from which it was built, especially in the use of “include” files and run-time parameter settings. Mixing code from different versions of the modeling systems leads to problems in using the generalized master scripts that are provided to configure, compile, and run the model code.
- Document the computational performance used for the testing; include type and speed of the processor(s), the compiler brand and version, and CPU usage. Any documentation on potential differences in model outputs between different computing platforms would be useful for end-users who may not be able to duplicate the platform on which the model was initially developed and tested. To this end, code testing and documentation of test results by developers, using more than one platform-compiler combination, if available, are desirable.
- Provide a benchmark case for the revised CMAQ code so that users may attempt to run the code and reproduce the test case results. The test case should include input data, output reference data, run scripts, and any special instructions for compiling and running the code.
- Work with EPA technical staff for integration of beta codes into the final CMAQ public release. Any changes in the base beta CMAQ code made between the initial model freeze and the model release will be communicated to the code contributor, and issues arising from those changes will be worked on by the code contributor and EPA staff. All contributed code should be in the form of subroutines or modules that can be turned on/off (modular) within CMAQ, depending upon the options invoked to run the model. Frequent discussions are encouraged between the code contributor and EPA staff during the integration period.
- Adequately document or otherwise provide references to peer-reviewed literature supporting new science algorithms. Include CMAQ model evaluation results for new science algorithms, documenting improved model performance using appropriate observational databases and the EPA model evaluation framework. Length of simulations used for model evaluations should be sufficient to demonstrate the impacts of the model changes.
- Contributors of model source code to EPA will be asked to provide continued support for technical guidance on the use of their code, which may include supporting the implementation, interpretation, and user-support/troubleshooting of model applications. Contributors will also be expected to maintain their codes at the current state-of-science and consistent with the CMAQ code structure for incorporation into future CMAQ releases. In the absence of these steps by code contributors, the contributed codes may be removed by EPA from subsequent CMAQ releases.
- Depending upon the resources available, EPA will make every effort to work with the code contributor to include the contribution in the scheduled CMAQ model release. In the event that the above steps cannot be achieved by the model release deadline, EPA will continue working with the contributor to satisfy all requirements, and consider including the contributed code in a subsequent interim model release.