Skip to content

HERMES_GR_Installation

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

HERMES_GR Installation Guide

This guide explains how to install HERMES_GR using the recommended Conda/Mamba workflow with the project Makefile, and also summarizes the dependencies needed for advanced manual installations.

The recommended installation method creates a complete Conda environment from environment.yml, installs the NES submodule, installs HERMES_GR, configures activation scripts, and runs the basic import and lint tests.

Table of contents

0. Requirements

Before installing HERMES_GR, make sure the following tools are available:

  • Git, to clone the repository and its submodules.
  • Mamba or Conda, to create and manage the environment.

Mamba is recommended because it usually resolves the environment faster. Conda can also be used through the fallback targets described below.

1. Clone the repository

Clone the HERMES_GR repository with its submodules:

git clone --recurse-submodules https://github.com/BSC-ES/HERMES_GR.git HERMES_GR
cd HERMES_GR

The --recurse-submodules option ensures that all required submodules, including NES, are cloned together with the main repository.

If you already cloned the repository without submodules, initialize them with:

git submodule update --init --recursive

2. Recommended installation with Makefile

The repository includes a Makefile that automates the complete installation.

2.1. User installation

To perform a standard installation using Mamba:

make full_installation

By default, this target:

  • Creates a Conda environment in ./HERMES_GR_vX.Y.Z.
  • Uses environment.yml as the source of the Conda dependencies.
  • Adds the required activation scripts.
  • Installs the NES submodule.
  • Installs HERMES_GR.
  • Runs the basic installation tests.

You can change the parent directory where the environment will be created with CONDA_ENV_DIR:

make full_installation CONDA_ENV_DIR=/my/custom/path

This creates the environment in:

/my/custom/path/HERMES_GR_vX.Y.Z

After installation, activate the environment with:

conda activate /my/custom/path/HERMES_GR_vX.Y.Z

If CONDA_ENV_DIR is not provided, activate the default local environment with:

conda activate ./HERMES_GR_vX.Y.Z

2.2. Developer installation

For development work, use the editable installation target:

make full_installation_for_dev

This target creates the environment in:

./HERMES_GR_<your-username>

and installs both NES and HERMES_GR in editable mode.

You can also choose a custom parent directory:

make full_installation_for_dev CONDA_ENV_DIR=/my/dev/path

This creates the development environment in:

/my/dev/path/HERMES_GR_<your-username>

2.3. Conda fallback

If Mamba is not available, use the Conda-based targets:

make full_conda_installation

For a developer installation with Conda:

make full_installation_for_dev_conda

The same CONDA_ENV_DIR argument can be used with these targets.

3. Verify the installation

After installation, activate the environment and check that the command-line tools are available.

Check the HERMES_GR version:

hermes_gr -V

Display the main command help:

hermes_gr -h

Display the preprocessing command help:

hermes_gr_preproc -h

The installation target also runs the project import and lint tests through the Makefile.

4. Dependencies

The authoritative dependency file for the recommended installation is environment.yml.

The current HERMES_GR environment is based on:

  • Python 3.10
  • MPI-enabled libnetcdf, netCDF4, and h5py
  • mpi4py
  • numpy, geopandas, shapely, pyproj, rtree, rasterio, and gdal
  • eccodes and python-eccodes
  • configargparse, pyyaml, openpyxl, holidays, pytz, filelock, psutil, and numba
  • pytest, pytest-cov, and pycodestyle for testing and style checks
  • jupyter and ipykernel for interactive workflows
  • argcomplete, installed through pip

The requirements.txt file provides a pip-oriented dependency list, while setup.py defines the Python package metadata, install requirements, package data, and console entry points.

The installed console commands are:

  • hermes_gr
  • hermes_gr_preproc
  • hermes_sum

5. Advanced manual installation

Manual installation is only recommended for advanced users who need to adapt HERMES_GR to a custom system or HPC environment.

At minimum, the environment must provide:

  • Python 3.10
  • A working MPI stack with mpicc and mpicxx
  • MPI-enabled NetCDF/HDF5 libraries
  • The Python packages listed in environment.yml or requirements.txt

After creating and activating a suitable environment, install NES and HERMES_GR with pip:

python -m pip install hermes_gr/sources/NES
python -m pip install .

For development mode:

python -m pip install -e hermes_gr/sources/NES
python -m pip install -e .

Avoid using python setup.py install for new installations. The pip install . workflow is the recommended Python packaging interface.

Clone this wiki locally