Submitting updates for inclusion in GEOS-Chem

From Geos-chem
Jump to: navigation, search

Overview

The GEOS-Chem Steering Committee (GCSC) encourages updates to the GEOS-Chem model. Updates to the GEOS-Chem model benefit both the developer and the entire GEOS-Chem community. The developer benefits through coauthorship and citations. Priority development needs are identified at GEOS-Chem users' meetings with updates between meetings based on GCSC input through working groups.

When should you submit updates to the GEOS-Chem code? Bug fixes should be submitted as soon as possible and be given high priority. Code related to model developments should be submitted when it is mature (i.e. a paper has been submitted). Your working group chair can offer guidance on the timing of submitting code to the GCST.

The practical aspects of submitting updates to the GEOS-Chem Support Team are outlined below.

Guidelines

  1. Contact your Working Group leaders to request that your changes be included in the standard code. The GEOS-Chem Steering Committee will meet every three months and set the GEOS-Chem model development priorities (i.e. decide on the order in which updates will be added to GEOS-Chem).
  2. Create or log into your GitHub account.
  3. Fork the GEOS-Chem repositories. Navigate to each appropriate GEOS-Chem repository on GitHub and click Fork in the top-right corner of the page.
  4. Clone your forks of the GEOS-Chem repositories to your system (e.g. git clone https://github.com/YOUR-USERNAME/geos-chem Code.12.0.0; git clone https://github.com/YOUR-USERNAME/geos-chem-unittest UT.12.0.0).
  5. Add your modifications into a new branch off of the master branch.
  6. Test your update thoroughly and make sure that it works.
  7. Review the code update checklist and data checklist below.
  8. Create a pull request in GitHub (recommended) or a Git patch file.
  9. The GEOS-Chem Support Team will add your changes to the standard code. Your update may be bundled with other code updates and the GEOS-Chem version number (X.Y.Z) will be changed. The update will be validated following the GEOS-Chem benchmarking procedure.

Checklist for code update submissions

  • Use F90 free format whenever possible
  • Include thorough comments throughout code updates
  • Remove extraneous code updates (e.g. testing options, other science)
  • Include full citations at the top of relevant source code modules
  • Complete GCHP updates required with GEOS-Chem Classic updates

Checklist for data submissions

  • Make sure netCDF data files are COARDS-compliant.
  • Concatenate netCDF files together whenever possible.
    • e.g. Create one file per time period instead of one file per species per time period.
    • Reducing the number of files that have to be opened results in more efficient GEOS-Chem simulations.
  • Make sure files have been chunked and deflated.
    • Deflation level 1 is usually sufficient for most files.
    • e.g. ./nc_chunk.pl myfile.nc 1
  • Include updated HEMCO Configuration file (if the data will be read via HEMCO).
  • Include README file detailing data source, contents, etc.
  • Include script(s) used to process original data
  • Include a summary or description of the expected results (e.g. emission totals for each species)

Further reading