Metadata-Version: 2.4
Name: hydroflow
Version: 0.1.1
Summary: hydroflow: a distributed, physics-based hydrological + hydrodynamic model — DEM preprocessing, gauge/IMERG precipitation, VSA + Green-Ampt + impervious runoff generation, and kinematic/diffusive-wave/Muskingum–Cunge routing, with optional Google Earth Engine forcing and CPU/GPU backends.
Author-email: Saurav Bhattarai <bhattaraisaurav36@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/SauravBhattarai19/hydroflow
Project-URL: Documentation, https://pyhydroflow.readthedocs.io
Project-URL: Issues, https://github.com/SauravBhattarai19/hydroflow/issues
Keywords: hydrology,hydrodynamics,watershed,runoff,flood,routing,kinematic wave,diffusive wave,muskingum-cunge,VSA,OPM,green-ampt,GIS,rainfall-runoff,earth-engine
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: rasterio
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: pyproj
Requires-Dist: pysheds
Requires-Dist: pyflwdir
Requires-Dist: fiona
Requires-Dist: pyyaml
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == "gpu"
Provides-Extra: gee
Requires-Dist: earthengine-api; extra == "gee"
Provides-Extra: notebook
Requires-Dist: geemap; extra == "notebook"
Requires-Dist: ipyleaflet; extra == "notebook"
Requires-Dist: ipywidgets; extra == "notebook"
Dynamic: license-file

# hydroflow

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![Docs](https://img.shields.io/badge/docs-pyhydroflow.readthedocs.io-teal.svg)](https://pyhydroflow.readthedocs.io)

**A distributed, physics-based hydrological + hydrodynamic model.** hydroflow
turns a bare-earth DEM and a rain event into a routed flood hydrograph —
Variable Source Area runoff, Green-Ampt infiltration and impervious shedding,
feeding grid-based kinematic / diffusive-wave / Muskingum–Cunge channel routing,
with optional GPU acceleration and Google Earth Engine forcing.

## 📖 Documentation

**Full docs, guides and API reference → [pyhydroflow.readthedocs.io](https://pyhydroflow.readthedocs.io)**

Learn the science interactively → [the hydroflow course](https://sauravbhattarai19.github.io/hydroflow/)

## Installation

```bash
pip install hydroflow            # core (CPU)
pip install "hydroflow[gpu]"     # + CuPy/CUDA acceleration
pip install "hydroflow[gee]"     # + Google Earth Engine forcing
```

## Quick example

```python
from hydroflow import Config, run_pipeline

cfg = Config(DEM_PATH="dem.tif", OUTPUT_DIR="results/",
             OUTPUT_POINT=(27.632, 85.293))   # (lat, lon) of the outlet
cfg.update_output_paths()
run_pipeline(cfg, stages=("process_dem", "routing"))   # → results/hydrograph.csv
```

Or from the command line:

```bash
hydroflow init-config -o run.yaml   # template config
hydroflow run -c run.yaml           # process_dem + routing
```

## What it offers

- **DEM → watershed** — reproject, pit-fill, D8 flow direction/accumulation and
  delineation (`pysheds` or `pyflwdir`).
- **Runoff generation** — `none · coefficient · raster · scs_cn · vsa_opm`; VSA
  saturation-excess + Green-Ampt + impervious as composable mechanisms.
- **Flood routing** — kinematic, diffusive-wave, or Muskingum–Cunge, with
  always-on mass-balance checking.
- **Satellite forcing** — optional IMERG rainfall, SERVES soil deficit,
  SoilGrids, LULC/LCZ via Google Earth Engine (degrades gracefully offline).
- **CPU / GPU** — one code path (NumPy or CuPy), automatic CPU fallback.
- **Three interfaces** — Python API, a `hydroflow` CLI, and a QGIS plugin, all
  driven by one `Config` object.

## Links

- **Documentation:** <https://pyhydroflow.readthedocs.io>
- **Interactive course:** <https://sauravbhattarai19.github.io/hydroflow/>
- **Source & issues:** <https://github.com/SauravBhattarai19/hydroflow>

## License

[MIT](LICENSE) © Saurav Bhattarai. Based on the One-Parameter Model of
Pradhan & Ogden (2010).
