Difference between revisions of "Running GEOS-Chem"

From Geos-chem
Jump to: navigation, search
(Submitting consecutive runs)
Line 16: Line 16:
  
  
== Overview ==
+
This content has been migrated to the [https://geos-chem.readthedocs.io/en/latest/gcc-guide/05-run/run.html '''Run your simulation''' chapter of geos-chem.readthedocs.io]
 
+
This page presents the basic information needed to run GEOS-Chem as well as how to verify a successful run and reuse a run directory.
+
 
+
== Important things to know before you submit your run ==
+
 
+
#Please be aware of several options available for speeding up your GEOS-Chem simulations. See our ''[[Speeding up GEOS-Chem]]'' page for more information.
+
#The initial restart files do not reflect the actual atmospheric state and should only be used to "spin up" the model. In other words, they should be used as initial values in an initialization simulation to generate more accurate initial conditions for your production runs. See [[GEOS-Chem_basics#Restart_files|this wiki post]] for more information.
+
#Prior to running with GEOS-FP met fields, please be aware of several caveats regarding that data stream. See the [[GEOS-FP|GEOS-FP]] wiki page for more information.
+
 
+
== Pre-run checklist ==
+
 
+
Prior to running GEOS-Chem, always run through the following checklist to ensure everything is set up properly.
+
 
+
#You have [[Configuring your computational environment|properly configured your Unix environment]]
+
#Your have run directory contains the [[Compiling_GEOS-Chem|<tt>geos</tt> executable]]
+
#You have set the proper [[GEOS-Chem configuration files|configurable settings]] for your simulation in:
+
##[[The_input.geos_file|<tt>input.geos</tt>]] (general simulation settings)
+
##[[The_HEMCO_Config.rc_file|<tt>HEMCO_Config.rc</tt>]] (emissions settings)
+
##[[The HEMCO_Diagn.rc file|<tt>HEMCO_Diagn.rc</tt>]]
+
##[[HISTORY.rc_and_other_configuration_files|<tt>HISTORY.rc</tt> and other diagnostic configuration files]]
+
#You have a run script ([[Running_GEOS-Chem#Running_as_a_Batch_Job|see below]])
+
#Your GEOS-Chem "Classic" run script [[Specifying settings for OpenMP parallelization|contains proper settings for OpenMP parallelization]], namely:
+
##[[Specifying_settings_for_OpenMP_parallelization#OMP_NUM_THREADS|<tt>OMP_NUM_THREADS</tt>]]
+
##[[Specifying_settings_for_OpenMP_parallelization#OMP_STACKSIZE|<tt>OMP_STACKSIZE</tt>]]
+
#You have enough [[Minimum_system_requirements_for_GEOS-Chem#Hardware_Recommendations|memory and computational cores available]]
+
 
+
== How to run GEOS-Chem ==
+
 
+
You can run GEOS-Chem locally from within your run directory (interactively) or by submitting your run to your cluster's job scheduler.
+
 
+
=== Running Interactively ===
+
 
+
If your computer system allows interactive computational sessions, then you can run GEOS-Chem interactively.  This is useful if you need to run short simulations for debugging or testing. 
+
 
+
''NOTE: If you are working with GEOS-Chem on the Amazon Web Services cloud computing platform, then you can always run GEOS-Chem interactively, because you will not be sharing your computational environment with other users.  See [http://cloud.geos-chem.org '''cloud.geos-chem.org'''] for more information.''
+
 
+
To run GEOS-Chem interactively in your terminal window:
+
 
+
'''1.''' Make sure that you have set the proper [[Setting Unix environment variables for GEOS-Chem|Unix environment variables for GEOS-Chem]] in your interactive session. 
+
 
+
'''2.''' Navigate to your run directory and type:
+
 
+
      ./geos
+
 
+
:'''2a''' You may also send the GEOS-Chem output to a log file by using:
+
 
+
      ./geos > GC.log
+
 
+
:'''2b''' You may send the GEOS-Chem output to a log file and to your screen using:
+
 
+
      ./geos 2>&1 | tee GC.log
+
 
+
''NOTE: Prior to [[GEOS-Chem 12#12.6.0|GEOS-Chem 12.6.0]], the executable was named either <tt>geos.mp</tt> or <tt>geos.sp</tt>, depending on whether or not OpenMP parallelization was turned on or off.''
+
 
+
=== Running as a Batch Job ===
+
 
+
Many shared computational clusters require that long simulations must be submitted as batch jobs via a scheduler (such as LSF, PBS, GridEngine, or SLURM).  Here is a sample script that you can modify for your own particular scheduler. 
+
 
+
''NOTE: Ask your sysadmin or IT staff, or consult your IT documentation for more information about the scheduler used by your institution, and the commands that it takes.
+
 
+
#!/bin/bash
+
+
# NOTE: depending on your scheduler, there may be some tags at the
+
# top of the run script (e.g. #SBATCH, #PBS or #LSF).  These tell
+
# the scheduler how many cores to use, which queue to use, how
+
# much memory to use, etc.  Because these are very system-dependent,
+
# we have omitted these here.  See the benchmark.run script in the
+
# geosfp_4x5_benchmark run directory for an example using the SLURM
+
# scheduler.
+
+
# Load your environment settings
+
source ~/.bashrc
+
+
# Declare that we would like to run GEOS-Chem with 16 cores
+
# (change this for your system)
+
export OMP_NUM_THREADS=16
+
+
# Max out the stack memory for the simulation.
+
# If your system has less than 500 MB then it should still
+
# give you the max amount available, which should be sufficient.
+
export OMP_STACKSIZE=500m
+
+
# Run the GEOS-Chem executable, and pipe output to a log file
+
./geos >> GC.log
+
 
+
=== Run script samples ===
+
 
+
In [[GEOS-Chem 13.0.0]] and later versions a folder named <tt>runScriptSamples</tt> is created in each [[Creating GEOS-Chem run directories|GEOS-Chem run directory]] that you create.  This folder has a few sample run scripts for the SLURM scheduler that you can use or modify
+
 
+
== Verifying a Successful Run ==
+
 
+
There are several ways to verify that your run was successful.
+
 
+
'''1.''' The following output can be found at the end of your GEOS-Chem log file:
+
      **************&nbsp;&nbsp;&nbsp;E N D&nbsp;&nbsp;&nbsp;O F&nbsp;&nbsp;&nbsp;G E O S -- C H E M&nbsp;&nbsp;&nbsp;**************
+
 
+
'''2.''' NetCDF files (<tt>GEOSChem.*.nc4</tt>) are present in the <tt>OutputDir/</tt> subfolder of the run directory.
+
 
+
'''3.''' [[GEOS-Chem restart files|Restart files]] (<tt>GEOSChem.Restart.*nc4</tt>, <tt>HEMCO_restart*.nc</tt>) for the ending date and time of the simulation are present in the run directory.
+
 
+
'''4.''' Your scheduler log (e.g. output from SLURM, LSF, PBS, etc.) does not contain any obvious errors.
+
 
+
If your run stopped with an error, please the following resources:
+
* ''[[Guide to GEOS-Chem error messages]]''
+
* [[GEOS-Chem coding and debugging#GEOS-Chem debugging tips|Tips on how to debug GEOS-Chem effectively]]
+
* [[Submitting GEOS-Chem support requests]]
+
 
+
== Submitting consecutive runs ==
+
 
+
'''''Please note: As of October 2019, the [[GCST]] is actively investigating differences in model output when running single vs multi-segmented runs. Any issues found will be addressed as soon as possible to minimize these differences.'''''
+
 
+
Often, users will split long simulations into several smaller simulations to stay within their cluster's computational limits. When doing so, make sure you follow these guidelines to minimize differences in model output:
+
 
+
'''1.''' Turn off setting initial stratospheric H2O mixing ratios in input.geos for all runs after your initial run to ensure you use H2O concentrations (found in the restart file) from the previous run:
+
 
+
    => Set initial glob MRs:---
+
        => strat. H2O?      : F
+
 
+
'''2.''' Make sure <tt>GC_RESTART</tt> and <tt>HEMCO_RESTART</tt> options are set to <b><tt>true</tt></b> in HEMCO_Config.rc.
+
 
+
'''3.''' To ensure you restart files are read and species concentrations are properly initialized, you may check your GEOS-Chem log file for the following output:
+
 
+
      ===============================================================================
+
      R E S T A R T  F I L E  I N P U T
+
+
      Min and Max of each species in restart file [mol/mol]:
+
      Species  1,      NO: Min = 1.000000003E-30  Max = 1.560991691E-08
+
      Species  2,      O3: Min = 3.135925075E-09  Max = 9.816152669E-06
+
      Species  3,      PAN: Min = 3.435056848E-25  Max = 1.222619450E-09
+
      ...
+
 
+
:Actual values may differ. If you see "<tt>Use background = ...</tt>" for most/all species, that suggests your restart file was not found. To avoid using the wrong restart file make sure to use time cycle flag <b><tt>EY</tt></b> in HEMCO_Config.rc to only use a restart file for the exact simulation date.
+
 
+
== Further reading ==
+
 
+
#[https://slurm.schedmd.com/documentation.html SLURM manual]
+
#[https://www.rc.fas.harvard.edu/resources/documentation/convenient-slurm-commands/ ''Convenient SLURM commands'' (Harvard)]
+
#[https://hpc.llnl.gov/banks-jobs/running-jobs/lsf-user-manual ''LSF user manual'' (LLNL)]
+
#[https://learn.scientificprogramming.io/learn-to-use-pbs-pro-job-scheduler-ffd9c0ad680d ''Learn to use PBS Pro job scheduler'' (LearnScientificProgramming.io)]
+
#''[[Guide to GEOS-Chem performance]]''
+
  
  
 
----
 
----
 
'''''[[Compiling GEOS-Chem|Previous]] | [[GEOS-Chem output files|Next]] | [[Getting Started with GEOS-Chem]]'''''
 
'''''[[Compiling GEOS-Chem|Previous]] | [[GEOS-Chem output files|Next]] | [[Getting Started with GEOS-Chem]]'''''

Revision as of 20:37, 3 August 2022

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Installing required software
  3. Configuring your computational environment
  4. Downloading source code
  5. Downloading data directories
  6. Creating run directories
  7. Configuring runs
  8. Compiling
  9. Running
  10. Output files
  11. Python tools for use with GEOS-Chem
  12. Coding and debugging
  13. Further reading


This content has been migrated to the Run your simulation chapter of geos-chem.readthedocs.io



Previous | Next | Getting Started with GEOS-Chem