Metadata-Version: 2.4
Name: hydromodpy
Version: 1.0.0
Summary: A Python toolbox for deploying catchment-scale shallow groundwater models
Author-email: Alexandre Gauvain <alexandre.gauvain.ag@gmail.com>, Ronan Abhervé <ronan.abherve@inrae.fr>, Jean-Raynald de Dreuzy <jean-raynald.de-dreuzy@univ-rennes.fr>, Bastien Boivin <bastien.boivin@proton.me>
Maintainer-email: Alexandre Gauvain <alexandre.gauvain.ag@gmail.com>, Ronan Abhervé <ronan.abherve@inrae.fr>, Bastien Boivin <bastien.boivin@proton.me>
License-Expression: EPL-2.0
Project-URL: Homepage, https://docs.hydromodpy.fr/v1.0/
Project-URL: Documentation, https://docs.hydromodpy.fr/v1.0/
Project-URL: Repository, https://github.com/HydroModPy/HydroModPy
Project-URL: Issues, https://github.com/HydroModPy/HydroModPy/issues
Project-URL: Google Group, https://groups.google.com/g/hydromodpy
Keywords: hydrology,hydrogeology,groundwater,modflow,watershed,modeling,catchment
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colormap
Requires-Dist: contextily
Requires-Dist: dask
Requires-Dist: flopy
Requires-Dist: geopandas
Requires-Dist: h5py
Requires-Dist: imageio
Requires-Dist: ipykernel
Requires-Dist: ipython
Requires-Dist: matplotlib
Requires-Dist: matplotlib-scalebar
Requires-Dist: netCDF4
Requires-Dist: numpy<2.5,>=2.0
Requires-Dist: pandas<3.0
Requires-Dist: plotly
Requires-Dist: pyproj
Requires-Dist: pyshp
Requires-Dist: pysheds
Requires-Dist: rasterio
Requires-Dist: rioxarray
Requires-Dist: selenium
Requires-Dist: vedo
Requires-Dist: whitebox
Requires-Dist: xarray
Requires-Dist: pyside6
Requires-Dist: spyder-kernels
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-togglebutton; extra == "docs"
Provides-Extra: ide
Requires-Dist: spyder>=6.0; extra == "ide"
Requires-Dist: jupyterlab>=4.0; extra == "ide"
Dynamic: license-file

![logo](https://raw.githubusercontent.com/HydroModPy/HydroModPy/v1.0/docs/source/images/logoHydroModPy_long.png)

# HydroModPy

A Python toolbox for deploying catchment-scale shallow groundwater models.

[![Documentation](https://img.shields.io/badge/docs-v1.0-blue)](https://docs.hydromodpy.fr/v1.0/)
[![DOI](https://img.shields.io/badge/DOI-10.5194%2Fegusphere--2026--868-blue)](https://doi.org/10.5194/egusphere-2026-868)
[![PyPI](https://img.shields.io/badge/PyPI-hydromodpy%201.0-blue)](https://pypi.org/project/hydromodpy/)
[![License: EPL-2.0](https://img.shields.io/badge/License-EPL%202.0-red.svg)](https://github.com/HydroModPy/HydroModPy/blob/v1.0/LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%E2%80%933.13-blue)](https://github.com/HydroModPy/HydroModPy/blob/v1.0/pyproject.toml)

> ### HydroModPy v1.0: the version cited in the paper
>
> This `v1.0` branch is the version described in the technical note submitted to
> *Hydrology and Earth System Sciences* (EGUsphere preprint, 2026). It is the
> reference cited by the paper and is kept up to date with fixes, so the paper
> link always points to a working v1.0.
>
> **HydroModPy v2** is the actively developed version on the `main` branch, with
> new features and a redesigned interface.
>
> | | Link |
> |---|---|
> | Paper (preprint) | https://doi.org/10.5194/egusphere-2026-868 |
> | v1.0 documentation | https://docs.hydromodpy.fr/v1.0/ |
> | v2 documentation (latest) | https://docs.hydromodpy.fr/main/ |
> | Forum (Google Group) | https://groups.google.com/g/hydromodpy |

## Presentation

HydroModPy was initiated in 2018 to streamline the setup and deployment of
hydrogeological models in catchments across the crystalline basement regions of
Normandy and Brittany (France). The platform integrates multiple open-source
libraries (e.g., FloPy, WhiteboxTools), providing a unified and reproducible
framework that is easily accessible to the scientific community. The development
of HydroModPy is driven by two main objectives:

First, it automates the extraction and discretization of watersheds from Digital
Elevation Models (DEMs) and enriches them with key hydrogeological datasets
(e.g., piezometry, hydrography, geology) compiled from local, national, and
global databases. This workflow ensures a standardized and reproducible approach
for building and running simulation ensembles across multiple catchments using
consistent input data.

Second, it facilitates the visualization, analysis, and comparison of outputs
from the different modelling components integrated within the platform. Beyond
research applications, HydroModPy also serves as an educational tool, enabling
students and researchers to explore hydrogeological modelling workflows in a
practical and reproducible environment.

## Authors

Alexandre Gauvain [1,2], Ronan Abhervé [1,3,4], Bastien Boivin [1], Alexandre Coche [1], Martin Le Mesnil [1], Tristan Babey [1], Enzo Maugan [1], Théa Touzeau [1], Imene Issolah [11], Clément Roques [3], Camille Bouchez [1], Jean Marçais [5], Sarah Leray [6], Etienne Marti [6], Etienne Bresciani [7], Ronny Figueroa [3], Mathias Pélissier [3], Simon Carlier [3], Luca Guillaumot [8], Rock S. Bagagnan [1], Camille Vautier [1], Laurent Longuevergne [1], June Sallou [9], Johan Bourcier [10], Benoit Combemale [11], Philip Brunner [3], Luc Aquilina [1], Jean-Raynald de Dreuzy [1].

- [1] Geosciences Rennes -- UMR 6118, CNRS, Université de Rennes, Rennes, France
- [2] Laboratoire de Météorologie Dynamique (LMD), CNRS, Sorbonne Université, Paris, France
- [3] Centre for Hydrogeology and Geothermics (CHYN), Université de Neuchâtel, Neuchâtel, Switzerland
- [4] UMR SAS 1069, INRAE, Centre Bretagne-Normandie, Rennes, France
- [5] UR RiverLy, INRAE, Centre Lyon-Grenoble Auvergne-Rhône-Alpes, Villeurbanne, France
- [6] Pontificia Universidad Católica de Chile, Santiago, Chile
- [7] Instituto de Ciencias de la Ingeniería, Universidad de O'Higgins, Rancagua, Chile
- [8] BRGM - French Geological Survey, F-45060 Orléans, France
- [9] INF, Wageningen University & Research, Wageningen, Netherlands
- [10] ISA/LIUPPA, Université de Pau et des Pays de l'Adour, Pau, France
- [11] Inria, IRISA, CNRS, Université de Rennes, Rennes, France

## Installation

The recommended way to install HydroModPy is with `pip` from PyPI. A `conda`
environment is also provided for the full scientific stack.

### Prerequisites

- Python 3.11 to 3.13.
- **Important**: your local path should not contain white spaces, to stay
  compatible with the MODFLOW-MODPATH suite.

### Install with pip (recommended)

Install HydroModPy from PyPI:

```bash
# without Spyder and JupyterLab
pip install "hydromodpy==1.0.*"     # latest 1.0.X, never 1.1 nor 2.0
# including Spyder and JupyterLab
pip install "hydromodpy[ide]==1.0.*"
```

The `==1.0.*` specifier always resolves to the latest `1.0.X` patch and never
crosses over to the v2 series. Use `==1.0.0` only to pin one exact release.

MODFLOW, MODPATH and MT3DMS binaries ship with the package. The PyHELP binary
downloads itself on the first call to the corresponding module.

### Install with conda

Ready-to-use environment files live in the `install/` directory (clone the
repository first, see "Get the source code" below):

- `env_hydromodpy.yml`: full runtime stack, including Spyder.
- `env_hydromodpy_pkg.yml`: same stack, then runs `pip install -e ..` to expose
  the cloned repository as an editable package.
- `env_hydromodpy_light.yml`: minimal headless stack (no IDE, no 3D viewer).
- `requirements-docker-light.txt`: pip requirements for a light Docker/server
  image.

```bash
# from the repository root
conda env create -f install/env_hydromodpy.yml
conda activate hydromodpy
```

### Get the source code

Needed for the conda environments above and for development (editable) installs.

- **Option 1**: download the `.zip` archive directly from the
  [GitHub project](https://github.com/HydroModPy/HydroModPy/tree/v1.0).
- **Option 2**: clone the repository with a Git client such as
  [GitHub Desktop](https://desktop.github.com/download/).
- **Option 3**: use the command line:

```bash
git clone https://github.com/HydroModPy/HydroModPy.git
cd HydroModPy
git checkout v1.0
```

For development (editable) mode from the clone:

```bash
pip install -e .
```

## Launch HydroModPy

HydroModPy v1.0 was primarily developed for use with Spyder, so we recommend
launching it from this IDE:

1. Activate the environment:

```bash
conda activate hydromodpy
```

2. Open Spyder or Jupyter:

```bash
spyder
# or
jupyter notebook
```

3. Import HydroModPy in Python:

```python
import hydromodpy
from hydromodpy import Watershed

# Check version
print(hydromodpy.__version__)
```

## Examples

Run the example scripts in `examples/` in this order:

```
00_quick_test_of_wide_hydromodpy_capabilities
01_simplified_example_presented_in_the_paper
02_basic_features_and_overview_of_possibilities
03_hydrographic_network_in_steady_state
04_streamflow_intermittence_in_transient
05_piezometry_in_a_heterogeneous_coastal_aquifer
06_particle_tracking_and_residence_times
07_analytical_solution_for_streamflow_recession
08_exponential_distribution_of_residence_times
09_transport_model_for_an_agricultural_catchment
10_coupling_with_land_surface_model_pyhelp
11_run_from_scratch_without_plots
```

The same examples are available as notebooks in the
[documentation](https://docs.hydromodpy.fr/v1.0/).

## Documentation

- v1.0 documentation: https://docs.hydromodpy.fr/v1.0/
- v2 documentation (latest development): https://docs.hydromodpy.fr/main/

The v1.0 documentation is built and published automatically to
`https://docs.hydromodpy.fr/v1.0/` on every update of the `v1.0` branch.

## Publications

Papers published using HydroModPy:

Bagagnan, R. S., Abhervé, R., Laverman, A. M., & Vautier, C. (2026). Groundwater controls on legacy antibiotics and pesticides in an intensive agricultural headwater catchment. Journal of Hydrology, 66. https://doi.org/10.1016/j.jhydrol.2026.135118

Abhervé, R., Roques, C., de Dreuzy, J.-R., Van Der Veen, T., Dumaine, L., Chatton, E., Brunner, P., Aquilina, L., & Servière, L. (2025). Projected climate change impacts on groundwater-surface water connectivity in a compartmentalized mountain headwater bedrock aquifer. Water Resources Research, 61(10). https://doi.org/10.1029/2025WR040083

Floriancic, M. G., Abhervé, R., Bouchez, C., Martinez, J. J., & Roques, C. (2024). Evidence of Groundwater Seepage and Mixing at the Vicinity of a Knickpoint in a Mountain Stream. Geophysical Research Letters, 51. https://doi.org/10.1029/2024GL111325

Le Mesnil, M., Gauvain, A., Gresselin, F., Aquilina, L., & de Dreuzy, J.-R. (2024). Characterizing coastal aquifer heterogeneity from a single piezometer head chronicle. Journal of Hydrology, 642. https://doi.org/10.1016/j.jhydrol.2024.131859

Abhervé, R., Roques, C., De Dreuzy, J.-R., Datry, T., Brunner, P., Longuevergne, L., & Aquilina, L. (2024). Improving calibration of groundwater flow models using headwater streamflow intermittence. Hydrological Processes, 38(6). https://doi.org/10.1002/hyp.15167

Abhervé, R., Roques, C., Gauvain, A., Longuevergne, L., Louaisil, S., Aquilina, L., & de Dreuzy, J.-R. (2023). Calibration of groundwater seepage against the spatial distribution of the stream network to assess catchment-scale hydraulic properties. Hydrology and Earth System Sciences, 27(17), 3221-3239. https://doi.org/10.5194/hess-27-3221-2023

## How to cite

If HydroModPy supports your work, please cite the technical note:

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

## License

HydroModPy is released under the Eclipse Public License v2.0 (EPL-2.0). See
[LICENSE](https://github.com/HydroModPy/HydroModPy/blob/v1.0/LICENSE).

## Contact

For any question regarding HydroModPy, please contact:

- <alexandre.gauvain.ag@gmail.com>
- <ronan.abherve@inrae.fr>
- <bastien.boivin@proton.me>
- <jean-raynald.de-dreuzy@univ-rennes.fr>
