Example: Create a carbon gases simulation run directory

The process of creating run directories for the GEOS-Chem specialty simulations is similar to that of the previous example. But the number of menus that you need to select from will likely be fewer than for the full-chemistry simulation. We’ll use the carbon gases simulation as an example.

  1. Navigate to the GCClassic superproject folder and get a directory listing:

    $ cd /path/to/your/GCClassic
    $ ls -CF
    AUTHORS.txt   CMakeLists.txt  CONTRIBUTING.md  LICENSE.txt  run@    src/        test@
    CHANGELOG.md  CMakeScripts/   docs/            README.md    spack@  SUPPORT.md
    

    As mentioned previously, run@ is a symbolic link. It actually points to the to the src/GEOS-Chem/run/GCClassic folder. This folder contains several scripts and template files for run directory creation.

  2. Navigate to the run folder and get a directory listing:

    $ cd run
    $ ls -CF
    archiveRun.sh*                  gitignore                   init_rd.sh*
    createRunDir.sh*                HEMCO_Config.rc.templates/  README.md
    geoschem_config.yml.templates/  HEMCO_Diagn.rc.templates/   runScriptSamples/
    getRunInfo*                     HISTORY.rc.templates/       setupForRestarts.sh*
    

    You can see several folders (highlighted in the directory display with /) and a few executable scripts (highlighted with *). The script we are interested in is createRunDir.sh.

  3. Run the createRunDir.sh script.. Type:

    $ ./createRunDir.sh
    


  4. You will then be prompted to supply information about the run directory that you wish to create:

    ===========================================================
    GEOS-CHEM RUN DIRECTORY CREATION
    ===========================================================
    
    -----------------------------------------------------------
    Choose simulation type:
    -----------------------------------------------------------
       1. Full chemistry
       2. Aerosols only
       3. Carbon
       4. Hg
       5. POPs
       6. Tagged O3
       7. Trace metals
       8. TransportTracers
       9. CH4
      10. CO2
      11. Tagged CO
    >>>
    

    To select the GEOS-Chem carbon gases specialty simulation, type 3 followed by ENTER.

    Tip

    To exit, the run directory creation process, type Ctrl-C at any prompt.


  5. You will be asked if you wish to set up a carbon simulation with all species (CH4, CO, CO2, OCS), or with just one of these species:

    -----------------------------------------------------------
    Do you wish to use a single advected species?
    -----------------------------------------------------------
      1. Use all species
      2. Use CH4 only
      3. Use CO2 only
      4. Use CO only
      5. Use OCS only
    >>>
    

    Let’s pick the carbon simulation with all species. Type 1 followed by ENTER.

  6. You will then be asked to specify the meteorology type for the simulation (GEOS-FP, MERRA-2), or GCAP 2.0):

    Attention

    We are still evaluating GEOS-Chem with the new NASA GEOS-IT meterorology product. Please select one of the other meteorology options for the time being.

    -----------------------------------------------------------
    Choose meteorology source:
    -----------------------------------------------------------
      1. MERRA-2 (Recommended)
      2. GEOS-FP
      3. GEOS-IT (Beta release)
      4. GISS ModelE2.1 (GCAP 2.0)
    >>>
    

    To accept the recommended meteorology (MERRA-2), type 1 followed by ENTER.

    Important

    The convection scheme used for GEOS-FP met generation changed from RAS to Grell-Freitas with impact on GEOS-FP meteorology files starting June 1, 2020. For this reason we recommend using MERRA-2 instead of GEOS-FP if running a simulation across June 1, 2020 to avoid unexpected discontinuities. Additional information about the impact of the convection change is at geoschem/geos-chem#1409.

  7. The next menu will prompt you for the horizontal resolution that you wish to use:

    -----------------------------------------------------------
    Choose horizontal resolution:
    -----------------------------------------------------------
      1. 4.0  x 5.0
      2. 2.0  x 2.5
      3. 0.5  x 0.625
    >>>
    

    If you wish to set up a global simulation, type either 1 or 2 followed by ENTER.

    If you wish to set up a nested-grid simulation, type 3 and hit ENTER. Then you will be followed by a nested-grid menu:

    -----------------------------------------------------------
    Choose horizontal grid domain:
    -----------------------------------------------------------
      1. Global
      2. Asia
      3. Europe
      4. North America
      5. Custom
    >>>
    

    Type the number of your preferred option and then hit ENTER.

  8. You will then be prompted for the vertical dimension of the grid.

    -----------------------------------------------------------
    Choose number of levels:
    -----------------------------------------------------------
      1. 72 (native)
      2. 47 (reduced)
    >>>
    

    For most simulations, you will want to use 72 levels. Type 1 followed by ENTER.

    For some memory-intensive simulations (such as nested-grid simulations), you can use 47 levels. Type 2 followed by ENTER.

  9. You will then be prompted for the folder in which you wish to create the run directory.

    -----------------------------------------------------------
    Enter path where the run directory will be created:
    -----------------------------------------------------------
    >>>
    

    You may enter an absolute path (e.g. $HOME/myusername/my-run-directories) followed by ENTER.

    You may also enter a relative path (e.g. ~/my-run-directories) followed by ENTER). In this case you will see that the ./createRunDir.sh script will expand the path to an absolute path.

  10. The next menu will prompt you for the run directory name.

    -----------------------------------------------------------
    Enter run directory name, or press return to use default:
    
    NOTE: This will be a subfolder of the path you entered above.
    -----------------------------------------------------------
    >>>
    

    You should use the default run directory name whenever possible. Type ENTER. The script will display the following output:

    -- Using default directory name gc_4x5_merra2_carbon
    

    or if you are creating a nested grid simulation:

    -- Using default directory name gc_05x0625_merra2_carbon
    

    and then

    -- See rundir_vars.txt for summary of default run directory settings
    -- This run directory has been set up to start on 20190101
    -- A restart file for this date has been copied to the Restarts subdirectory
    -- You may add more restart files using format GEOSChem.Restart.YYYYMMDD_HHmmz.nc4
    -- Change simulation start and end dates in configuration file geoschem_config.yml
    -- Default frequency and duration of diagnostics are set to monthly
    -- Modify diagnostic settings in HISTORY.rc and HEMCO_Config.rc
    


  11. The last menu will prompt you with:

    -----------------------------------------------------------
    Do you want to track run directory changes with git? (y/n)
    -----------------------------------------------------------
    >>>
    

    Type y and then ENTER. Then you will be able to track changes that you make to GEOS-Chem configuration files with Git. This can be a lifesaver when debugging—you can revert to an earlier state and then start fresh.

    You will then see output similar to this:

    Initialized empty Git repository in /path/to/gc_4x5_merra2_carbon/.git/
    
    Created /path/to/gc_4x5_merra2_carbon
    
    >>>> REMINDER: You must compile with options: -DMECH=carbon <<<<
    

    You can navigate to this directory and then start editing the GEOS-Chem configuration files.

    Because the carbon simulation requires special compilation instructions, a reminder will be displayed with the proper command to use during the configuration step.

The procedure to set up run directories for other GEOS-Chem Classic simulations is similar to that shown above.