Skip to content

HERMES_GR_ShortExamples

Jump to bottom
Carles Tena edited this page Jul 15, 2026 · 1 revision

HERMES_GR Short Examples

This section of the wiki describes how to execute HERMES_GR using a reproducible benchmark and how to validate the generated output.

Table of contents

Benchmark scenario

This benchmark aims to test and validate the main functionalities of the HERMES_GR software.

The scenario reproduces the generation of 24 hourly emission outputs for a MONARCH rotated domain, with a horizontal resolution of 0.2 degrees in rotated coordinates and 5 vertical layers, starting on November 29, 2022.

The benchmark uses a compact set of input emission data, configuration files, vertical profiles, temporal profiles, speciation profiles, and geospatial support files. It is intended to verify that HERMES_GR can:

  • Read and combine emission inventory data.
  • Apply temporal, vertical, and chemical speciation profiles.
  • Apply the selected domain configuration.
  • Generate model-ready NetCDF output.
  • Reuse auxiliary files between equivalent runs.

Pre-requirements

It is assumed that HERMES_GR has been properly installed before running this benchmark.

Please refer to the installation guide available in the wiki:

That page also describes how to verify the installation by querying the HERMES_GR version and the CLI help.

Download benchmark

The benchmark dataset is distributed through the BSC Dataverse repository:

To download the benchmark dataset:

  1. Open the link above.
  2. Download the compressed benchmark file.
  3. Extract its contents to a stable working directory, for example:
/path/to/HERMES_GR_Benchmark

Keep the benchmark directory in a stable location. Running the benchmark only requires updating four paths in the configuration file or passing them through command-line arguments.

Benchmark data description

Once the benchmark has been downloaded and extracted, the directory structure should contain the following main folders:

HERMES_GR_Benchmark/
|-- data_path
|   |-- emission_inventories
|   `-- shapefiles
|       |-- gadm_country_mask.geojson
|       `-- timezones_2021c.geojson
|-- input_dir
|   |-- conf
|   |   |-- EI_benchmark.csv
|   |   `-- HERMES_GR_benchmark.ini
|   `-- profiles
|       |-- speciation
|       |   |-- MolecularWeights.csv
|       |   `-- Speciation_profile_benchmark.csv
|       |-- temporal
|       |   |-- TemporalProfile_Daily.csv
|       |   |-- TemporalProfile_Hourly.csv
|       |   |-- TemporalProfile_Monthly.csv
|       |   `-- TemporalProfile_Weekly.csv
|       `-- vertical
|           |-- benchmark_5layers_vertical_description.csv
|           `-- Vertical_profile.csv
`-- output
    `-- HERMES_GR_Benchmark_2022112900.nc

As shown above, the downloaded data are organized into three main directories:

  • data_path: location of emission inventory data and geospatial support files required by HERMES_GR.
  • input_dir: location of configuration files and text-based inputs required to run the benchmark.
    • conf: main HERMES_GR .ini file and emission inventory cross table.
    • profiles: temporal, vertical, speciation, and molecular weight profile definitions.
  • output: reference NetCDF output included with the benchmark, used for validation.

Configuration

Once the benchmark has been downloaded, the .ini configuration file must be reviewed before execution:

HERMES_GR_Benchmark/input_dir/conf/HERMES_GR_benchmark.ini

The benchmark configuration already includes the simulation options. Only the path-dependent parameters must be adapted to your local machine:

Parameter Description Data type Required
input_dir Path to the benchmark input_dir directory. str Yes
data_path Path to the benchmark data_path directory. str Yes
output_dir Path to the directory where HERMES_GR will write the generated output. str Yes
auxiliary_files_path Path to the directory where auxiliary files will be generated or reused. str Yes

In the configuration file, these parameters appear at the beginning of the [GENERAL] section with the following placeholder values:

# input_dir = /path/to/the/downloaded/benchmark/input_dir
# data_path = /path/to/the/downloaded/benchmark/data_path
# output_dir = /path/to/the/output/directory/for/HERMES_GR/<version>/Benchmark
# auxiliary_files_path = /path/to/create/or/read/the/auxiliary/files/HERMES_GR_Benchmark_<domain_type>_<resolution>

You can either uncomment and edit these values in the .ini file, or keep them commented and pass them through command-line arguments when running HERMES_GR.

  • input_dir: path to the input_dir directory of the benchmark.
  • data_path: path to the data_path directory of the benchmark.
  • output_dir: path to a new or empty directory with write permissions. Do not overwrite the reference output included in the benchmark.
  • auxiliary_files_path: path to the directory where auxiliary files will be generated or reused.

Auxiliary files depend on the domain definition and input geospatial data, but do not change in time. Therefore, they can be reused across simulations as long as the domain and input data remain unchanged.

Execution

To run HERMES_GR, use the Command Line Interface (CLI) hermes_gr followed by the --my-config option pointing to the benchmark .ini file.

If the four path-dependent parameters were edited directly in the .ini file:

hermes_gr --my-config /path/to/HERMES_GR_Benchmark/input_dir/conf/HERMES_GR_benchmark.ini

Alternatively, keep the four parameters commented in the .ini file and pass them as command-line arguments:

BENCHMARK_PATH="/path/to/HERMES_GR_Benchmark"

CONFIG="${BENCHMARK_PATH}/input_dir/conf/HERMES_GR_benchmark.ini"
DATA_PATH="${BENCHMARK_PATH}/data_path"
INPUT_DIR="${BENCHMARK_PATH}/input_dir"
AUX_PATH="/path/to/HERMES_GR_AUX/v3.0.0/Benchmark"
OUT_DIR="/path/to/HERMES_GR_OUT/v3.0.0/Benchmark"

hermes_gr --my-config "${CONFIG}" --input_dir "${INPUT_DIR}" --data_path "${DATA_PATH}" --auxiliary_files_path "${AUX_PATH}" --output_dir "${OUT_DIR}"

For a parallel run, use mpirun specifying the number of processes:

mpirun -np 16 hermes_gr --my-config "${CONFIG}" --input_dir "${INPUT_DIR}" --data_path "${DATA_PATH}" --auxiliary_files_path "${AUX_PATH}" --output_dir "${OUT_DIR}"

The first execution can take longer because HERMES_GR has to create the auxiliary files. Once created, those files can be reused in future simulations with the same domain and input data.

Validation

Once the execution has finished, compare the generated NetCDF output with the reference file provided in the benchmark output directory:

HERMES_GR_Benchmark/output/HERMES_GR_Benchmark_2022112900.nc

Any standard NetCDF inspection or comparison tool can be used to verify that the results are consistent with the reference output, for example:

  • ncdump
  • ncdiff
  • cdo
  • nco

The generated file name follows the output_name pattern configured in the benchmark .ini file:

output_name = HERMES_GR_Benchmark_<date>.nc

Clone this wiki locally