Quick Start

This quickstart guide assumes your environment satisfies HEMCO’s requirements. This means you should load a compute environment such that programs like cmake and mpirun are available, before continuing. You can find more detailed instructions in the user guide.

1. Clone HEMCO

Download the source code:

$ git clone https://github.com/geoschem/HEMCO.git ~/HEMCO
$ cd ~/HEMCO

Checkout the HEMCO version that you want to use:

$ git checkout 3.0.0-rc.0

2. Create a run directory

Navigate to the run/ subdirectory. Create a run directory by running ./createRunDir.sh and answering the prompts:

$ cd run/
$ ./createRunDir.sh

3. Configure your build

Create a build directory and cd into it. A good name for this directory is build/, and a good place for it is in the top-level of the source code:

$ mkdir ~/HEMCO/build
$ cd ~/HEMCO/build

Initialize your build directory by running cmake and passing it the path to your source code:

$ cmake ~/HEMCO

Now you can configure build options. These are persistent settings that are saved to your build directory. A common build option is -DRUNDIR. This option lets you specify one or more run directories that HEMCO is “installed” to when you do make install. Configure your build so it installs HEMCO to the run directory you created in Step 2:

$ cmake . -DRUNDIR="/path/to/rundir"

Note

The . in the cmake command above is important. It tells CMake that your current working directory (i.e., .) is your build directory.

4. Compile and install

Compile HEMCO:

$ make -j

Next, install the compiled executable to your run directory (or directories):

$ make install

This copies build/bin/hemco_standalone and supplemental files to your run directory.

Note

You can update build settings at any time:

  1. Navigate to your build directory.

  2. Update your build settings with cmake. See

  3. Recompile with make -j. Note that the build system automatically figures out what (if any) files need to be recompiled.

  4. Install the rebuilt executable with make install.

5. Configure your run directory

Now, navigate to your run directory:

$ cd path/to/rundir

Simulation settings are configured in the .rc files. The main configuration file is HEMCO_sa_Config.rc. The start end end time for your simulation can be modified in HEMCO_sa_Time.rc. The horizontal grid for your simulation can be modified in HEMCO_sa_Grid.rc. Emissions settings can be changed in the HEMCO_Config.rc file that has been copied from another model (e.g. GEOS-Chem).

6. Run HEMCO

HEMCO can be run interactively from within your run directory by typing:

$ ./hemco_standalone

You may also submit your HEMCO simulation as a batch job to a scheduler. A sample run script runHEMCO.sh is included in your run directory. To submit a HEMCO simulation using SLURM:

$ sbatch runHEMCO.sh

Those are the basics of using HEMCO! See the user guide, step-by-step guides, and reference pages for more detailed instructions.