Obtaining a GCHP Run Directory

Previous | Next | Getting Started With GCHP | GCHP Main Page

1. Hardware and Software Requirements
2. Downloading Source Code and Data Directories
3. Obtaining a Run Directory
4. Setting Up the GCHP Environment
5. Compiling
6. Running GCHP: Basics
7. Running GCHP: Configuration
8. Output Data
9. Developing GCHP
10. Run Configuration Files

Overview

Starting in version 12.1.0, GCHP no longer uses the Unit Tester to create run directories. Instead, create run directories directly from the GCHP source code repository. If you are uncertain about what version you have, please contact the GEOS-Chem Support Team. Please note that we always recommend upgrading to the latest version.

Step 1: Create Run Directory

Navigate to GCHP subdirectory Run/ and run shell script createRunDir.sh.

./createRunDir.sh

You can pass a run directory name as an optional argument if you wish, or you can set it interactively later on.

./createRunDir.sh gchp_standard_12.5.0

During the course of script execution you will be asked a series of questions:

External library paths

The very first time you create a run directory you will be prompted for (1) your ExtData path where you store GEOS-Chem shared data directories, and (2) your Goddard Fortran Template Library (gFTL) path where your gFTL repository is located. Both paths will be stored in file .geoschem/config in your home directory as environment variable GC_DATA_ROOT. If that file does not already exist it will be created for you.

Follow the prompts to enter the paths. The ExtData path should include the name of your ExtData directory. It is a good idea to have this ready prior to creating your first run directory. Make sure you do not include any symbolic links in the path. The gFTL path should also include the name of the gFTL directory. The interactive script will print out a list of instructions on downloading gFTL in case you have not already downloaded it.

Here is an example of what you will see when initially configuring external library paths:

~/GC/Code.gchp/GCHP/Run $ ./createRunDir.sh 

Define paths to ExtData and the Goddard Fortran Template Library (gFTL).
These will be stored in /n/home/user003/.geoschem/config for future automatic use.

Enter path for ExtData:
/n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/gcdata/ExtData (entered by user interactively)

If you have not downloaded gFTL then enter q to exit.
Follow these instructions at the command prompt to install:

     1. Navigate to directory where you want to download gFTL
     2. Type the following at the command prompt:
        $ git clone https://github.com/Goddard-Fortran-Ecosystem/gFTL
        $ cd gFTL
        $ git checkout v1.0.0
        $ cmake . -DCMAKE_INSTALL_PREFIX=.
        $ make install
     3. Verify success by checking that include/templates and include/types exist

Enter path for gFTL:
/n/home/user003/gFTL (entered by user interactively)

Below is an example of what the newly created file ${HOME}/.geoschem/config looks like. Beware that the file assumes bash and you will need to manually change how the environment variable is exported if you use a different shell. Functionality of ${HOME} is also assumed in the createRunDir.sh script.

export GC_DATA_ROOT=/n/holylfs/EXTERNAL_REPOS/GEOS-CHEM/gcgrid/gcdata/ExtData
export GFTL=/local/user003/gFTL

NOTE: Subsequent runs of createRunDir.sh will always source the .geoschem/config file to get your location for shared data directories and gFTL. You will not be prompted to enter them again. If the paths changes in the future you must provide the new paths in .geoschem/config. The run directory creation script will prompt you to do so only if the file is missing or if the paths within it are not valid.

Simulation type

You will next be prompted for what simulation you wish to create a run directory for.

Choose simulation type:
 1. TransportTracers
 2. Standard
 3. Benchmark

Enter the integer number next to the simulation type you want to use that is displayed on the screen. There are currently three options for GCHP simulations. If you would like to run additional simulation types with GCHP please contact the GCHP Working Group with why you think adding the additional simulation type should be a priority.

Meteorology source

Next, choose which meteorology source you would like to use.

Choose meteorology source:
 1. GEOS-FP
 2. MERRA2

Currently GCHP supports GEOS-FP and MERRA2 data only. Input data resolution is 0.25x0.325 for GEOS-FP and 0.5x0.625 for MERRA2 by default. Unlike GEOS-Chem Classic, GCHP input meteorology data does not need to be the same grid type or grid resolution as the grid and resolution you run at.

Storage location

Next, enter the target path where you want your run directory to be stored.

Enter path where the run directory will be created:

Do not include symbolic links in the path. Choose your path wisely to keep your runs organized.

Run directory name

You will then be prompted to enter a run directory name if you did not pass one as an optional argument when calling the script. You are given the option to simply press return and use the default run directory name of format gchp_{simulation_type}. Here is an example of what you will see if using the default name for the standard full chemistry simulation:

Enter run directory name, or press return to use default:


Using default directory name gchp_standard

If you are not storing your run directory at a path that indicates GEOS-Chem version, we recommend storing the version number directly in the run directory name to avoid later confusion. However, please note that you can always look up the run directory version within the run directory itself in file rundir.version if you have doubts about what GCHP version your run directory is compatible with.

Run directory version control

Finally, you will be asked if you want to track run directory changes with git version control. This feature is useful if you plan on making feature updates to GEOS-Chem that involve changes to the run directory, such as adding emissions or turning components on or off. With version control you can keep track of exactly what you changed relative to the original settings.

This is what you will see if you use to put your run directory under version control with git:

Do you want to track run directory changes with git? (y/n)
y
Initialized empty Git repository in /n/home/use003/gchp_standard/.git/

We strongly recommend using this feature if you plan on submitting an update for inclusion in the standard model since you can copy changes directly from your version history to GCHP/Run, and then commit those changes with your source code updates. If you forked the repository you can then push to your fork and do a pull request to send us your updates.

Step 2: Set Environment File Symbolic Link

Once you have created a run directory you need to set the gchp.env symbolic link to your GCHP environment file. This file will be sourced automatically every time you compile using the Makefile and every time you run using one of the provided run scripts (more on this later in the manual). If you write your own run script, be sure to include source gchp.env to use the same environment that you compiled with.

To set the gchp.env symbolic link execute shell script setEnvironment and pass the path to your environment file. You can keep your environment file anywhere on your system; it does not need to be stored in the run directory.

./setEnvironment /home/gchp/envs/gchp_ifort17_openmpi.env

Several examples of GCHP environment files are provided in subdirectory environmentFileSamples. For more information on developing a working environment file for GCHP see the next chapter in this online manual.

---

Previous | Next | Getting Started With GCHP | GCHP Main Page