Creating GEOS-Chem run directories
On this page we show you how to use the GEOS-Chem Unit Tester to generate and use fresh copies of run directories for your GEOS-Chem simulations.
Contents
Downloading the GEOS-Chem Unit Tester
IMPORTANT NOTE! As of June 2018, we have migrated the GEOS-Chem Unit Tester repository from Bitbucket back to Github. Going forward, please make sure to clone or pull code updates ONLY from the Github repository. Using Github will allow us to define a DOI for each GEOS-Chem version.
First, make sure that your system has these software packages installed. (Most of these come standard with your Unix-based operating system.)
Next, clone the GEOS-Chem Unit Tester package with these commands:
git clone https://github.com/geoschem/geos-chem-unittest UT cd UT git checkout master
This will download a fresh copy of the GEOS-Chem-UnitTest repository into a directory named UT, and place you in the master branch. The master branch always corresponds to the last benchmarked GEOS-Chem version.
If you would like to check out the Unit Tester that corresponds to a specific numbered GEOS-Chem version you can type one of the following commands:
git checkout 12.0.0 git checkout v11-02-rc git checkout v11-02e
etc.
NOTE: The Git clone process may take a few minutes to complete depending on your connection speed.
--Bob Yantosca (talk) 21:10, 21 June 2018 (UTC)
Available run directories
Benchmark run directory
The GEOS-Chem Unit Tester includes a run directory called 4x5_standard (GEOS-Chem v11-01 and later) or geosfp_4x5_benchmark (GEOS-Chem v10-01). The standard GEOS-Chem benchmark simulation utilizes the GEOS-FP met fields (4° x 5 °, 72 levels) with the UCX tropospheric-stratospheric chemistry mechanism and secondary organic aerosols included.
To reproduce our latest 1-month benchmark simulation for v11-01, you can edit the CopyRunDirs.input file so that the following line is uncommented under RUNS:
geosfp 4x5 - standard 2013070100 2013080100 -
Make sure to check the start and end date so that your simulation will run for July 2013. You can then create the GEOS-Chem benchmark run directory by typing ./gcCopyRunDirs. Navigate to your the newly created geosfp_4x5_benchmark run directory. To compile and run your benchmark simulation, type:
make -j4 mp
To compile only, type:
make -j4 mpbuild
That will create a geos.mp executable file that you can use to submit your GEOS-Chem benchmark simulation to a queue system.
NOTE: If you are compiling GEOS-Chem within the code directory, and not within a run directory created from the GEOS-Chem Unit Tester, you will need to pass the UCX=y option in your make command.
--Melissa Sulprizio (talk) 19:38, 23 June 2015 (UTC)
Other run directories
Run directories are provided for a combination of met field, grid, and simulation type and are named accordingly. For more details on the simulation types, please see our GEOS-Chem chemistry mechanism wiki page.
The following table summarizes the run directories that are available in the GEOS-Chem Unit Tester. Please choose the run directories that are most relevant for your research.
| Met field(s) | Grid | Standard | Tropchem | UCX | SOA | SOA-SVPOA | AcidUptake | MarinePOA | RRTMG | RnPbBe | Hg | tagHg | POPs | tagCO | tagO3 | CH4 | CO2 | aerosol | TOMAS15 | TOMAS40 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| GEOS-FP GEOS-5 MERRA MERRA-2 |
4x5 | |||||||||||||||||||
| GEOS-FP GEOS-5 MERRA MERRA-2 |
2x2.5 | |||||||||||||||||||
| Nested grid simulations: | ||||||||||||||||||||
| GEOS-FP | 025x03125 CH |
|||||||||||||||||||
| GEOS-FP | 025x03125 NA |
|||||||||||||||||||
| GEOS-5 | 05x0666 CH |
|||||||||||||||||||
| GEOS-5 | 05x0666 NA |
|||||||||||||||||||
| Other: | ||||||||||||||||||||
| GEOS-4 | 4x5 | |||||||||||||||||||
| GCAP | 4x5 | |||||||||||||||||||
LEGEND
| Run directory is available | |
| Run directory is in need of updating | |
| Run directory is obsolete | |
| Run directory is not available |
--Melissa Sulprizio (talk) 20:10, 8 December 2016 (UTC)
Editing the CopyRunDirs.input file
Once you have downloaded the GEOS-Chem Unit Tester to your disk space, switch to the perl/ directory:
cd UT/perl
In this directory there is a Perl script named gcCopyRunDirs that you will use to generate fresh copies of GEOS-Chem run directories. This script uses an input file named CopyRunDirs.input, which is also located in the perl directory.
IMPORTANT: The CopyRunDirs.input file that comes with the Unit Tester provides only a small sample of the possible run directories that you can create. You can add as many entries to the RUNS section as you wish. See the UnitTest.input file for a complete list of all possible run directories that you can add to CopyRunDirs.input.
Your CopyRunDirs.input file will look something like this:
#------------------------------------------------------------------------------
# GEOS-Chem Global Chemical Transport Model !
#------------------------------------------------------------------------------
#BOP
#
# !DESCRIPTION: Input file that specifies configuration for creating and
# copying a run directory from the UnitTester.
#\\
#\\
# !REMARKS:
# For a complete description of how to customize the settings in the
# INPUTS and RUNS sections, see the following wiki posts:
#
# wiki.geos-chem.org/Creating_GEOS-Chem_run_directories#Section_1:_INPUTS
# wiki.geos-chem.org/Creating_GEOS-Chem_run_directories#Section_2:_RUNS
#
# !REVISION HISTORY:
# 18 Mar 2015 - R. Yantosca - Initial version
# 19 Mar 2015 - E. Lundgren - Simplify content for only copying run dirs
# 19 May 2015 - R. Yantosca - Now can specify VERBOSE and WARNINGS options
#EOP
#------------------------------------------------------------------------------
#
# !INPUTS:
#
# %%% ID tags %%%
#
VERSION : v11-01
DESCRIPTION : Create run directory from UnitTest
#
# %%% Data path and HEMCO settings %%%
#
DATA_ROOT : /n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/data/ExtData
HEMCO_ROOT : {DATAROOT}/HEMCO
VERBOSE : 0
WARNINGS : 1
#
# %%% Unit tester path names %%%
#
UNIT_TEST_ROOT : {HOME}/UT
RUN_ROOT : {UTROOT}/runs
RUN_DIR : {RUNROOT}/{RUNDIR}
PERL_DIR : {UTROOT}/perl
#
# %%% Target directory and copy command %%%
#
COPY_PATH : {HOME}/GC/rundirs
COPY_CMD : cp -rfL
#
# !RUNS:
# Specify the runs directories that you want to copy below.
# Here we provide a few examples, but you may copy additional entries from
# UnitTest.input and modify the dates as needed. You can deactivate copying
# run certain directories by commenting them out with "#".
#
#--------|-----------|------|------------|------------|------------|---------|
# MET | GRID | NEST | SIMULATION | START DATE | END DATE | EXTRA? |
#--------|-----------|------|------------|------------|------------|---------|
geosfp 4x5 - standard 2013070100 2013080100 -
# geosfp 4x5 - gc_timing 2013070100 2013070800 -
# geosfp 4x5 - tropchem 2013070100 2013070101 -
# geosfp 4x5 - soa 2013070100 2013070101 -
# geosfp 4x5 - soa_svpoa 2013070100 2013070101 -
# geosfp 4x5 - aciduptake 2013070100 2013070101 -
# geosfp 4x5 - UCX 2013070100 2013070101 -
# geosfp 4x5 - RRTMG 2013070100 2013070101 -
# geosfp 4x5 - RnPbBe 2013070100 2013070101 -
# geosfp 4x5 - Hg 2013010100 2013010101 -
# geosfp 4x5 - POPs 2013070100 2013070101 -
# geosfp 4x5 - TOMAS40 2013070100 2013070101 -
# geosfp 4x5 - CH4 2013070100 2013070101 -
# geosfp 4x5 - tagO3 2013070100 2013070101 -
# geosfp 4x5 - tagCO 2013070100 2013070101 -
# geosfp 2x25 - CO2 2013070100 201307010030 -
# geosfp 4x5 - aerosol 2013070100 2013070101 -
# geosfp 025x03125 ch tropchem 2013070100 201307010010 -
# geosfp 025x03125 na tropchem 2013070100 201307010010 -
# gchp 4x5 - tropchem 2013070100 2013070101 -
!END OF RUNS:
#EOP
#------------------------------------------------------------------------------
NOTE: Lines starting with a # character will be treated as comments.
The CopyRunDirs.input file has a layout that is very similar to the GEOS-Chem Unit Tester input files (UnitTest.input located within this directory). Like the GEOS-Chem Unit Tester input files, CopyRunDirs.input is composed of an INPUTS section and a RUNS section, which are described below.
Section 1: INPUTS
Under the INPUTS section, you can customize the directory paths and other options for your system. Each configurable input is described in the table below.
| Option | Description |
|---|---|
| VERSION | An ID tag that will be added to all log files and output files. |
| DESCRIPTION | A short (1-sentence) description of the purpose of this specific file (optional). This may be used to differentiate different input files, such as if you pre-configure several for future re-use. |
| DATA_ROOT | Specifies the path for your root-level data directory. |
| HEMCO_ROOT | Specifies the top-level path for the HEMCO data directory tree.
Leave this as-is. |
| VERBOSE | Specifies the level of debug output that will be sent to the HEMCO log file. (0=no debug output; 3=max debug output)
|
| WARNINGS | Specifies the level of warning messages that will be sent to the HEMCO log file. (0=no warnings; 3=max warnings)
|
| UNIT_TEST_ROOT | Specifies the path to the GEOS-Chem Unit Tester. |
| RUN_ROOT | Specifies the top-level unit test run directories.
Leave this as-is. |
| RUN_DIR | Specifies the run directory subdirectory.
Leave this as-is. |
| PERL_DIR | Specifies the directory where the unit test Perl scripts are found.
Leave this as-is. |
| COPY_PATH | Specifies the directory on your disk server where copies of the GEOS-Chem run directories will be created. |
| COPY_CMD | Specifies the command used to copy run directories from the GEOS-Chem Unit Tester to COPY_PATH.
|
Section 2: RUNS
The layout of the RUNS section is identical to the RUNS section in the GEOS-Chem Unit Tester input file. This enables copying and pasting simulation settings text from UnitTest.input into CopyRunDirs.input.
For example, the following line:
# # !RUNS: # Specify the debugging runs that you want to perform below. # You can deactivate runs by commenting them out with "#". # #--------|-----------|------|------------|------------|------------|---------| # MET | GRID | NEST | SIMULATION | START DATE | END DATE | EXTRA? | #--------|-----------|------|------------|------------|------------|---------| geosfp 4x5 - standard 2013070100 2013080100 -
will tell the gcCopyRunDirs script to create a run directory for a GEOS-Chem simulation with the following settings:
- Using GEOS-FP met fields
- On the 4° x 5° GEOS-Chem horizontal grid
- For the GEOS-Chem standard full-chemistry simulation
- Starting at 00:00 GMT on 2013/07/01
- Ending at 00:00 GMT on 2013/08/01
The date range will be used to initialize the input.geos file that is read during a GEOS-Chem simulation. Once the run directory is created, you may edit these dates within the input.geos file. Note, however, that time ranges must remain within the time range covered by the MET field you are using. You can check the MET field temporal coverage on the GMAO met data products wiki page. Also note that we recommend using the restart files to spin up GEOS-Chem for at least one year prior to your simulation start date. You may use the resulting output restart files as initial values for your simulation.
You can add as many entries to the RUNS section as you wish. See the UnitTest.input file for a complete list of all possible run directories entries that you can add to CopyRunDirs.input.
Generating a GEOS-Chem Run Directory
Once you have edited the CopyRunDirs.input script to your liking, you can use that to generate fresh copies of GEOS-Chem run directories. Make sure you are in the perl directory, and then type:
./gcCopyRunDirs
If you do not pass a file name to gcCopyRunDirs, then the gcCopyRunDirs script will use the CopyRunDirs.input file that you just modified.
If you wish, you can create many customized copies of CopyRunDirs.input. For example, suppose you edit CopyRunDirs.input to generate a full-chemistry run directory. You can then save it as a separate file and use it explicitly with gcCopyRunDirs.
cp CopyRunDirs.input CopyRunDirs.fullchem # Input file set up to only copy the full-chemistry run directories gcCopyRunDirs CopyRunDirs.Hg
Executing gcCopyRunDirs will create a new GEOS-Chem run directory corresponding to each entry that you specified in the input file RUNS section. Each run directory will be created as a subdirectory of COPY_PATH that you specified in the input file INPUTS section.
Let's examine the contents of a sample geosfp_4x5_standard run directory. Navigate to your newly created run directory and tssue the following commands:
make fileclean # Remove any files left over from previous unit test runs ls -1 # Get directory listing
And you will see this directory listing:
brc.dat dust.dat FJX_j2j.dat FJX_spec.dat getRunInfo h2so4.dat HEMCO_Config.rc HEMCO_restart.201307010000.nc input.geos jv_spec_mie.dat Makefile org.dat output/ README so4.dat soot.dat ssa.dat ssc.dat v11-01.run validate
NOTE: Run directories for other simulations may contain other files not pictured here.
The input.geos and HEMCO_Config.rc files have been customized for this particular simulation. They were created from the corresponding template files input.geos.template and HEMCO_Config.template in the Unit Tester. The Perl script getRunInfo is used by the Makefile to extract information about the simulation from input.geos. HEMCO and tracer restart files are also included in every run directory but care must be taken when using them. See the section below for more information about restart files.
Important Notes About Restart Files
Please see this post on the GEOS-Chem basics wiki page for more information about how to obtain sample restart files for your simulations.
Compiling GEOS-Chem
Starting in v11-01, you can now compile GEOS-Chem directory from the run directory. See theGEOS-Chem Makefile Structure wiki page wiki page for more information about compiling GEOS-Chem and using the run directory Makefile.
Running GEOS-Chem
We generally recommend users compile GEOS-Chem from within their run directory to create the geos (or geos.mp) executable. GEOS-Chem simulations can then be submitted to a local cluster's queue using a simple script. For example:
#!/bin/bash ./geos.mp >> GC.log exit 0
GEOS-Chem Output Files
Once the GEOS-Chem simulation is complete, you will see several new files in the run directory. Some of these are generated for all simulations while others may be simulation-dependent. For more information, see our GEOS-Chem Output Files wiki page.
