©2025 ETH Zurich
This project is under active development. The goal is to provide an orchestration and scheduling platform for earthquake forecast models.
For v0 of the project, see the gitlab repository
This project does not distribute any earthquake forecast models. It is merely a framework to run and schedule earthquake forecast models. The models need to be installed separately. Please look at the hermes-model repository for more information on how to install and use a model with HERMES.
This installation instruction is merely a recommendation for a user of the software. Depending on your preferences and knowledge, you are free to choose a different setup.
To use the software, you need to have a correctly configured Prefect Server installation as well as a PostgreSQL database. You can install them using Docker Compose as described in section 2.1. If there is already such an installation provided, you can skip to section 2.2.
Follow the instructions here
First you need to clone the repository. This will create a folder called rt-hermes in your current directory.
git clone https://github.com/swiss-seismological-service/rt-hermes.git
cd rt-hermes
The .env file is used to configure the Prefect Server and the PostgreSQL database. It contains sensitive information such as passwords and connection strings. You can create a copy of the example file with the following command:
cp .env.example .env
As a quick test setup, the configuration works as is, but is not secure. Please change the credentials, ports and connection strings in the .env file.
You can now create the Docker services for the Prefect Server and the PostgreSQL database using the following commands:
docker compose -f compose-prefect.yaml up -d
docker compose --env-file .env -f compose-database.yaml up -d
You can now access the Prefect Server at http://localhost:4200 and the webservice at http://localhost:8000/docs.
If you already followed Section 2.1, you can create a new folder next to the cloned rt-hermes repository to create your project.
If you have a Service installation provided, but would like to use the examples provided in the repository, you can still clone the repository to get the examples and the template env file:
git clone https://github.com/swiss-seismological-service/rt-hermes.git
It is strongly recommended to use a virtual environment. This will ensure that the dependencies are isolated from your system Python installation.
mkdir hermes-project && cd hermes-project
python3 -m venv env # python3.12 is required
source env/bin/activate
pip install -U pip wheel setuptools
Install Hermes from the Python Package Index
pip install rt-hermes
For HERMES to find the correct Prefect Server and PostgreSQL database, you need to create a .env file in the root of your project. You can use the example file provided in the repository:
# Assuming you have cloned the repository into the current directorys parent
cp ../rt-hermes/.env.example .env
Use the credentials defined in section 2.1 or the ones provided to you by your admin.
The main usage of HERMES is currently via CLI
To run models, you need to have them installed locally. You can, for example, clone them into a subdirectory and install from there.
git clone https://gitlab.seismo.ethz.ch/indu/em1.git models/em1
git clone https://github.com/swiss-seismological-service/etas.git models/etas
pip install -e models/em1
pip install -e models/etas
The models can be run using the CLI.
You can start with an example configuration and data to get a feel for how HERMES works. The example configuration is located in the examples/induced folder. You can copy it to your project directory using the following command, assuming again you have the repository cloned in the parent directory:
cp -r ../rt-hermes/examples .
Update the absolute path fdsnws_url in the examples/induced/forecastseries.json file to the path of the examples/induced folder.
hermes db init
This only needs to be done once. In case you want to delete all data and start from scratch, you can run hermes db purge and then hermes db init again.
hermes projects create project_induced --config examples/induced/project.json
hermes forecastseries create fs_induced --config examples/induced/forecastseries.json --project project_induced
hermes injectionplans create default --forecastseries fs_induced --file examples/induced/multiply_template.json
hermes models create em1 --config examples/induced/model_config.json
The CLI can be used to interact with the HERMES service. For a list of available commands, run hermes --help. Most commands have a --help option to show the available options.
Most setting should be self-explanatory, but more information can be found in the concepts documentation.
A more detailed of the InjectionPlan configuration can be found here.
hermes forecasts run fs_induced --start 2022-04-21T15:00:00 --end 2022-04-21T18:00:00 --local
This starts a single forecast directly on the local machine.
To use advanced features like scheduling, it is necessary to start a process which "serves" the forecastseries.
hermes forecastseries serve fs_induced
Depending on your model, you need to control how many modelruns are executed in parallel, you can do that by specifying the --concurrency-limit option which is by default set to 3. Please consider, that also the requesting of the input data can become a limiting factor if you are requesting a lot of data at the same time (eg. requests to an FDSNWS).
hermes forecastseries serve fs_induced --concurrency-limit 1
Once this process is running, you can "send" a forecast to the service using the above command without the --local flag.
hermes forecasts run fs_induced --start 2022-04-21T15:00:00 --end 2022-04-21T18:00:00
This will again execute a single forecast, but this time it will be executed by the service. This now allows us to create a schedule for the forecastseries, which will automatically execute forecasts at the specified times. More information about the schedule settings can be found here.
hermes schedules create fs_induced --config examples/induced/schedule_replay.json
This schedule specifies forecasts in the past. Accordingly, no future forecasts will be executed, but the catchup command can be used to execute all forecasts as a "replay".
hermes schedules catchup fs_induced
Note that a schedule can either lie in the past, the future, or both. The catchup command will only execute forecasts in the past, while the service will automatically execute forecasts in the future.
To view the forecasts and modelruns, currently only the webservice is available. The available endpoints are listed in the API documentation: http://localhost:8000/docs.
A quick description of the way to traverse the API is as follows:
To view the Projects, you can navigate to the following URL: http://localhost:8000/v1/projects. Copy the oid of the project you'd like to access.
To find the correct Forecastseries, you can navigate to the following URL: http://localhost:8000/v1/projects/<project_oid>/forecastseries. Again, copy the oid of the ForecastSeries.
To view the Forecasts and ModelRuns, you can navigate to the following URL: http://localhost:8000/v1/forecastseries/<forecastseries_oid>/forecasts.
Once you have the oid of the models, you can use that to more easily debug the models. You can download the exact configuration and input files the modelrun used. Navigate to the following URL: http://localhost:8000/v1/modelruns/<modelrun_oid>/input to download the input files.
The results of the modelruns can be directly downloaded from the webservice. This API is still under development and will be improved in the future. The results can be downloaded from the following URL: http://localhost:8000/v1/modelruns/<modelrun_oid>/results.
A Python client library is provided for easier access to the RT-HERMES data and results. It can be installed using pip:
pip install hermes-clientA documentation is available here
Inside the cloned repository folder, update the prefect docker containers:
docker compose -f compose-prefect.yaml up -d
prefect server database upgrade -yNext you can update the hermes database and webservice:
docker compose -f compose-database.yaml up -d
hermes db upgradeIf you want to update the library, you can do so by running the following command inside your virtual environment:
pip install -U rt-hermesIf you need to update the hermes database too (if your admin has not done that already), you can run the following command:
hermes db upgradeIf you want to update the services and would like a clean install or/and don't care about the existing data, you can do so by completely removing the existing containers and volumes, pulling the latest changes, and then starting the services again.
docker compose -f src/hermes/compose-prefect.yaml down -v
docker compose -f src/hermes/compose-prefect.yaml pull
docker compose -f src/hermes/compose-prefect.yaml up -dNext you can update the hermes database and webservice:
docker compose -f src/hermes/compose-database.yaml down -v
docker compose -f src/hermes/compose-database.yaml pull
docker compose --env-file .env -f src/hermes/compose-database.yaml up -d