Technical note: HydroModPy (v1.0) – a Python toolbox for deploying catchment-scale shallow groundwater models
Abstract
Despite the widespread use of physically based groundwater models, their deployment at the catchment scale remains challenging and time-consuming. HydroModPy was developed to address this gap by enabling automated and streamlined multi-site developement of hydrogeological models at the catchment scale. This open-source Python toolbox facilitates the construction, execution, calibration, and analysis of unconfined shallow groundwater models. The current version integrates established geospatial such as WhiteboxTools and hydrogeological libraries with FloPy-driven MODFLOW-NWT simulations, along with optional particle-tracking and solute transport modules (MODPATH and MT3DMS), to provide a fully scriptable, end-to-end workflow. Automation is achieved through dedicated functions and classes capable of performing watershed delineation from digital elevation models, preparing spatial and temporal recharge forcings, generating computational meshes and vertical discretization schemes, assigning model parameters, and running simulations in steady or transient state. The overall framework supports systematic and reproducible calibration routines that leverage subsurface data such as groundwater head measurements, as well as surface observations — including stream network maps and stream intermittency patterns — to constrain model estimates of aquifer hydraulic properties. Model outputs and provenance metadata are exported in standard geospatial formats to ensure interoperability and alignment with FAIR data principles. Built-in visualization tools and integration with Jupyter Notebooks support interactive exploration, teaching applications, and fully reproducible analyses. In this technical note, we present the HydroModPy architecture and its core functionalities, demonstrate model deployment across various hydrogeological contexts, and discuss ongoing and planned developments for future versions of this collaborative tool. The code is modular and extensible, making it suitable for adoption by a broad user community. Planned enhancements include tighter coupling with land-surface or ecohydrological models adding new numerical solvers, the integration of advanced calibration and uncertainty quantification algorithms, and improved user interfaces to facilitate application in various environmental settings. HydroModPy contributes to improving the understanding of hydrogeological processes that are often poorly characterized or inadequately represented. It also provides valuable support for multidisciplinary education, particularly for those studying groundwater systems and their interactions with the surface in headwater catchments. Furthermore, this numerical framework can serve as a practical decision-support tool for public policy and water resource management, helping stakeholders address current and future groundwater-related challenges.
Related
- Long-term observatory of groundwater, soil moisture and rainfall in a French urban catchment
- Spatial distribution, origins, and driving mechanisms of groundwater nitrate contamination in a rural-agricultural-mining catchment: Insight from PMF, machine learning and multi-isotopic techniques
- Technical note: A physically based correction of WRF temperature using atmospheric lapse rates for high-resolution hydrological simulations in a glacierized catchment
- Evidence of macroclimatic impacts of deploying agroforestry at landscape scale
- Deploying machine learning components coupled to Earth System Models with OASIS3-MCT (v6) and Eophis (v1.1)
BibTeX
@article{gauvain2026technical,
title = {{Technical note: HydroModPy (v1.0) – a Python toolbox for deploying catchment-scale shallow groundwater models}},
author = {Alexandre Gauvain and Ronan Abhervé and Bastien Boivin and Alexandre Coche and Martin Le Mesnil and Tristan Babey and Enzo Maugan and Théa Touzeau and Imene Issolah and Clément Roques and Camille Bouchez and Jean Marçais and Sarah Leray and Etienne Marti and Etienne Bresciani and Ronny Figueroa and Mathias Pélissier and Simon Carlier and Luca Guillaumot and Rock Bagagnan and Camille Vautier and Laurent Longuevergne and June Sallou and Johan Bourcier and Benoit Combemale and Philip Brunner and Luc Aquilina and Jean-Raynald de Dreuzy},
journal = {Hydrology and Earth System Sciences},
year = {2026},
month = sep,
doi = {10.5194/hess-30-5571-2026},
url = {https://hal.inrae.fr/hal-05568617v1},
note = {CC BY 4.0},
}
RIS
TY - JOUR
TI - Technical note: HydroModPy (v1.0) – a Python toolbox for deploying catchment-scale shallow groundwater models
AU - Alexandre Gauvain
AU - Ronan Abhervé
AU - Bastien Boivin
AU - Alexandre Coche
AU - Martin Le Mesnil
AU - Tristan Babey
AU - Enzo Maugan
AU - Théa Touzeau
AU - Imene Issolah
AU - Clément Roques
AU - Camille Bouchez
AU - Jean Marçais
AU - Sarah Leray
AU - Etienne Marti
AU - Etienne Bresciani
AU - Ronny Figueroa
AU - Mathias Pélissier
AU - Simon Carlier
AU - Luca Guillaumot
AU - Rock Bagagnan
AU - Camille Vautier
AU - Laurent Longuevergne
AU - June Sallou
AU - Johan Bourcier
AU - Benoit Combemale
AU - Philip Brunner
AU - Luc Aquilina
AU - Jean-Raynald de Dreuzy
PY - 2026
DA - 2026/09/08
JO - Hydrology and Earth System Sciences
DO - 10.5194/hess-30-5571-2026
UR - https://hal.inrae.fr/hal-05568617v1
AB - Despite the widespread use of physically based groundwater models, their deployment at the catchment scale remains challenging and time-consuming. HydroModPy was developed to address this gap by enabling automated and streamlined multi-site developement of hydrogeological models at the catchment scale. This open-source Python toolbox facilitates the construction, execution, calibration, and analysis of unconfined shallow groundwater models. The current version integrates established geospatial such as WhiteboxTools and hydrogeological libraries with FloPy-driven MODFLOW-NWT simulations, along with optional particle-tracking and solute transport modules (MODPATH and MT3DMS), to provide a fully scriptable, end-to-end workflow. Automation is achieved through dedicated functions and classes capable of performing watershed delineation from digital elevation models, preparing spatial and temporal recharge forcings, generating computational meshes and vertical discretization schemes, assigning model parameters, and running simulations in steady or transient state. The overall framework supports systematic and reproducible calibration routines that leverage subsurface data such as groundwater head measurements, as well as surface observations — including stream network maps and stream intermittency patterns — to constrain model estimates of aquifer hydraulic properties. Model outputs and provenance metadata are exported in standard geospatial formats to ensure interoperability and alignment with FAIR data principles. Built-in visualization tools and integration with Jupyter Notebooks support interactive exploration, teaching applications, and fully reproducible analyses. In this technical note, we present the HydroModPy architecture and its core functionalities, demonstrate model deployment across various hydrogeological contexts, and discuss ongoing and planned developments for future versions of this collaborative tool. The code is modular and extensible, making it suitable for adoption by a broad user community. Planned enhancements include tighter coupling with land-surface or ecohydrological models adding new numerical solvers, the integration of advanced calibration and uncertainty quantification algorithms, and improved user interfaces to facilitate application in various environmental settings. HydroModPy contributes to improving the understanding of hydrogeological processes that are often poorly characterized or inadequately represented. It also provides valuable support for multidisciplinary education, particularly for those studying groundwater systems and their interactions with the surface in headwater catchments. Furthermore, this numerical framework can serve as a practical decision-support tool for public policy and water resource management, helping stakeholders address current and future groundwater-related challenges.
SN - 1027-5606
SN - 1607-7938
ER -