hydromodpy 2.0.0a3

HydroModPy is a Python toolbox for deploying catchment-scale shallow groundwater models. One TOML config drives MODFLOW 6, MODFLOW-NWT, Boussinesq and GR4J on the same hydrology, with reproducible inputs and ML-friendly outputs.

What you get

• One config, four solvers. A single HydroModPyConfig (Pydantic v2) drives MODFLOW 6, MODFLOW-NWT, Boussinesq and GR4J on the same catchment.
• Disk is the truth. Every run is one plain directory under runs/, named after the run. The DuckDB file in .hmp/ is only an index over those directories: delete it and hmp catalog reindex rebuilds it.
• Standard formats, no container. Field arrays in Zarr, tables in Parquet, the frozen config in TOML, the seal and the provenance in JSON. pandas, xarray and zarr read a run without HydroModPy installed.
• Reproducibility. A frozen hydromodpy.lock pins the input data, and each run stores its own provenance.json: Python version, package versions, git commit, host, solver binary and its SHA-256.

Install

pip install --pre hydromodpy

The current main documentation targets the v2 alpha line. Use pip install hydromodpy only when you want the latest stable release.

2.0.0a1 misses whitebox-workflows in its dependencies, and build_geographic fails without it. On that release, add it by hand:

pip install whitebox-workflows==1.3.5

Optional extras: [ide], [test], [viewer3d], [docs]. Solver binaries (MODFLOW 6, MODFLOW-NWT, MODPATH, MT3D-USGS) are downloaded on demand into ~/.cache/hydromodpy/bin/ on first solver run, or eagerly with hmp install-binaries.

For developer install, conda recipes, Windows + WSL setup and the PETSc backend, see the installation guide.

Quickstart

Scaffold a workspace, create a project, run it. hmp project new writes both a project.toml with the shared settings and a ready-to-run run_demo.toml on a small synthetic catchment.

hmp workspace init .
hmp project new getting_started --workspace .
hmp run projects/getting_started/run_demo.toml

The run lands in its own directory inside the project:

projects/getting_started/
├── project.toml                  shared settings, and the marker of the project root
├── run_demo.toml                 the run you launched
├── hydromodpy.lock               frozen input data
├── runs/
│   └── demo/                     one directory per run, named after the run
│       ├── config.toml           frozen resolved configuration
│       ├── fields.zarr/          field arrays (head, mesh, forcings, ...)
│       ├── tables.parquet/       metrics, parameters, budgets, timeseries
│       ├── figures/              figures rendered for this run
│       ├── manifest.json         seal, written last
│       └── provenance.json       versions, git commit, solver binary
└── .hmp/                         internals: index.duckdb, logs, checkpoints

figures/ appears once a figure is rendered, and a tagged run also carries an annotations.json. On-demand exports and reports go to share/, calibration sessions to sessions/.

Browse it from the command line:

hmp catalog ls                    # every run of the project
hmp catalog show demo --detail    # metadata, metrics, parameters, store layout
hmp viz show demo piezometric_map # render one figure into runs/demo/figures/

Or read it from Python:

import hydromodpy as hmp

catalog = hmp.open("projects/getting_started")
run = catalog.latest()

head = hmp.read(run, "head")  # lazy xarray.DataArray
water_table = hmp.read(run, "watertable_elevation", time=-1)  # numpy array

The tables are plain Parquet, so pandas.read_parquet on runs/demo/tables.parquet/metrics.parquet works too. See the results guide for the full reading and export path.

Documentation

Full documentation lives at docs.hydromodpy.fr.

Contributing

Bug reports, feature requests and pull requests are welcome. See CONTRIBUTING.md for the short version and the contributor guide for the full reference. Released versions are listed in CHANGELOG.md.

Security issues: please follow SECURITY.md and use a private advisory rather than a public issue.

How to cite

If HydroModPy supports your work, please cite the software and the companion paper. Full BibTeX, RIS and plain-text entries are on the citation page; GitHub renders the "Cite this repository" button from CITATION.cff.

Gauvain, A., Abhervé, R., Boivin, B., Roques, C., Le Mesnil, M., Coche, A., Babey, T., Marçais, J., Bouchez, C., Leray, S., Marti, E., Bresciani, E., Figueroa, R., Pélissier, M., Guillaumot, L., Touzeau, T., Issolah, I., Maugan, E., Bagagnan, R. S., Vautier, C., Sallou, J., Bourcier, J., Combemale, B., Brunner, P., Longuevergne, L., Aquilina, L., & de Dreuzy, J.-R. (2026). Technical note: HydroModPy – a Python toolbox for deploying catchment-scale shallow groundwater models. EGUsphere [preprint], 1–31. https://doi.org/10.5194/egusphere-2026-868

Authors and contact

HydroModPy is developed by Geosciences Rennes (Université de Rennes, CNRS) together with collaborators at CHYN Neuchâtel, INRAE, Pontificia Universidad Católica de Chile, Universidad de O'Higgins, WUR, Inria/IRISA and CNRS-LMD. The complete author list with affiliations is maintained in CITATION.cff.

For questions or collaboration: alexandre.gauvain.ag@gmail.com or ronan.abherve@gmail.com.

License

HydroModPy is released under the Eclipse Public License 2.0. See LICENSE.