1. HOME
2. R AND D
3. DOCS
4. DEVELOPMENT GUIDANCE

CMAS Software Development Guidance

CMAS recommends the following steps as the minimum level of coding and testing practices to be adopted by software developers wishing to contribute code for release to the community.

• To make the best use of the CMAQ system features in developing new code, review the coding conventions that are provided in Chapter 18 of the EPA publication EPA/600/R-99/030, March 1999, "Science Algorithms of the EPA Models-3 Community Modeling and Analysis System".
• Build new code using an operational version of the model as template whenever possible. This will facilitate consistency in coding practices, including naming conventions, inline documentation, and specification of compile-time vs. run-time parameters.
• Prior to submission of code to the CMAS Center, check that the code is consistent with the operational model version from which it was built, especially in the use of common include files and run-time parameter settings. Mixing code from different operational versions of the modeling systems leads to problems in using the generalized master scripts that are provided to configure and compile the model code.
• Adequately document or otherwise provide references to peer-reviewed literature for any new science algorithms.
• 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 development code so that interested users may attempt to run the code and produce 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.
• Provide stress test results from at least a 5-day simulation that demonstrate how the code updates impact the model results. Shorter simulations than this do not provide adequate results from which to discern trends in the model results beyond the initialization period.
• When making incremental changes to the model science, provide documentation of the results including: (a) the results for all variables that show a deviation of greater than 1.0E-6 ppmV for the gas-phase species or 1.0E-4 ug/m^3 for the particulate species from the base model results for the same case, (b) an analysis of what was done to understand these differences, and (c) conclusions of the analysis.
• Note that more than one simulation may be necessary to adequately demonstrate seasonal or regional biases, if any, in the results. It is also understood that with models that are still under development, the analysis may not resolve all differences from the operational model results. It is recommended that these unresolved issues also be documented.
• Contributors of model source code to the CMAS Center will be asked to provided technical guidance on the use of their code, which may include supporting the implementation, interpretation, and troubleshooting of applications where the code was used.

Email the CMAS Software Development Coordinator if you have code to contribute to the CMAS Center or if you have software development questions.