Submitting GEOS-Chem support requests

From Geos-chem
Revision as of 15:06, 8 October 2019 by Bmy (Talk | contribs) (Should I first try to solve my issue by myself?)

Jump to: navigation, search

On this page we provide information about how to report any GEOS-Chem issues that you may encounter.


Should I first try to solve my issue by myself?

We have been migrating bug reports to our GEOS-Chem issue tracker, which is located on our Github repository: We recommend that you also look through both the open and closed issues on this page, as your issue might be listed there.

The GCST encourages all GEOS-Chem users to try to debug issues to the greatest extent possible. Please see our our Debugging GEOS-Chem wiki page for a list of useful tips that you can use to help identify the source of your bug or technical issue. Also see our Guide to GEOS-Chem error messages for a list of several commonly-encountered issues and fixes.

You can also check if your issue was resolved in a later GEOS-Chem version by consulting the our Bugs and fixes wiki page, as well as our GEOS-Chem issue tracker on Github.

If you still cannot resolve your issue on your own, then please do not hesitate to submit a GEOS-Chem support request. More information about what to include in your support request is provided in the following sections.

What type of support can I expect?

The GCST will be happy to assist you in resolving bugs and technical issues that may arise when compiling or running GEOS-Chem. User support and outreach is an important part of the GCST's mission to support the International GEOS-Chem User Community.

Even though the GCST can assist in many different ways, it cannot possibly do everything. GEOS-Chem users are expected to take on certain responsibilities. For example, the GCST relies on users to make sure that their computer system has all of the software libraries needed to run GEOS-Chem.

Also keep in mind that the GCST focuses primarily on software development and user support rather than on scientific research. If your question is more scientific in nature (e.g. "What happens if I change this reaction rate from X to Y?", or "Is emissions inventory A better than inventory B?", etc.), then we recommend that you contact the relevant GEOS-Chem Working Group(s) for assistance. If you are not sure of whom to contact, then send your question to the GCST, who will be happy to forward it to the appropriate person(s).

Contacting the GEOS-Chem Support Team for assistance

Please send all GEOS-Chem support requests to the GEOS-Chem Support Team (aka GCST), as described below.

How can I make a support request?

The table below describes how you can make a GEOS-Chem support request. For bugs or technical issues, we recommend opening an issue on the relevant Github repository page (see links below).

Open a support request for: Instructions

(1) Open this link (in a new browser tab):

(2) You will then see this screen: Gc issues.png

(3) Click on the "Get Started" button next to the type of issue that you would like to open. You can ask a question, request a feature, or report a bug or technical issue.

(4) Follow the directions in the issue template. Please be sure to include all relevant documentation.

  1. Open a new issue on the GCHP Github repository:
  2. Type a description of the issue
  3. Include all relevant documentation

(1) Open this link (in a new browser tab):

(2) You will then see this screen: Gcpy issue.png

(3) Click on the "Get Started" button next to the type of issue that you would like to open. You can ask a question, request a feature, or report a bug or technical issue.

(4) Follow the directions in the issue template. Please be sure to include all relevant documentation.

Other topics Email your question to the GEOS-Chem Support Team.

Use this email address: geos-chem-suppport [at]

--Bob Yantosca (talk) 18:53, 25 July 2019 (UTC)

What do I need to include in my support request?

Here is a quick list of information that you should include in your support request. If you are using the Github issue tracker, then you will see a list of requested information in the issue template.

# Item Filename(s) Description / Notes
0 Version of GEOS-Chem you are using You can find out what version you are using typing git log at the command prompt. The first entry will show you the last git commit for the version you are using. Please send this to the GCST with your help request. If you created a run directory for GEOS-Chem Classic, please also do this for the repository geos-chem-unittest that you created the run directory from.
1 A description of the issue Please include a brief description of the issue and any error messages that you encountered. Also include the steps (e.g. compile and run commands) that you used.

Of particular importance: The GCST needs to know if you are using an unmodified (aka "out-of-the-box") version of GEOS-Chem, or if you have made any modifications to the code or input data. If you have modified GEOS-Chem, then please take a moment to doublecheck your modified code or data to make sure that it is not the source of the error.

2 input.geos file input.geos File containing the various input options for your simulation.
3 HEMCO configuration file HEMCO_Config.rc File containing input information for the HEMCO emissions component.
4 Lastbuild file lastbuild or or
File containing a summary of all of the options that were used to build the GEOS-Chem executable

NOTE: For GCHP simulations, this file is just named lastbuild, without any suffixes.

5 GEOS-Chem "Classic" log file GC_*.log or
GC_* or
Contains an "echo-back" of all input options that were specified in input.geos, the list of diagnostic quantities that are being archived, the list of files that are being read, and information about the operations that are being done at each GEOS-Chem timestep. If you run dies with an error, a detailed error message should be printed here.
6 HEMCO log file HEMCO.log or or
Contains information about how emissions, met fields, and other relevant data are read from disk and processed by HEMCO for input into GEOS-Chem.
7 Output file from your job scheduler
  • Only if you ran GEOS-Chem with a batch scheduler (e.g. SLURM, PBS, LSF, etc.)
slurm-JOBID.out Contains stdout and/or stderr output from the your job scheduler. May contain important error messages.
8 Amazon Machine Image (AMI) ID
  • Only if you ran GEOS-Chem on the Amazon Web Services (AWS) cloud.
The AMI ID string that was used to initialize your AWS cloud instance. This will allow us to login to the AWS cloud with the same environment that your run used.
List of additional information to include when submitting GCHP support requests
9 GCHP environment file gchp.env The file used to load libraries and set module variables for GCHP simulations.
10 Run configuration log file runConfig.log Contains echo-back output from the ./ script. This contains information about the compute resources, grid information, restart and checkpoint files, outputs, timesteps, and operations that are selected for the GCHP simulation.
11 GCHP compilation log file compile.log Log file containing output from the GCHP compilation. Compilation errors would show up here.
12 GCHP log file gchp.log Log file containing GCHP standard output including what would typically go to a GEOS-Chem Classic log file.
13 CAP restart file cap_restart MAPL output text file containing GCHP run end time to be used as the next run's start time if doing multi-segmented runs. If not doing multi-segmented runs then this file should be deleted prior to rerunning so that start information in CAP.rc is used instead.

How long will I wait for a reply?

The GCST will endeavor to respond to your request as soon as possible. Typically we try to turn around requests within 2 business days or sooner. During times of high workload the wait may be longer.