Submitting updates for inclusion in GEOS-Chem
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.
- Create or log into your GitHub account.
- 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.
- 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.).
- Add your modifications into a new branch off of the master branch.
- Test your update thoroughly and make sure that it works.
- You can use the GEOS-Chem Unit Tester to make sure your code updates work for a given combination of met fields, resolutions, and simulation types. A unit test looks for parallelization errors, floating point math issues, array-out-of-bounds errors, and creation of array temporaries.
- For structural updates, we recommend running difference tests often to ensure your updates don't impact model output.
- Review the code update checklist and data checklist below.
- Contact your Working Group leaders to request that your changes be included in the standard code.
- Create a pull request in GitHub (recommended) or a Git patch file.
- Fill out and submit the GEOS-Chem Update Submission Form.
- 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).
- 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.
- Use isCoards script and include output in submission.
- 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).
- Submit this as a pull request in the geos-chem-unittest repository on GitHub.
- 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)