hydrosovereign 6.5.4

HydroSovereign AI Engine — Python package for hydrological analysis, satellite data, and water sovereignty assessment

HydroSovereign AI Engine (HSAE) — Python Package

Author: Seifeldin M.G. Alkhedir · ORCID 0000-0003-0821-2991 · University of Khartoum

---

🔗 Quick Links

Resource	Link
🔌 QGIS Plugin	plugins.qgis.org/plugins/hsae_qgis/ — Plugin ID: 5040
🐍 PyPI Package	pypi.org/project/hydrosovereign/
🌐 Live Streamlit App	HSAE v6.01
📦 GitHub (Main App)	HydroSovereign-AI-Engine-HSAE-v601
🏛️ Zenodo DOI	10.5281/zenodo.19180160
📄 SoftwareX Paper	SOFTX-D-26-00442 — Under Review 2026
📖 Manual PDF	⬇️ Download Complete Guide
🐛 Issues	GitHub Issues

---

What is HSAE?

HydroSovereign AI Engine (HSAE) is a Python package for transboundary river basin analysis, combining satellite remote sensing, physics-based hydrological modelling, geopolitical water law, and AI-powered negotiation assessment.

Two novel scientific indices:

Index	Full Name	Range	Blue Nile Result
ATDI	Alkhedir Transparency Deficit Index	0–100%	43.5% — Art. 7 UNWC zone
HIFD	Human-Induced Flow Deficit	0–100%	20.0% — 20% withheld

---

⚙️ Installation

pip install hydrosovereign            # base
pip install hydrosovereign[viz]       # + Plotly & Folium
pip install hydrosovereign[gee]       # + Google Earth Engine
pip install hydrosovereign[all]       # everything

Requirements: Python ≥ 3.9, NumPy, Pandas, SciPy, Requests

---

Quick Start

from hydrosovereign import ATDI, HIFD, ConflictIndex, NegotiationAI

# Blue Nile (GERD)
params = dict(runoff_coeff=0.38, dam_capacity_bcm=74.0,
              n_countries=3, dispute_level=4, basin_area_km2=174000)

atdi = ATDI(**params)   # → 43.5%
hifd = HIFD(**params)   # → 20.0%
ci   = ConflictIndex(atdi=atdi, hifd=hifd, **params)  # → 0.44 HIGH

ai = NegotiationAI()
p  = ai.predict(atdi=atdi, ci=ci, n_countries=3, dispute_level=4)
print(f"P(Negotiation) = {p:.0%}")  # → 58% → Art.17 Mediation

---

Architecture

hydrosovereign/
├── api.py          ← analyze_basin() entry point
├── indices.py      ← ATDI, HIFD, NSE, KGE, CI
├── hbv.py          ← HBV-96 + SCE-UA calibration
├── basins.py       ← 26-basin registry (7 world regions)
├── legal.py        ← UNWC 1997 article assessment (33 articles)
├── alerts.py       ← Alert level classification
├── data/fetchers.py ← Open-Meteo, GRDC, NASA POWER
├── viz/            ← Plotly charts + Folium maps
├── models/hbv.py   ← HBV-96 model class
└── ai/negotiation.py ← NegotiationAI (478 TFDD/ICJ cases)

---

📊 Key Results (Blue Nile / GERD)

Metric	Value	Class
NSE	0.63	Satisfactory
KGE	0.74	Satisfactory
ATDI	43.5%	Art. 7 UNWC
HIFD	20.0%	Moderate
CI	0.44	HIGH
P(Negotiation)	58%	Mediation

Note: NSE and KGE are proxy-validated against GloFAS ERA5 v4 reanalysis — no open GRDC gauge data is available for the Blue Nile at basin scale for 2024.

---

📝 Citation

@software{alkedir2026hsae,
  author    = {Alkhedir, Seifeldin M.G.},
  title     = {{HydroSovereign AI Engine (HSAE) v6.01}},
  year      = {2026},
  publisher = {QGIS Plugin Repository + PyPI + Zenodo},
  version   = {6.0.1},
  note      = {QGIS Plugin ID: 5040. SoftwareX SOFTX-D-26-00442.},
  url       = {https://plugins.qgis.org/plugins/hsae_qgis/},
  doi       = {10.5281/zenodo.19180160},
  orcid     = {0000-0003-0821-2991}
}

---

hydrosovereign v6.5.3 · GPL-3.0 · Seifeldin M.G. Alkhedir · ORCID: 0000-0003-0821-2991