SDWG Developer's Guidelines
The SDWG enhances CESM and its application to improve understanding of the interactions between human and earth systems. Toward that end, one of its functions is to review and approve “new CESM code that provides linkages to human system models,” in particular impact and integrated assessment models. The working group recently updated its code development policy information to expand that function to include a wider variety of CESM code, software tools and models that can facilitate the application of CESM to research questions relevant to the SDWG. Download the SDWG code policy document or see the sections below. Note that because scientific work linking human and earth systems is developing, this code policy should be considered open to modification by the working group over time to match evolving circumstances.
Software Tools Overview
Software tools for enhancing the application of CESM include tools for linking (in either direction) CESM or one of its components to human system models (especially impact and integrated assessment models). These tools can be code that provides the infrastructure for carrying out the mechanics of model linkage, but also can include scientific models that perform a function important to linkage (for example, models that downscale aggregate emissions or land use to the grid cell level for input to CESM). They can also include tools for providing CESM diagnostics. They do not include tools primarily designed for climate downscaling or bias correction, two topics that are currently outside the scope of the SDWG.
Approval of Software Tools
There are two types of “approval” the SDWG can give to software tools for enhancing CESM application:
- Endorsement of tools external to CESM. This code is to be hosted and maintained separately from the CESM code repository. Endorsement implies that the SDWG has evaluated the tools according to the criteria and procedure below and found them to be of sufficient interest to the SDWG community. Links to these endorsed tools will be available from the SDWG web page.
- Recommendation that code be adopted as part of the CESM publicly released versions. This recommendation involves multiple steps (see below), including testing and approval by the Software Engineering Working Group. Note that, in the case of major changes to CESM structure or capability, the inclusion of such code might require approval by other working groups and/or the CESM SSEC.
Criteria for Software Tools
Decisions on endorsing or recommending software tools would be made based on a number of criteria:
- They should be consistent with the SDWG’s goal of enhancing CESM and its application to improve understanding of the interactions between human and earth systems;
- They should be anticipated to be of benefit to a wide research community;
- Source code should be openly available to the research community to apply and further develop, consistent with the community model philosophy of CESM;
- Documentation should be sufficient to support use by the research community.
The first criterion above implies that tools should be designed to work well with CESM specifically, and that they should be of sufficient quality that their use can help improve scientific understanding of research questions to which they are applied. Quality of tools can best be demonstrated through published applications, and the SDWG can contribute to further evaluation of tools through shared discussion of user experience, as facilitated by the SDWG email list and the CESM online discussion forum.
The procedure for arriving at a decision of endorsement or recommendation is (not necessarily in this order):
- Researchers develop software tools and use them in a peer-reviewed publication(s).
- Researchers present tools and their applications at an SDWG meeting.
- For CESM code recommendation decisions, researchers develop a plan for the testing and maintenance of tools as part of CESM releases that is agreed to by the CESM Software Engineering Group. (This step to be refined with further input from SEWG/CSEG.) For CESM code endorsement decisions, researchers develop a plan for the maintenance and hosting of tools.
- Researchers announce the availability of the tools on the SDWG email list and other appropriate channels in order to reach the relevant communities, and allow for feedback during a review period of at least 3 months. Availability includes the source code (for “friendly review”), documentation and plans for testing, maintenance and/or hosting.
- Co-chairs decide on endorsement or recommendation based on the SDWG view as expressed at a WG meeting or through the SDWG email list. The decision should be informed by feedback from the target research or application communities and the judgment of the working group on whether the tools meet the criteria above. A vote of the working group could be held if the view of the working group as a whole is unclear.