Create a run directory
Note
Another useful resource for HEMCO standalone run directory creation instructions is our YouTube tutorial.
HEMCO standalone run directories are created from within the source code.
A new run directory should be created for each different version of
HEMCO you use. Git version information is logged to file
rundir.version within the run directory upon creation.
To create a run directory, navigate to the run/ subdirectory
of the source code and execute shell script createRunDir.sh.
$ cd HEMCO/run
$ ./createRunDir.sh
During the course of script execution you will be asked a series of questions:
Enter ExtData path
The first time you create a HEMCO standalone run directory on your
system you will be prompted for a path to the ExtData folder,
which is the root data directory for HEMCO (as well as for GEOS-Chem).
The path that you specify should include the name of your
ExtData/ directory and should not contain symbolic links. The
path you enter 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. When
creating additional run directories you will only be prompted again if
the file is missing or if the path within it is not valid.
-----------------------------------------------------------
Enter path for ExtData:
-----------------------------------------------------------
Choose meteorology source
Enter the integer number that is next to the input meteorology source you would like to use.
===========================================================
HEMCO STANDALONE RUN DIRECTORY CREATION
===========================================================
-----------------------------------------------------------
Choose meteorology source:
-----------------------------------------------------------
1. MERRA-2 (Recommended)
2. GEOS-FP
3. GISS ModelE2.1 (GCAP 2.0)
Choose horizontal resolution
Enter the integer number that is next to the horizontal resolution you would like to use.
-----------------------------------------------------------
Choose horizontal resolution:
-----------------------------------------------------------
1. 4.0 x 5.0
2. 2.0 x 2.5
3. 0.5 x 0.625
4. 0.25 x 0.3125
5. Custom
Enter HEMCO_Config.rc path
Provide the path to a HEMCO_Config.rc file with your emissions
settings.
-----------------------------------------------------------
Enter the file path to a HEMCO_Config.rc with your
emissions settings.
- This should be a HEMCO_Config.rc file from a
pre-generated GEOS-Chem run directory and not a
template config file from the GEOS-Chem repository.
- If you do not have a pre-generated HEMCO_Config.rc file,
type ./HEMCO_Config.rc.sample at the prompt below.
This will copy a sample configuration file into your
run directory. You can then edit this configuration
file with your preferred emission settings.
-----------------------------------------------------------
If you have a pre-configured HEMCO_Config.rc file available
(e.g. from a GEOS_Chem run
directory), then then type the absolute path:
/path/to/my/HEMCO_Config.rc
If you do not have a HEMCO_Config.rc template file handy, then
type:
./HEMCO_Config.rc.sample
This will copy sample HEMCO_Config.rc and
HEMCO_Diagn.rc files to the run directory. You can edit these
configuration files to include your preferred emission settings.
Refer to the HEMCO Reference Guide for more information about how to edit the HEMCO configuration file.
Enter run directory path
Enter the target path where the run directory will be stored. You will be prompted to enter a new path if the one you enter does not exist.
-----------------------------------------------------------
Enter path where the run directory will be created:
-----------------------------------------------------------
Enter run directory name
Enter the run directory name, or accept the default. You will be prompted for a new name if a run directory of the same name already exists at the target path.
-----------------------------------------------------------
Enter run directory name, or press return to use default:
NOTE: This will be a subfolder of the path you entered above.
-----------------------------------------------------------
If you press return, a default name such as hemco_4x5_merra2,
hemco_2x25_geosfp, etc. will be used.
Enable version control (optional)
Enter whether you would like your run directory tracked with Git version control. With version control you can keep track of exactly what you changed relative to the original settings. This is useful for trouble-shooting as well as tracking run directory feature changes you wish to migrate back to a previous version.
-----------------------------------------------------------
Do you want to track run directory changes with git? (y/n)
-----------------------------------------------------------
If a run directory has successfully been created, the name of the run directory will be printed. If you used the default run directory name then you will see output similar to:
Created /path/to/hemco_4x5_merra2
etc.
Run directory contents
Navigate to the run directory that was just created and get a directory listing:
$ cd hemco_4x5_merra2
$ ls
build/ HEMCO_Config.rc HEMCO_sa_Config.rc HEMCO_sa_Spec.rc OutputDir/ rundir.version
CodeDir@ HEMCO_Diagn.rc HEMCO_sa_Grid.4x5.rc HEMCO_sa_Time.rc README runHEMCO.sh*
build is the folder is where you will compile HEMCO
standalone.
CodeDir is a symbolic link back to the HEMCO source code.
OutputDir is the folder where diagnostic outputs will be generated.
Files ending in .rc are user-edtiable configuration files
that control HEMCO standalone simulation options. We will discuss
these in more detail more in the Configure a simulation chapter.
The rundir.version file contains information about the Git
commit in the HEMCO source code corresponding to this run directory.
You will see output similar to this:
This run directory was created with /path/to/hemco/HEMCO/run/createRunDir.sh.
HEMCO repository version information:
Remote URL: git@github.com:geoschem/hemco.git
Branch: dev
Commit: Add fixes for generating HEMCO standalone run directory
Date: Wed Jul 13 10:56:36 2022 -0400
User: Melissa Sulprizio
Hash: b29dac4
Changes to the following run directory files are tracked by git:
[master (root-commit) b8e694d] Initial run directory
7 files changed, 477 insertions(+)
create mode 100644 HEMCO_Config.rc
create mode 100644 HEMCO_Diagn.rc
create mode 100644 HEMCO_sa_Config.rc
create mode 100644 HEMCO_sa_Grid.4x5.rc
create mode 100644 HEMCO_sa_Spec.rc