HOLMES

HOLMES (HydrOLogical Modeling Educational Software) is a software developed to teach operational hydrology. It is developed at Université Laval, Québec, Canada.

📖 Documentation · 📦 PyPI

The dashboard guides students through a modeling pipeline — stations → weather → model → calibration → simulation → projection — starting from an interactive map of hydrometric stations. The backend is Starlette, the frontend is vanilla JavaScript with an Elm architecture (d3 and Leaflet), and communication is mostly over WebSocket. All numerical computation runs in holmes-rs, a Rust extension.

Usage

Installation

pip install holmes-hydro

Running HOLMES

After installation, start the dashboard with:

holmes run

The web interface will be available at http://127.0.0.1:8000.

Other commands:

holmes experiment   # run batch calibration experiments
holmes download     # maintainers: build every data product from its true source
holmes package      # maintainers: zip the built products into data-YYYY-MM-DD.zip

Data

The server never builds data. At startup it compares the newest data-YYYY-MM-DD.zip asset on the repo's rolling data release against its local copy, and downloads and extracts the archive if it is newer — old data keeps being served during the swap, and no credentials are ever needed to run the app. Data lives in the per-user data directory (~/.local/share/holmes on Linux, ~/Library/Application Support/holmes on macOS, %LOCALAPPDATA%\holmes\holmes on Windows), overridable with HOLMES_DATA_DIR; map tiles are the one exception, still fetched lazily from CartoDB.

Rebuilding the archive is the maintainer path. holmes download builds every product incrementally from its true source: daily re-runs only fetch the current year (plus the previous year in January) for ERA5 and the ministry grid, always refresh the small streamflow files, recompute the cheap derived products, and skip the static ones (station data, projections). It needs the download extra (pip install 'holmes-hydro[download]', which carries the heavy geo dependencies) and, on a cold ERA5 cell cache, CDS credentials in ~/.cdsapirc or the CDSAPI_URL/CDSAPI_KEY environment variables. holmes package then zips the built products into the dated archive. A nightly GitHub Actions workflow (.github/workflows/data.yml, 07:00 UTC) runs both and replaces the dated zip on the data release; it is toggled with the DATA_REFRESH_ENABLED repository variable (Settings → Actions → Variables) and can always be run manually via workflow dispatch.

Configuration

Customize the server by creating a .env file:

DEBUG=True                  # Enable debug mode (default: False)
RELOAD=True                 # Enable auto-reload on code changes (default: False)
HOST=127.0.0.1              # Server host (default: 127.0.0.1)
PORT=8000                   # Server port (default: 8000)
HOLMES_DATA_DIR=data        # Data directory (default: the per-user data
                            # directory, e.g. ~/.local/share/holmes on Linux)
HOLMES_SKIP_DATA_SYNC=True  # Skip the startup data sync (default: False)

A repo checkout should set HOLMES_DATA_DIR=data to keep using the repo-local data/ directory.

Development

Setup

1. Install uv:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Clone and install in development mode:

   git clone https://github.com/antoinelb/holmes.git
   cd holmes
   uv sync
   

Running

uv run holmes run

Or activate the virtual environment and run directly:

source .venv/bin/activate
holmes run

Code Quality

make static-analysis

Tests

make test       # unit + integration (100% coverage) and the Rust suites
make test-e2e   # Playwright end-to-end tests

References

• HOOPLA