Skip to content

DevelopmentGuidelines

Jump to bottom
Ned Haughton edited this page Apr 28, 2016 · 12 revisions

Guidelines for the use and development of CABLE

Released with CABLE v2.0: October 2012 Updated: 27 Nov 2012

This document outlines the procedures involved in the development of the Community Atmosphere Biosphere Land Exchange (CABLE) model. It describes: the role and responsibilities of CABLE users, developers and the CABLE committee; the expected scientific and technical standards of proposed changes to CABLE; and how to submit a proposal for the formal adoption of changes to the CABLE code. Any questions about these procedures should be directed to the CABLE coordinator ( [email protected] ).

This document should be read alongside other CABLE documentation available at https://trac.nci.org.au/trac/cable/wiki/CableDocuments , including:

  • The [CableUserGuide CABLE user guide], that describes how to download, compile and execute the CABLE code. This includes descriptions of initialisation, parameter selection and other model control procedures.
  • Technical description documents that outline the derivation and implementation of equations describing the physical processes that CABLE represents
  • Guidelines for the use and development of CABLE (this page) describes how CABLE is being managed
  • [CableCodingConvention Coding standards] – a description of the standards that CABLE code should aim to adhere to
  • [CableBenchmarking Basic benchmarking results from CABLE-2.0]

CABLE users

CABLE users are users who do not intend to submit any modifications to CABLE. In being given access to utilise CABLE for scientific research, they are expected to:

CABLE developers

CABLE developers are any users who intend to modify some aspect of CABLE’s functioning and are interested in seeing their modification adopted by the broader CABLE community. The requirements of CABLE users (see above) will apply also to developers. Additionally, in being given access to develop CABLE, they are also expected to:

  • Utilise the CABLE Subversion repository (https://trac.nci.org.au/svn/cable/) as part of their development environment. Each developer would usually establish their own (or multiple) repository branches and develop CABLE code within that branch. Detailed information describing the repository is available in the CABLE users guide. Developers should not copy code from another developer’s personal branch without that person’s permission, nor check code into another developer’s personal branch.
  • When sharing CABLE code, only do so through the CABLE repository. Code should not be passed directly between developers via other methods (email, USB drive etc), as tracking different versions in this manner becomes very difficult.
  • Share repository development branches with other developers with whom they are working. Groups formed in this way would need to establish their own protocols for committing changes to a shared branch.
  • In the first instance all developments to the source code should be made switchable. Thereby with the switch turned off, the model should reproduce exactly the same results as the base revision. This is a pre-requisite of any development being pushed to the trunk. This is discussed further [BasicTrunkTestIntro here]. In time, these switches may be removed.
  • Only anticipate updates to the repository trunk after the submission and testing procedure in Section 4 is complete, coding standards have been met and the update has been approved by the CABLE code committee. Code submissions for committee consideration should be made through the ticketing system (see Sec 4).
  • Participate in the CABLE trac (https://trac.nci.org.au/trac/cable/) ticketing system to log the progress of CABLE developments. For example noted bugs, bug fixes, intended development and suggested development should be ticketed. This will provide a documented, readily searchable and linked, common history that is available to all CABLE users.

The role and responsibilities of the CABLE committee

The CABLE Committee is a small group of researchers, originally selected by CSIRO from various institutions, who have an interest in, or have had significant involvement with, the development of CABLE and are charged with effectively managing CABLE on behalf of the CABLE research community. Their work is facilitated by the CABLE technical support group and is led by the CABLE coordinator (currently Rachel Law, CSIRO). The CABLE committee are expected to:

  • Maintain a record of who is working on different areas of the CABLE code, aid communication between parties interested in similar types of research and work to ensure complementarity in the various directions of CABLE development. This task will be facilitated by the participation of developers in the CABLE trac ticketing system.
  • Devise and review documentation and benchmarking tests for any proposed changes to the CABLE repository trunk and initiate extra tests when required.
  • Identify potential conflicts (either structural or scientific) in multiple CABLE development proposals.
  • Request / perform coupled (atmosphere-ocean) model tests of proposed changes if required.
  • Approve changes to CABLE trunk
  • Periodically tag repository trunk versions to be released as official updates of CABLE, at the same time updating CABLE libraries for different coupled models, and mirror these releases on the CABLE Sharepoint site.
  • Recognise and document successful developments/approved changes, possibly through a CABLE annual report.

Submitting improvements to CABLE

Types of development/code changes

Different types of changes may require different levels of testing and performance before being added to the CABLE trunk. These include:

  1. Code clean up – no change in functionality
  2. Bug fixes
  3. Changes to driving, coupling or input/output code
  4. Changes to surface datasets (e.g. veg/soil type maps, initial carbon store values, spatially distributed vegetation height, etc)
  5. Changes to algorithms in current modules
  6. Modules that provide alternatives to current code
  7. Modules that model new processes

Documentation of developments

Where applicable, together with any changes submitted for CABLE integration, developers must submit:

  • Enough within-code commenting for others to follow the logic of the code, what processes are represented and any relevant scientific references
  • A short comment within the ‘history’ section of the code header to note significant changes/additions and their author and date.
  • Technical documentation – mathematical description of treatment of processes and description of implementation of these within the CABLE code. Where substantial new processes are implemented, it may be appropriate to document these in a form suitable for submission to Geophysical Model Development.
  • Results from the complete set of benchmarking tests (see below).
  • Clearly written documentation of any implications for the way CABLE is executed (i.e. user guide changes).

Once this documentation in a trac ticket (e.g. information should be noted is completed, all https://trac.nci.org.au/trac/cable/ticket/5 ). This may be a new ticket, or preferably an update to a pre- existing ticket which already documents the code development that has been undertaken. The ticket should include the following information:

  • Who contributed to the code development, and their institution (for IP/licence requirements)
  • The branch location of the code changes, and the svn revision number(s).
  • A statement that CABLE coding standards have been adhered to
  • The purpose of the code development and the resulting model behaviour
  • Benchmarking results should be described briefly
  • Any appropriate technical documentation, user guide modifications or more detailed benchmarking results should be attached.

When the ticket has been submitted, please notify [email protected] with a request that the cable committee consider the code submission.

Benchmarking tests

Defining a comprehensive and useful set of benchmarking tests is a research task. Here we identify the types of benchmarking tests that will be required for any CABLE modification to be considered for repository trunk integration. More precise benchmarking lists will be developed over time, and the CABLE committee will always welcome suggestions for new benchmarking tests. Developers will need to undertake most benchmarks themselves but the CABLE committee will be responsible for ensuring that there are standardised tools or jobs scripts available for those benchmarks. What constitutes a ‘pass’ in any benchmark may depend on what the changes to CABLE involve. For example, obvious bug fixes might degrade model performance but should still be included. Optional schemes may be included with less rigorous testing unless they become the default option in a tagged release of CABLE.

#!html
<table class="listing">
    <thead>
    <tr>
        <th></th>
        <th>Simulation </th>
        <th>Metrics</th>
    </tr>
    </thead>
    <tbody>
    <tr class="odd">
        <td>1</td>
        <td>Single sites (multiple locations across biomes) using PALS </td>
        <td>Fluxes <br /> Energy conservation </td>
    </tr>
    <tr class="even">
        <td>2</td>
        <td>Global offline using GSWP2 or similar using PALS </td>
        <td>Albedo, LE, GPP … LAI if interactive, runoff (Dai et al.) 10 largest catchments? </td>
    </tr>
    <tr class="odd">
        <td>3</td>
        <td> MIP style ACCESS run (with or without CASA-CNP) </td>
        <td> Energy balance, water balance, surface temperature, precipitation, run-off, atmospheric CO2 (seasonal cycle)</td>
    </tr>
    <tr class="even">
        <td>4</td>
        <td> Fully coupled ACCESS runs (may not be required in all cases) </td>
        <td> As AMIP, also global salinity, global ocean temperature etc.</td>
    </tr>
    </tbody>
</table>

[CableBenchmarking Here] we outline some specific examples of bench marking applied to CABLE.

Clone this wiki locally