Technical note: HydroModPy – 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.