Creating GEOS-Chem run directories

From Geos-chem
Revision as of 17:44, 2 April 2015 by Melissa Payer (Talk | contribs) (Run directory tips)

Jump to: navigation, search

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.

Downloading the GEOS-Chem Unit Tester

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 the command:

git clone -b v10-01-public git://git.as.harvard.edu/bmy/GEOS-Chem-UnitTest UT

This will create a copy of the GEOS-Chem Unit Tester package in a directory named UT for short.

The option

-b v10-01-public

specifies which branch of the GEOS-Chem Unit Tester that you would like to download. Branches in the GEOS-Chem unit tester correspond to each internal version of GEOS-Chem (i.e. the states of the code for which we run 1-month benchmark simulations), as well as the publicly-released versions. Most likely, you will want to download the v10-01-public branch of the GEOS-Chem Unit Tester, which corresponds to the public release of GEOS-Chem v10-01.

--Bob Y. 13:36, 19 March 2015 (EDT)

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.

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:  
#  Customize the run directory for your system by specifying these values:
#  -------------------------------------------------------------------
#  VERSION     : A tag used to identify this Unit Test (e.g. v10-01h)
#  DESCRIPTION : A short description of this file's run dir copy configuration
#  COPY_PATH   : Local path where run directory will be copied to
#  DATA_ROOT   : Root GEOS-Chem data directory
#  HEMCO_ROOT  : Root directory where HEMCO emissions data files are stored 
#  RUN_ROOT    : Unit test run directories are subdirectories of RUN_ROOT
#  RUN_DIR     : Individual unit test run directory path
#  PERL_DIR    : Unit Test perl script directory (i.e. this directory)
#  COPY_CMD    : Unix copy command with optional tags
#
# !REVISION HISTORY:
#  18 Mar 2015 - R. Yantosca - Initial version
#  19 Mar 2015 - E. Lundgren - Simplify content for only copying run dirs
#EOP
#------------------------------------------------------------------------------
#
# !INPUTS:
#
   VERSION     : v10-01h
   DESCRIPTION : Create run directory from UnitTest
   COPY_PATH   : /home/{USER}/GC/rundirs
   DATA_ROOT   : /as/data/geos/ExtData
   HEMCO_ROOT  : {DATAROOT}/HEMCO
   RUN_ROOT    : /home/{USER}/UT/runs
   RUN_DIR     : {RUNROOT}/{RUNDIR}
   PERL_DIR    : /home/{USER}/UT/perl
   COPY_CMD    : cp -rfL
#
# !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   2x25        -      Hg           2013070100   2013070101   -
  geos5    2x25        -      Hg           2005070100   2005070101   -
  geosfp   4x5         -      fullchem     2013070100   2013070101   -
  geos4    4x5         -      Hg           2005070100   2005070101   -
  geos4    4x5         -      CH4          2005070100   2005070101   -
  geosfp   4x5         -      Hg           2013070100   2013070101   -
  geosfp   4x5         -      POPs         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. (These are the files named UnitTest.input, etc.) 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. As seen above, most of these inputs are self-explanatory.

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.
COPY_PATH Specifies the root directory on your disk server where copies of the GEOS-Chem run directories will be created.
DATA_ROOT Specifies the path for your root-level data directory.
HEMCO_ROOT Specifies the top-level path for the HEMCO data directory tree.
  • The {DATAROOT} token in HEMCO_ROOT will be replaced with the value you specify for RUN_ROOT option.

Leave this as-is.

RUN_ROOT Specifies the top-level unit test run directories.

Leave this as-is.

PERL_DIR Specifies the directory where the unit test Perl scripts are found.

Leave this as-is.

COPY_CMD Specifies the command used to copy run directories from the GEOS-Chem Unit Tester to COPY_PATH.
  • The default setting is cp -rfL. This will create a new copy of the directory, even if the prior copy exists.
  • The -L option to the cp will create "hard" copies of files that are symbolic links. This command may differ slightly depending on the flavor of your Unix-based Operating system.

--Bob Y. 14:20, 19 March 2015 (EDT)

Section 2: RUNS

The layout of the !RUNS section is identical to The !RUNS section in the GEOS-Chem Unit Tester input files. This allows you to copy and paste text from one or more GEOS-Chem Unit Tester input files 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   2x25        -      Hg           2013070100   2013070101   -

will tell the gcCopyRunDirs script to create a run directory for a GEOS-Chem simulation using:

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 the restart files automatically generated for the run directory correspond only to the original date specified in the CopyRunDirs.input file. Restart files for a later dates must be generated by running a simulation that ends on that date.

You can add as many entries to the !RUNS section as you wish. Simply cut and paste from one of the existing GEOS-Chem Unit Test input files (e.g. UnitTest.input within UT/perl).

Generating a 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 created.

If you wish, you can create many customized copies of CopyRunDirs.input. For example, suppose you edit CopyRunDirs.input to generate a mercury run directory. You can then save it as a separate file and use it explicitly with gcCopyRunDirs.

cp CopyRunDirs.input CopyRunDirs.Hg   # Input file set up to only copy the Hg run directories
 
gcCopyRunDirs CopyRunDirs.Hg                 

Executing gcCopyRunDirs will create a new GEOS-Chem run directory corresponding to each entry that you specified in the CopyRunDirs.* file. Each run directory will be created as a subdirectory of !COPY_PATH.

Let's examine the contents of a sample geosfp_2x25_Hg run directory. Issue the following commands:

cd ~/GC/rundirs/geosfp_2x25_Hg  # Change to geosfp_2x25_Hg run dir 
  
make fileclean                  # Remove any files left over from previous unit test runs

ls -l                           # Get detailed directory listing

And you will see this directory listing:

-rw-r--r-- 1 bmy bmy   17137 2015-03-18 16:18 HEMCO_Config.rc
-rw-r--r-- 1 bmy bmy   17116 2015-03-18 16:18 HEMCO_Config.template
-rw-r--r-- 1 bmy bmy    4568 2015-03-18 16:18 Makefile
-rwxr-xr-x 1 bmy bmy    1458 2015-03-18 16:18 getEnd.pl*
-rwxr-xr-x 1 bmy bmy    1374 2015-03-18 16:18 getStart.pl*
-rw-r--r-- 1 bmy bmy 7391476 2015-03-18 16:18 initial_trac_rst.geosfp_2x25_Hg
-rw-r--r-- 1 bmy bmy   12082 2015-03-18 16:20 input.geos
-rw-r--r-- 1 bmy bmy   12060 2015-03-18 16:18 input.geos.template
-rw-r--r-- 1 bmy bmy  210712 2015-03-18 16:18 ocean_rst.geosfp_2x25_Hg.201307010000

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. The template files are otherwise not used.

The Perl scripts getStart.pl and getEnd.pl pass the starting and ending dates of the simulation, as specified in the input.geos file, to the Makefile.

--Bob Y. 14:24, 19 March 2015 (EDT)

Compiling and Running GEOS-Chem

Once you have created one or more GEOS-Chem run directories, you can use them for your GEOS-Chem simulations. First, doublecheck that the settings in the input.geos and HEMCO_Config.rc files are correct for the simulation that you are trying to run. See the GEOS-Chem Manual for more information about setting simulation options.

To start a GEOS-Chem simulation, type the following commands. (We'll use the example of the geos5_2x25_Hg simulation, from the previous sections.)

make -j4 CODE_DIR=~/GC/Code.v10-01 VERSION=v10-01 MET=geosfp GRID=2x25 TRACEBACK=y mp

The above command specifies: (1) the location of the code to compile (CODE_DIR), (2) a version tag to use as a prefix in our data output file (VERSION), (3) the met field to use (MET), (4) the grid resolution to use (GRID), and (5) whether to show traceback for debugging (TRACEBACK). The MET and GRID values must match those for your run directory. If you wish, you can omit the VERSION option. If you do not include VERSION, it will automatically be set to GC..

The final command mp is a makefile target defined in the file Makefile within the run directory. In our example, mp indicates that our code will be compiled and then run with OpenMP parallelization. You can also specify sp to compile and run code using a single processor. This will result in output files having the .sp rather than .mp suffix. See the Makefile for other make options and Section 3.6.2 of the GEOS-Chem Manual for more information about makefiles.

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 the case of our mercury simulation example, the following files are output:

File Description
trac_avg.geosfp_2x25_Hg.YYYYMMDDhh.mp or
trac_avg.geosfp_2x25_Hg.YYYYMMDDhh.sp
Diagnostic output file that contains time-averaged output for diagnostics enabled in input.geos. Data in this file are in "binary punch" format and may be viewed and manipulated using GAMAP.
trac_rst.geosfp_2x25_Hg.YYYYMMDDhhmm.mp or
trac_rst.geosfp_2x25_Hg.YYYYMMDDhhmm.sp
Tracer restart file that contains instantaneous tracer concentrations at simulation end time. This file may be used to initialize another GEOS-Chem simulation. Data in this file are in "binary punch" format and may be viewed and manipulated using GAMAP.
HEMCO_restart.YYYYMMDDhh.nc HEMCO restart file containing several quantities tracked by HEMCO for use in initializing another GEOS-Chem simulation. Data in this file are in netcdf format.
ocean_rst.YYYYMMDDhhmm.nc Ocean mercury restart file containing several quantities pertaining to the ocean mercury module saved at the end of the GEOS-Chem simulation. Like the tracer restart file, this file may be used to initialize another GEOS-Chem mercury simulation. Data in this file are in the in netcdf format.
v10-01.geosfp_2x25_Hg.mp or
v10-01.geosfp_2x25_Hg.sp
GEOS-Chem simulation log file. Open this file in a text editor to diagnose compile and run errors.
HEMCO.log.mp or
HEMCO.log.sp
HEMCO log file containing detailed information about the emissions read from disk into HEMCO. Open this file in a text editor to diagnose HEMCO errors.
diaginfo.dat File generated by GEOS-Chem that contains diagnostic quantities for use with GAMAP.
tracerinfo.dat File generated by GEOS-Chem that contains tracer name metadata for use with GAMAP.

--Lizzie Lundgren 16:38, 23 March 2015 (EDT)

Available run directories

Here we summarize the run directories that are available in the GEOS-Chem Unit Tester. Please choose the run directory or run directories that are most relevant for your research.

Met field Resolution Full-
chemistry
UCX RRTMG SOA SOA w/ SVPOA Rn-Pb-Be Hg POPs Tagged CO Tagged O3 CH4 CO2 Aerosols TOMAS
GEOS-FP 4° x 5°


GEOS-FP 2° x 2.5°
GEOS-FP 0.25° x 0.3125°
nested CH


GEOS-FP 0.25° x 0.3125°
nested NA
GEOS-5 4° x 5°


GEOS-5 2° x 2.5°


GEOS-5 0.5° x 0.666°
nested CH


GEOS-5 0.5° x 0.666°
nested NA
MERRA 4° x 5°


MERRA 2° x 2.5°
GEOS-4 4° x 5°
GCAP 4° x 5°
LEGEND
Run directory is available
Run directory is in need of updating
Run directory is obsolete
Run directory is not available

--Melissa Sulprizio 17:52, 1 April 2015 (EDT)

Run directory notes

  • In each run directory, we provide a GEOS-Chem restart file that you can use to initialize your simulation. However, it is highly recommended that you not use these restart files for any of your production runs. Rather, you will probably want to generate your own restart file by spinning up the model for at least a year.
  • You can create a run directory for the nested grid simulations from a 4° x 5° or 2° x 2.5° run directory by following these steps:
  1. Modify the input.geos file for the nested grid simulation. Complete instructions can be found on this wiki page.
  2. Regrid the restart file(s) using the GAMAP regridding routines. For example, REGRIDH_RESTART can be used to regrid the tracer restart file from one horizontal resolution to another. You can then use CREATE_NESTED to crop the restart file to your nested domain (CH, EU, or NA).
  • You can create a MERRA run directory from a GEOS-5 or GEOS-FP run directory, since all three met fields have the same horizontal and vertical resolution.
  • If you would like to run a simulation and the run directory is not available in the Unit Tester, you can follow these steps:
  1. Modify the input.geos file for your simulation type following the relevant checklist in Chapter 6 of the GEOS-Chem Manual.
  2. Create a "fake" restart file using GAMAP routine MAKE_RESTART.
  3. Alternatively, you can send an email to the relevant Working Group to see if another member can provide you with a run directory or restart file.

--Melissa Sulprizio 18:23, 1 April 2015 (EDT)