Metadata-Version: 2.4
Name: holmes-hydro
Version: 4.1.0
Summary: HOLMES (HydrOLogical Modeling Educationnal Software) is a software developped to teach operational hydrology. It is developed at the university Laval, Québec, Canada.
Project-URL: Homepage, https://github.com/antoinelb/holmes
Project-URL: Repository, https://github.com/antoinelb/holmes
Author-email: Antoine Lefebvre-Brossard <antoinelb@proton.me>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.12
Requires-Dist: altair>=6.2.2
Requires-Dist: cdsapi>=0.7.7
Requires-Dist: exactextract>=0.3.0
Requires-Dist: gcsfs>=2026.7.0
Requires-Dist: geopandas>=1.1.3
Requires-Dist: geopolars>=0.1.0a4
Requires-Dist: holmes-rs>=0.7.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: netcdf4>=1.7.4
Requires-Dist: numpy>=2.4.6
Requires-Dist: polars>=1.41.0
Requires-Dist: pystac-client>=0.9.0
Requires-Dist: rioxarray>=0.22.0
Requires-Dist: starlette>=1.0.0
Requires-Dist: tqdm>=4.68.2
Requires-Dist: typer>=0.26.3
Requires-Dist: uvicorn>=0.47.0
Requires-Dist: vl-convert-python>=1.9.0.post1
Requires-Dist: websockets>=16.0
Requires-Dist: xarray>=2026.4.0
Requires-Dist: zarr>=3.2.1
Description-Content-Type: text/markdown

# HOLMES

[![ci holmes](https://github.com/antoinelb/holmes/workflows/ci%20holmes/badge.svg)](https://github.com/antoinelb/holmes/actions)
[![ci holmes-rs](https://github.com/antoinelb/holmes/workflows/ci%20holmes-rs/badge.svg)](https://github.com/antoinelb/holmes/actions)
![holmes-hydro pypi version](https://img.shields.io/pypi/v/holmes-hydro?label=holmes-hydro%20pypi%20package&color=green)
![holmes-rs pypi version](https://img.shields.io/pypi/v/holmes-rs?label=holmes-rs%20pypi%20package&color=green)
[![Supported Python Version](https://img.shields.io/pypi/pyversions/holmes-hydro.svg?color=%2334D058)](https://pypi.org/project/holmes-hydro)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://antoinelb.github.io/holmes/)

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

📖 **[Documentation](https://antoinelb.github.io/holmes/)** · 📦 **[PyPI](https://pypi.org/project/holmes-hydro/)**

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](src/holmes-rs), a Rust extension.

## Usage

### Installation

```bash
pip install holmes-hydro
```

### Running HOLMES

After installation, start the dashboard with:

```bash
holmes run
```

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

Other commands:

```bash
holmes download     # rebuild the published datasets from their true sources
holmes experiment   # run batch calibration experiments
```

Station, weather, and projection data are fetched from their true sources at runtime and cached under `data/`; prebuilt products are served from the repo so a fresh install works without any credentials.

### Configuration

Customize the server by creating a `.env` file:

```env
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)
```

## Development

### Setup

1. Install [uv](https://docs.astral.sh/uv/):
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. Clone and install in development mode:
   ```bash
   git clone https://github.com/antoinelb/holmes.git
   cd holmes
   uv sync
   ```

### Running

```bash
uv run holmes run
```

Or activate the virtual environment and run directly:

```bash
source .venv/bin/activate
holmes run
```

### Code Quality

```bash
make static-analysis
```

### Tests

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

## References

- [HOOPLA](https://github.com/ulaval-rs/HOOPLApy/tree/main/hoopla/models/hydro)
