Difference between revisions of "Submitting GEOS-Chem support requests"

From Geos-chem
Jump to: navigation, search
(How can I make a support request?)
(Replaced content with "This content has been migrated to [https://geos-chem.readthedocs.io/en/latest/reference/SUPPORT.html the '''Support guidelines''' page at <tt>geos-chem.readthedocs.io</tt>].")
 
Line 1: Line 1:
On this page we provide information about how to report any GEOS-Chem issues that you may encounter.
+
This content has been migrated to [https://geos-chem.readthedocs.io/en/latest/reference/SUPPORT.html the '''Support guidelines''' page at <tt>geos-chem.readthedocs.io</tt>].
 
+
== Featured video tutorials ==
+
 
+
We recommend that you view these video tutorials, particularly if this is your first time submitting a support request.  These videos are posted at  [http://youtube.geos-chem.org '''youtube.geos-chem.org'''].
+
 
+
{| border="1" cellspacing=0 cellpadding=5
+
|-valign="top" align="center"
+
|[[Image:Github_Notifications_Thumbnail.png]]<br>[https://www.youtube.com/watch?v=RuH6zeYuzuY&t=314s '''<big>Click HERE to view!</big>''']
+
|[[Image:Github_issues_thumbnail.png]]<br>[https://www.youtube.com/watch?v=dFBhdotYVf8 '''<big>Click HERE to view!</big>''']
+
|[[Image:Github_Searching_thumbnail.png]]<br>[https://www.youtube.com/watch?v=EiZC2vaXNnU&t=336s '''<big>Click HERE to view!</big>''']
+
|}
+
 
+
== Overview ==
+
 
+
=== Should I first try to solve my issue by myself? ===
+
 
+
The [[GCST]] encourages all GEOS-Chem users to try to debug issues to the greatest extent possible.  Please see our [[Debugging_GEOS-Chem|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 [[Bugs and fixes|our ''Bugs and fixes'' wiki page]], as well as our [https://github.com/geoschem/geos-chem/issues/ GEOS-Chem issue tracker on Github].
+
 
+
If you still cannot resolve your issue on your own, then please do not hesitate to submit a [[#Contacting the GEOS-Chem Support Team for assistance|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 [[GEOS-Chem_Support_Team#Mission|the GCST's mission to support the International GEOS-Chem User Community]].
+
 
+
Even though [[GEOS-Chem_Support_Team#Specific_tasks_handled_by_the_GEOS-Chem_Support_Team|the GCST can assist in many different ways]], it cannot possibly do everything.  GEOS-Chem users are expected [[GEOS-Chem_Support_Team#Responsibilities_of_the_GEOS-Chem_User_Community|to take on certain responsibilities]]. For example, the GCST relies on users to make sure that their computer system has all of the [[Installing libraries for GEOS-Chem|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 [http://acmg.seas.harvard.edu/geos/geos_working_groups.html 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).
+
 
+
{| border=1 cellpadding=5 cellspacing=0
+
|-valign="top"
+
!width="200px"  bgcolor="#CCCCCC"|Open a support request for:
+
!width="800px" bgcolor="#CCCCCC"|Instructions
+
 
+
|-valign="top"
+
|GEOS-Chem
+
|
+
(1) Open this link (in a new browser tab): [https://github.com/geoschem/geos-chem/issues/new/choose <tt>https://github.com/geoschem/geos-chem/issues/new/choose</tt>]
+
 
+
(2) You will then see this screen:
+
[[Image: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) Edit the title text AFTER the issue type in brackets. Keep the title brief. For example: <tt>[BUG/ISSUE] Problem compiling 12.7.0 with gfortran</tt>.
+
 
+
(5) Read the directions in the issue template text box.  Edit the text box to customize information for your issue. Please be sure to [[#What do I need to include in my support request?|include all relevant documentation]]. You can drag and drop text files and images into the issue box. Text files must be renamed to have extension '.txt'. Click the preview tab to see the rendering.
+
 
+
|-valign="top"
+
|GCHP
+
|
+
Same procedure as for GEOS-Chem above but in the GCHP repository: <tt>https://github.com/geoschem/gchp/issues/new</tt>
+
 
+
|-valign="top"
+
|GCPy
+
|
+
Same procedure as for GEOS-Chem above but in the GCPy repository: <tt>https://github.com/geoschem/gcpy/issues/new/choose</tt>
+
 
+
|-valign="top"
+
|Other topics
+
|Email your question to the [[GEOS-Chem Support Team]].
+
 
+
Use this email address: '''geos-chem-suppport [at] g.harvard.edu'''.
+
 
+
|}
+
 
+
=== 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.
+
 
+
{| border=1 cellpadding=5 cellspacing=0
+
 
+
|-valign="top"
+
!width="20px"  bgcolor="#CCCCCC"|#
+
!width="250px" bgcolor="#CCCCCC"|Item
+
!width="150px" bgcolor="#CCCCCC"|Filename(s)
+
!width="600px" bgcolor="#CCCCCC"|Description / Notes
+
 
+
|-valign="top"
+
|0
+
|Version of GEOS-Chem you are using
+
|
+
|You can find out what version you are using typing <tt>git log</tt> 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 <tt>geos-chem-unittest</tt> that you created the run directory from.
+
 
+
|-valign="top"
+
|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.
+
 
+
|-valign="top"
+
|2
+
|[[GEOS-Chem_Input_Files#The_input.geos_file|<tt>input.geos</tt> file]]
+
|<tt>input.geos</tt>
+
|File containing the various input options for your simulation.
+
 
+
|-valign="top"
+
|3
+
|[[GEOS-Chem_Input_Files#The_HEMCO_Config.rc_file|HEMCO configuration file]]
+
|<tt>HEMCO_Config.rc</tt>
+
|File containing input information for the HEMCO emissions component.
+
 
+
|-valign="top"
+
|4
+
|[[GEOS-Chem_Output_Files#The_lastbuild_file|Lastbuild file]]
+
|<tt>lastbuild</tt>
+
|File containing a summary of all of the options that were used to build the GEOS-Chem executable
+
 
+
'''''NOTE:''''' GEOS-Chem "Classic" simulations (versions [[GEOS-Chem 12#12.5.0|12.5.0]] and earlier) create files named <tt>lastbuild.mp</tt> or <tt>lastbuild.sp</tt>, depending on whether OpenMP parallelization is turned on or off.
+
 
+
|-valign="top"
+
|5
+
|[[GEOS-Chem_Output_Files#GEOS-Chem_log_file|GEOS-Chem "Classic" log file]]
+
|<tt>GC_*.log</tt> or<br><tt>GC_*.log.mp</tt> or <br><tt>GC_*.log.sp</tt>
+
 
+
|Contains an "echo-back" of all input options that were specified in <tt>input.geos</tt>, 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.
+
 
+
|-valign="top"
+
|6
+
|[[GEOS-Chem_Output_Files#HEMCO_log_file|HEMCO log file]]
+
|<tt>HEMCO.log</tt> or<br><tt>HEMCO.log.mp</tt> or<br><tt>HEMCO.log.sp</tt>
+
|Contains information about how emissions, met fields, and other relevant data are read from disk and processed by HEMCO for input into GEOS-Chem.
+
 
+
|-valign="top"
+
|7
+
|Output file from your job scheduler
+
 
+
*Only if you ran GEOS-Chem with a batch scheduler (e.g. SLURM, PBS, LSF, etc.)
+
 
+
|<tt>slurm-JOBID.out</tt>
+
|Contains stdout and/or stderr output from the your job scheduler.  May contain important error messages.
+
 
+
|-valign="top"
+
|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.
+
 
+
|-valign="top"
+
!colspan="4" bgcolor="#CCFFFF"|List of additional information to include when submitting [[GCHP Main Page|GCHP]] support requests
+
 
+
|-valign="top"
+
|9
+
|GCHP environment file
+
|<tt>gchp.env</tt>
+
|The file used to load libraries and set module variables for GCHP simulations.
+
 
+
|-valign="top"
+
|10
+
|Run configuration log file
+
|<tt>runConfig.log</tt>
+
|Contains echo-back output from the <tt>./createRunDir.sh</tt> 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.
+
 
+
|-valign="top"
+
|11
+
|GCHP compilation log file
+
|<tt>compile.log</tt>
+
|Log file containing output from the GCHP compilation. Compilation errors would show up here.
+
 
+
|-valign="top"
+
|12
+
|GCHP log file
+
|<tt>gchp.log</tt>
+
|Log file containing GCHP standard output including what would typically go to a GEOS-Chem Classic log file.
+
 
+
|-valign="top"
+
|13
+
|CAP restart file
+
|<tt>cap_restart</tt>
+
|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 <tt>CAP.rc</tt> 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.
+

Latest revision as of 16:01, 15 August 2022

This content has been migrated to the Support guidelines page at geos-chem.readthedocs.io.