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:
Navigate to your build directory.
Update your build settings with cmake. See
Recompile with make -j. Note that the build system automatically figures out what (if any) files need to be recompiled.
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.