Metadata-Version: 2.4
Name: hydromodpy
Version: 2.0.0a3
Summary: A Python toolbox for deploying catchment-scale shallow groundwater models
Author-email: Alexandre Gauvain <alexandre.gauvain.ag@gmail.com>, Ronan Abherve <ronan.abherve@gmail.com>, Jean-Raynald de Dreuzy <jean-raynald.de-dreuzy@univ-rennes.fr>
Maintainer-email: Alexandre Gauvain <alexandre.gauvain.ag@gmail.com>, Ronan Abherve <ronan.abherve@gmail.com>, Bastien Boivin <bastien.boivin@proton.me>
License-Expression: EPL-2.0
Project-URL: Homepage, https://docs.hydromodpy.fr/
Project-URL: Documentation, https://docs.hydromodpy.fr/
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,queryable-results
Classifier: Development Status :: 3 - Alpha
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: contextily<2,>=1.7.0
Requires-Dist: flopy<4,>=3.10.0
Requires-Dist: geopandas<2,>=1.1.3
Requires-Dist: h5py<4,>=3.16.0
Requires-Dist: imageio<3,>=2.37.3
Requires-Dist: matplotlib<4,>=3.10.8
Requires-Dist: meshio<6,>=5.3.5
Requires-Dist: netCDF4<2,>=1.7.4
Requires-Dist: numpy<3,>=2.4.4
Requires-Dist: pandas<3,>=2.3.3
Requires-Dist: Pillow<13,>=12.0.0
Requires-Dist: optuna<5,>=4.8.0
Requires-Dist: plotly<7,>=6.7.0
Requires-Dist: pint<1,>=0.25.3
Requires-Dist: pydantic-pint<1,>=0.4
Requires-Dist: py7zr<2,>=1.0
Requires-Dist: pyarrow<24,>=23.0.1
Requires-Dist: pyproj<4,>=3.7.2
Requires-Dist: rasterio<2,>=1.4.0
Requires-Dist: requests<3,>=2.32.5
Requires-Dist: rioxarray<1,>=0.19
Requires-Dist: scikit-learn<2,>=1.8.0
Requires-Dist: scipy<2,>=1.17.1
Requires-Dist: shapely<3,>=2
Requires-Dist: whitebox-workflows==1.3.5
Requires-Dist: xarray<2027,>=2026.4.0
Requires-Dist: xugrid<1,>=0.15.2
Requires-Dist: pydantic<3,>=2.13.3
Requires-Dist: duckdb<2,>=1.5.2
Requires-Dist: dask<2027,>=2026.3.0
Requires-Dist: rich<16,>=13.9.4
Requires-Dist: zarr<4,>=3.1.6
Requires-Dist: zstandard<1,>=0.25.0
Requires-Dist: tomlkit<1,>=0.14.0
Requires-Dist: tomli-w<2,>=1.2.0
Requires-Dist: universal_pathlib<1,>=0.2
Requires-Dist: pandera<1,>=0.31.1
Requires-Dist: platformdirs<5,>=4
Requires-Dist: filelock<4,>=3.13
Requires-Dist: argcomplete<4,>=3.5
Provides-Extra: calibration
Requires-Dist: cma<5,>=4.4.4; extra == "calibration"
Requires-Dist: cmaes<1,>=0.12.0; extra == "calibration"
Provides-Extra: mesh
Requires-Dist: gmsh<5,>=4.15.2; extra == "mesh"
Provides-Extra: duckdb
Requires-Dist: duckdb; extra == "duckdb"
Provides-Extra: metrics
Requires-Dist: psutil; extra == "metrics"
Requires-Dist: pynvml; extra == "metrics"
Provides-Extra: mf6api
Requires-Dist: modflowapi>=0.2; extra == "mf6api"
Requires-Dist: xmipy>=1.5; extra == "mf6api"
Provides-Extra: all
Requires-Dist: duckdb; extra == "all"
Requires-Dist: psutil; extra == "all"
Requires-Dist: pynvml; extra == "all"
Provides-Extra: viz
Requires-Dist: datashader<1,>=0.16; extra == "viz"
Requires-Dist: lttb<1,>=0.3; extra == "viz"
Provides-Extra: fair
Requires-Dist: pystac<2,>=1.10; extra == "fair"
Requires-Dist: stac-validator<5,>=3.5; extra == "fair"
Requires-Dist: rocrate<1,>=0.10; extra == "fair"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: pytest-timeout; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: coverage[toml]>=7.0; extra == "test"
Requires-Dist: pyyaml; extra == "test"
Requires-Dist: jsonschema>=4.0; extra == "test"
Requires-Dist: pyinstrument<6,>=5.0; extra == "test"
Requires-Dist: hypothesis<7,>=6.100; extra == "test"
Provides-Extra: performance
Requires-Dist: pytest-benchmark<6,>=5.0; extra == "performance"
Requires-Dist: uuid-utils<1,>=0.10; extra == "performance"
Requires-Dist: polars<2,>=1.0; extra == "performance"
Provides-Extra: profiling
Requires-Dist: pyinstrument<6,>=5.0; extra == "profiling"
Provides-Extra: docs
Requires-Dist: sphinx<8,>=7.0; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: readthedocs-sphinx-ext; extra == "docs"
Requires-Dist: pydata-sphinx-theme==0.17.1; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-polyversion>=1.0; extra == "docs"
Requires-Dist: sphinxcontrib-plantuml; extra == "docs"
Requires-Dist: autodoc-pydantic>=2.0; extra == "docs"
Requires-Dist: sphinx-codeautolink; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints<3; extra == "docs"
Requires-Dist: sphinxext-rediraffe; extra == "docs"
Requires-Dist: sphinx-favicon<1.1; extra == "docs"
Requires-Dist: sphinx-sitemap; extra == "docs"
Requires-Dist: sphinx-last-updated-by-git; extra == "docs"
Requires-Dist: sphinxext-opengraph; extra == "docs"
Requires-Dist: sphinx-lint; extra == "docs"
Requires-Dist: doc8; extra == "docs"
Provides-Extra: docs-uml
Requires-Dist: erdantic; extra == "docs-uml"
Provides-Extra: ide
Requires-Dist: ipykernel; extra == "ide"
Requires-Dist: ipython; extra == "ide"
Requires-Dist: jupyterlab>=4.0; extra == "ide"
Requires-Dist: pyside6; extra == "ide"
Requires-Dist: spyder>=6.0; extra == "ide"
Requires-Dist: spyder-kernels; extra == "ide"
Provides-Extra: viewer3d
Requires-Dist: pyvista; extra == "viewer3d"
Provides-Extra: dev
Requires-Dist: ruff>=0.15; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Dynamic: license-file

![logo](https://github.com/HydroModPy/HydroModPy/blob/61d654ca738c488480fd22aa01c2b1002984eac9/docs/readthedocs/source/images/logoHydroModPy_long.png)

**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.

[![PyPI](https://img.shields.io/pypi/v/hydromodpy.svg)](https://pypi.org/project/hydromodpy/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![License: EPL-2.0](https://img.shields.io/badge/license-EPL--2.0-green.svg)](https://opensource.org/licenses/EPL-2.0)
[![CI](https://github.com/HydroModPy/HydroModPy/actions/workflows/main-ci.yml/badge.svg?branch=main)](https://github.com/HydroModPy/HydroModPy/actions/workflows/main-ci.yml?query=branch%3Amain)
[![Documentation](https://github.com/HydroModPy/HydroModPy/actions/workflows/docs-deploy-pages.yml/badge.svg?branch=main)](https://docs.hydromodpy.fr/main/)
[![Codecov](https://codecov.io/gh/HydroModPy/HydroModPy/branch/main/graph/badge.svg)](https://codecov.io/gh/HydroModPy/HydroModPy/tree/main)

## 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

```bash
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:

```bash
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](https://docs.hydromodpy.fr/main/install.html).

## 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.

```bash
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:

```text
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:

```bash
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:

```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](https://docs.hydromodpy.fr/main/user_guide/results-and-exports.html)
for the full reading and export path.

## Documentation

Full documentation lives at
**[docs.hydromodpy.fr](https://docs.hydromodpy.fr/main/)**.

| Section | What it covers |
|---------|----------------|
| [Get started](https://docs.hydromodpy.fr/main/getting_started/index.html) | Install, scaffold, first run end to end. |
| [User Guide](https://docs.hydromodpy.fr/main/user_guide/index.html) | Workflows, configuration, theory, cookbook. |
| [Configuration](https://docs.hydromodpy.fr/main/user_guide/config_reference/index.html) | Every TOML section validated by `HydroModPyConfig`. |
| [CLI](https://docs.hydromodpy.fr/main/cli/index.html) | Every `hmp` verb, its sub-actions, and the typed exit codes. |
| [Gallery](https://docs.hydromodpy.fr/main/capability_gallery/index.html) | Validation figures, mesh illustrations, watershed diagnostics. |
| [API Reference](https://docs.hydromodpy.fr/main/api/index.html) | Auto-generated reference for every public class and module. |
| [Architecture](https://docs.hydromodpy.fr/main/architecture/index.html) | Layer matrix, module diagrams, contributor maps. |

## Contributing

Bug reports, feature requests and pull requests are welcome. See
[CONTRIBUTING.md](https://github.com/HydroModPy/HydroModPy/blob/main/CONTRIBUTING.md) for the short version and the
[contributor guide](https://docs.hydromodpy.fr/main/contribute.html)
for the full reference. Released versions are listed in
[CHANGELOG.md](https://github.com/HydroModPy/HydroModPy/blob/main/CHANGELOG.md).

Security issues: please follow [SECURITY.md](https://github.com/HydroModPy/HydroModPy/blob/main/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](https://docs.hydromodpy.fr/main/how_to_cite.html);
GitHub renders the "Cite this repository" button from
[`CITATION.cff`](https://github.com/HydroModPy/HydroModPy/blob/main/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`](https://github.com/HydroModPy/HydroModPy/blob/main/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](https://opensource.org/licenses/EPL-2.0).
See [LICENSE](https://github.com/HydroModPy/HydroModPy/blob/main/LICENSE).
