Obtaining a GCHP Run Directory

From Geos-chem
Revision as of 15:26, 26 April 2019 by Lizzie Lundgren (Talk | contribs) (Step 1: Create Run Directory)

Jump to: navigation, search

Previous | Next | User Manual Home | GCHP Home

  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


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

Run directories are created directly from the GCHP source code repository starting in version 12.1.0. Navigate to GCHP subdirectory Run/ and run shell script createRunDir.sh.


You can pass a run directory name as an optional argument if you wish.

./createRunDir.sh gchp_12.1.0_RnPbBe

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

  1. The very first time you create a run directory you will be prompted for your ExtData path where you store GEOS-Chem shared data directories. The ExtData path should include the name of your ExtData directory. For example, it may be something like this: /n/lfs/gcgrid/gcdata/ExtData. 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. Once entered, it 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.
  2. Subsequent runs of createRunDir.sh will always source that file to get your location for shared data directories and you will not be prompted again. If your ExtData path changes in the future you must provide the new path in .geoschem/config. The run directory creation script will prompt you to do so only if the file is missing or if the path within it is not valid.
  3. You will next be prompted for what simulation you wish to create a run directory for. Enter the integer number next to the simulation type you want to use that is displayed on the screen.
  4. Following simulation type, enter the meteorology you want to use in the same way. Options for GEOS-FP and MERRA2 will be displayed.
  5. Next, enter the target path where you want your run directory to be stored. Do not include symbolic links in the path.
  6. 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}. 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.
  7. 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. With version control you can keep track of exactly what you changed relative to the original settings. This is also useful 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 in the same clone as 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. 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.

Step 3: Copy Run Script to Run Directory (Optional)

Run scripts are what you submit to your compute cluster to execute your GCHP run. It is not required since you sometimes can run interactively using the same resources used for your command line tasks. However, we recommend submitting GCHP runs as jobs. Several examples of GCHP run scripts, mostly for SLURM, are provided in subdirectory runScriptSamples. All example run scripts include source gchp.env. If you customize your own run script make sure you include this before use.

Previous | Next | User Manual Home | GCHP Home