HydroModPy#
A Python toolbox for automated, reproducible, catchment-scale modeling of shallow groundwater. One TOML configuration drives MODFLOW 6, MODFLOW-NWT, Boussinesq, and GR4J on the same hydrology, from DEM to calibrated heads and streams.
Important
This documentation tracks the v2 alpha line, currently 2.0.0a1.
Install it with pip install --pre hydromodpy. Existing v1 projects
should stay pinned to exact tags such as v1.0.0.
pip install --pre hydromodpy or use the conda environment, then
check the prerequisites.
Concepts in five minutes, then a first end-to-end project on a real basin.
Every TOML section validated by HydroModPyConfig, with
fields, defaults, and types.
Auto-generated reference for every public class, function, and
module under hydromodpy.
What HydroModPy does#
Physically based groundwater models remain expensive to deploy at the catchment scale: data wrangling, mesh design, parameterization, calibration, and post-processing rarely follow a uniform path from one site to the next. HydroModPy was built to close that gap. It turns the construction, execution, calibration, and analysis of unconfined shallow groundwater models into a single scriptable workflow that can be replayed across many catchments with consistent inputs and outputs.
The toolbox automates the steps that usually consume the most time:
Watershed extraction from digital elevation models, with the geospatial backbone provided by WhiteboxTools and the standard geospatial Python stack.
Forcing preparation: spatial and temporal recharge, climate inputs, and observation ingestion (groundwater heads, stream networks, intermittency patterns).
Mesh and vertical discretization suited to shallow basement aquifers, plus parameter assignment and steady or transient runs.
Calibration and validation that combine subsurface heads with surface signals (active stream networks, intermittency) to constrain hydraulic properties.
Standard, FAIR-aligned exports with provenance metadata, plus built-in visualization and notebook integration for teaching and reproducible analyses.
Originally a FloPy-driven MODFLOW-NWT toolbox, HydroModPy now ships a multi-solver architecture, a Pydantic-validated configuration, and a columnar storage stack (DuckDB catalog, Zarr fields, Parquet tables) that make end-to-end runs reproducible and inspectable.
Highlights#
MODFLOW 6, MODFLOW-NWT, Boussinesq, and GR4J behind a single adapter layer. Optional MODPATH and MT3DMS for particle tracking and solute transport.
One HydroModPyConfig root, every field typed and validated
by Pydantic v2. The CLI hmp runs the same config without any
Python.
DEM-driven watershed delineation, recharge forcing, mesh and vertical discretization, observation ingestion, all from one configuration.
Heads, stream networks, and intermittency patterns combined into reproducible calibration loops with provenance tracking.
DuckDB catalog, Zarr field arrays, Parquet tables, and standard geospatial formats with metadata for interoperability.
Validation figures, mesh illustrations, and notebook examples curated for documentation, training, and decision support.
What’s new#
Recent entries from CHANGELOG.md:
v0.3.3 (2025-12-03): lightweight conda environment option, surface routing consolidated under
masstransfer, leaner SIM2 memory use.v0.3.2 (2025-11-28): SIM2 reworked with coarse-clip then reproject,
disk_clipaccepts.shp,.gpkg,.geojson.v0.3.1 (2025-11-14): installation guide reorganized, dual YAML options for runtime versus editable installs, NumPy >= 2 baseline.
How to cite#
If HydroModPy supports your work, please cite both the software and the
companion technical note (Gauvain et al., 2026, EGUsphere,
doi:10.5194/egusphere-2026-868).
The How to cite HydroModPy page lists BibTeX, RIS, and plain-text variants;
CITATION.cff at the repository root is what GitHub renders behind the
“Cite this repository” button.
BibTeX entries
@software{hydromodpy_software,
title = {HydroModPy: a Python toolbox for deploying catchment-scale shallow groundwater models},
author = {Gauvain, A. and Abherv\'e, R. and Boivin, B. and Roques, C. and
Le Mesnil, M. and Coche, A. and Babey, T. and Mar\c{c}ais, J. and
Bouchez, C. and Leray, S. and Marti, E. and Bresciani, E. and
Figueroa, R. and P\'elissier, M. and Guillaumot, L. and
Touzeau, T. and Issolah, I. and Maugan, E. and Bagagnan, R. S. and
Vautier, C. and Sallou, J. and Bourcier, J. and Combemale, B. and
Brunner, P. and Longuevergne, L. and Aquilina, L. and
de Dreuzy, J.-R.},
year = {2026},
url = {https://github.com/HydroModPy/HydroModPy},
license = {EPL-2.0}
}
@article{egusphere-2026-868,
title = {Technical note: HydroModPy -- a Python toolbox for deploying catchment-scale shallow groundwater models},
author = {Gauvain, A. and Abherv\'e, R. and Boivin, B. and Roques, C. and
Le Mesnil, M. and Coche, A. and Babey, T. and Mar\c{c}ais, J. and
Bouchez, C. and Leray, S. and Marti, E. and Bresciani, E. and
Figueroa, R. and P\'elissier, M. and Guillaumot, L. and
Touzeau, T. and Issolah, I. and Maugan, E. and Bagagnan, R. S. and
Vautier, C. and Sallou, J. and Bourcier, J. and Combemale, B. and
Brunner, P. and Longuevergne, L. and Aquilina, L. and
de Dreuzy, J.-R.},
journal = {EGUsphere},
year = {2026},
volume = {2026},
pages = {1--31},
doi = {10.5194/egusphere-2026-868}
}
Linked publications and a registry of catchments where HydroModPy has been deployed live on Papers using HydroModPy and Geographic application map.
Documentation map#
Get started
Install HydroModPy, scaffold a workspace, and run a first end-to-end simulation in five steps.
User Guide
Usage modes, workflow families, cookbook, and the theory backing each solver.
Configuration
Every TOML section validated by HydroModPyConfig: fields,
defaults, types, plus the JSON Schema explorer.
Gallery
Static mesh illustrations, validation figures, and watershed diagnostics curated for documentation and teaching.
API Reference
Auto-generated reference for every public class, function, and
module under hydromodpy.
Developer
Architecture, code-reading maps, component and class diagrams, developer notes, and contributing guidelines.
About
How to cite HydroModPy, papers using the toolbox, and field applications across catchments.