wiki:CiceCodeModifications

CICE Code Modifications

The CICE user community embodies a broad range of collaborative effort. Many users are happy with the code as-is, altering only those aspects necessary to configure it for their own computer systems and scientific studies. Some users report back with bugs or suggestions for improving less user-friendly options, while others contribute entire parameterizations or infrastructure improvements. The level of collaboration you wish to engage in will determine the level of your interaction with LANL CICE developers and the CICE repository. This interaction can be divided into two general types: small modifications to formally released versions of the code, and larger scale developments requiring frequent communication with the code repository, often on a dedicated branch.

To date, CICE releases have appeared when either enough bugs accumulated that we felt a new release was necessary, or when a big new feature was added to the code (such as overhauling the infrastructure or adding an ice thickness distribution). The released code thus is stable for long periods of time, and users have a good reason to upgrade when the time comes. These users, including those who return small CICE modifications to LANL, make up the “ciceusers” mailing list.

The second interaction type is most useful when new development takes place over a longer period in which many other changes are made simultaneously in the LANL-based code, that must be incorporated into a local working code in order to keep the different versions from diverging too much. Many small releases can be easier to keep up with in small steps. This option is available to users (“cicedev”) who have access to the development branches of the repository, but it comes with increased risk of bugs or other unexpected “features” as other changes are made to the trunk. We value those users for helping to exercise the code before it is released to the rest of the user community.

This “hybrid” release approach, with frequent updates to a set of close collaborators/users interspersed with less frequent general releases, has worked very well for our CICE model development efforts and for the general user community. A list of ongoing collaborative development efforts is available (and can be edited by cicedev collaborators): CiceDev

Standard Procedures for Code Development Collaborations

For small code alterations that affect only a few lines (ten, not 100), or that are compact and relatively noninvasive to other parts of the code, the most efficient approach is to send Elizabeth eclare@… the modified code along with a description of what it does. It should already be well tested. Elizabeth will decide whether the change is warranted and test it further before checking it into the CICE repository trunk.

For larger code development projects, first open a discussion with Elizabeth about what your project aims to do. She will decide whether to provide a repository branch for your use. Branches require extra work for her to maintain, and such projects are necessarily collaborations with LANL code developers; therefore Elizabeth will be selective in allowing outside developers to have their own repository branches. Once a branch is created, the following procedures should be followed. These procedures can be flexible, depending on the intensity of LANL’s participation in the collaboration.

  1. Check out the code into your working directory and modify it. Test the changes thoroughly.
  2. When changes are made to the trunk, merge them into your working directory. Test the changes thoroughly.
  3. You may commit changes from your working directory to your branch regularly, but we recommend that you commit only working code.
  4. When you are ready for your changes to be merged into the CICE trunk for others to test and use:
    1. Ensure the branch and your working directory are at the latest trunk revision
    2. Complete the series of required tests in your working directory (see below)
    3. Compile the test results and written documentation of the new code’s purpose, operation and limitations
    4. Commit your changes to your branch
    5. Inform Elizabeth that the code is ready for review, providing the test results and documentation (these can be checked into your branch)
    6. Repeat steps (a)-(e) as necessary until you and Elizabeth are both satisfied. Elizabeth will merge the branch into the trunk.

Tip: Notify Elizabeth of your plan to commit a version for review well beforehand, in order to agree on a target date that best fits everyone’s schedules. This helps to reduce the amount of time and trunk changes that pass between the branch code commit and its review.

A minimum list of tests that modifications must pass before release

Programming basics:

  1. check for divide-by-zero and other over-/underflows (set flags in bld/Macros)
  2. check for arrays out of bounds (set flags in bld/Macros)
  3. check that restarts are bit-for-bit exact
    1. run from time t0 to t2, writing restart files at times t1, t2
    2. rename the t2 restart file or copy it to another directory
    3. restart from time t1, writing a new restart file at time t2
    4. if the restart format is binary, use the unix command ‘cmp’ to compare the two t2 restart files; if they are exactly the same, there will be no output from the command
    5. if the restart format is netcdf, use the unix command ‘ncdump’ to write each of the two t2 restart files to ascii output; then use ‘diff’ to compare them
  4. check that timings are not degraded (or if so, understand why and document how much)

Parallelization: test that the code produces correct results and scales as expected

  1. 1 processor, 1 block
  2. 1 processor, > 1 block
  3. multiprocessors, 1 block per proc
  4. multiprocessors, > 1 block per proc
  5. padding (blocks don't fit evenly into processors), 1 proc and more
  6. test on various grids (dipole, tripole, column, etc)

General tests, as applicable:

  1. check that the new changes do not alter the default configuration
  2. test all parameter options, including those external to the new code that may be impacted by it (look at output to see if it is sensible)
  3. check diagnostics, especially global conservation (print_global)
  4. check history output fields
  5. turn on hardwired conservation and monotonicity tests (for changes to those modules)
  6. set kdyn=0 and confirm no motion (for changes to dynamics)

Notes:

  • hardwired parameters should be listed explicitly in the declarations, not buried
  • provide documentation as comments in code and as additions/changes to cicedoc