Metadata-Version: 2.4
Name: PyHydroGeophysX
Version: 0.3.0
Summary: A comprehensive Python package for integrating hydrological model outputs with geophysical forward modeling and inversion, featuring an automatic cross-modal geophysics agent for subsurface hydrology
Author-email: Hang Chen <hangchen.work@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/geohang/PyHydroGeophysX
Project-URL: Documentation, https://geohang.github.io/PyHydroGeophysX/
Project-URL: Repository, https://github.com/geohang/PyHydroGeophysX
Project-URL: Bug Tracker, https://github.com/geohang/PyHydroGeophysX/issues
Keywords: geophysics,hydrology,ERT,seismic,tomography,inversion,MODFLOW,ParFlow,watershed monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.21
Requires-Dist: scipy<3.0,>=1.8
Requires-Dist: matplotlib<4.0,>=3.5
Requires-Dist: pandas>=1.3.0
Requires-Dist: joblib>=1.2
Requires-Dist: tqdm>=4.62
Provides-Extra: geophysics
Requires-Dist: pygimli<2.0,>=1.5.5; extra == "geophysics"
Requires-Dist: simpeg<1.0,>=0.24; extra == "geophysics"
Requires-Dist: flopy<4.0,>=3.5; extra == "geophysics"
Requires-Dist: pftools>=1.3; extra == "geophysics"
Provides-Extra: gpu
Requires-Dist: cupy-cuda11x; extra == "gpu"
Provides-Extra: agents
Requires-Dist: openai; extra == "agents"
Requires-Dist: google-generativeai; extra == "agents"
Requires-Dist: anthropic; extra == "agents"
Provides-Extra: climate
Requires-Dist: pydaymet>=0.16.0; extra == "climate"
Requires-Dist: pandas>=1.3.0; extra == "climate"
Requires-Dist: xarray>=0.19.0; extra == "climate"
Provides-Extra: webapp
Requires-Dist: streamlit<2.0,>=1.35; extra == "webapp"
Requires-Dist: plotly<7.0,>=5.18; extra == "webapp"
Requires-Dist: streamlit-plotly-events>=0.0.6; extra == "webapp"
Requires-Dist: pyarrow>=14.0; extra == "webapp"
Provides-Extra: desktop
Requires-Dist: PySide6>=6.5; extra == "desktop"
Requires-Dist: pyqtgraph>=0.13; extra == "desktop"
Requires-Dist: qtawesome>=1.2; extra == "desktop"
Requires-Dist: numpy<3.0,>=1.21; extra == "desktop"
Requires-Dist: pandas>=1.3.0; extra == "desktop"
Provides-Extra: seismic-raw
Requires-Dist: obspy>=1.4.0; extra == "seismic-raw"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: all
Requires-Dist: pygimli<2.0,>=1.5.5; extra == "all"
Requires-Dist: simpeg<1.0,>=0.24; extra == "all"
Requires-Dist: flopy<4.0,>=3.5; extra == "all"
Requires-Dist: pftools>=1.3; extra == "all"
Requires-Dist: cupy-cuda11x; extra == "all"
Requires-Dist: openai; extra == "all"
Requires-Dist: google-generativeai; extra == "all"
Requires-Dist: anthropic; extra == "all"
Requires-Dist: pydaymet>=0.16.0; extra == "all"
Requires-Dist: pandas>=1.3.0; extra == "all"
Requires-Dist: xarray>=0.19.0; extra == "all"
Requires-Dist: streamlit<2.0,>=1.35; extra == "all"
Requires-Dist: plotly<7.0,>=5.18; extra == "all"
Requires-Dist: streamlit-plotly-events>=0.0.6; extra == "all"
Requires-Dist: pyarrow>=14.0; extra == "all"
Requires-Dist: obspy>=1.4.0; extra == "all"
Requires-Dist: PySide6>=6.5; extra == "all"
Requires-Dist: pyqtgraph>=0.13; extra == "all"
Requires-Dist: sphinx>=5.0; extra == "all"
Requires-Dist: sphinx-gallery; extra == "all"
Requires-Dist: sphinx_rtd_theme; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: pytest-cov; extra == "all"
Requires-Dist: black; extra == "all"
Requires-Dist: flake8; extra == "all"
Dynamic: license-file

﻿[![tests](https://github.com/geohang/PyHydroGeophysX/actions/workflows/tests.yml/badge.svg)](https://github.com/geohang/PyHydroGeophysX/actions/workflows/tests.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17025139.svg)](https://doi.org/10.5281/zenodo.17025139)

<div align="center">
  <img src="logo.png" alt="PyHydroGeophysX Logo" width="400">
</div>

# PyHydroGeophysX

A Python package for integrating hydrological model outputs (MODFLOW, ParFlow) with geophysical forward modeling and inversion — ERT, SRT, TDEM, FDEM — for watershed monitoring and critical zone science. Includes a multi-agent AI system for automated geophysical workflows.

<div align="center">
  <img src="frame.png" alt="HydroGeophysX Framework" width="600">
</div>

**Links:** [Documentation](https://geohang.github.io/PyHydroGeophysX/) · [Examples gallery](https://geohang.github.io/PyHydroGeophysX/auto_examples/index.html) · [Live demo app](https://pyhydrogeophysx.streamlit.app/) · [Issues](https://github.com/geohang/PyHydroGeophysX/issues)

---

## Features

- **Hydrological model integration** — load MODFLOW and ParFlow outputs
- **ERT data processing** — field data QC, export, and RESIPY integration
- **Forward modeling** — 2D/3D ERT, SRT, TDEM, FDEM synthetic data generation
- **Inversion** — single-time, time-lapse, windowed, structure-constrained, joint ERT+SRT, TDEM, FDEM
- **Petrophysics** — water content ↔ resistivity (Waxman-Smits/Archie), seismic velocity (Hertz-Mindlin, DEM)
- **Uncertainty quantification** — Monte Carlo for petrophysical parameter uncertainty
- **Multi-agent AI system** — automated workflows via GPT, Gemini, or Claude APIs
- **GPU acceleration** — optional CuPy/CUDA support for large-scale inversions

---

## Installation

### Recommended (conda — handles binary deps for PyGIMLi)

```bash
conda env create -f environment.yml
conda activate pyhydrogeophysx
```

### From PyPI

```bash
# Core only (petrophysics, model I/O, solvers)
pip install pyhydrogeophysx

# With geophysics engines (ERT/SRT/TDEM/FDEM inversion and forward modeling)
pip install "pyhydrogeophysx[geophysics]"

# With AI agent support
pip install "pyhydrogeophysx[geophysics,agents]"

# With web app
pip install "pyhydrogeophysx[geophysics,webapp]"

# Everything
pip install "pyhydrogeophysx[all]"
```

> **Note on PyGIMLi:** PyGIMLi links against C++ libraries. If `pip install` fails, install it first via conda:
> ```bash
> conda install -c gimli pygimli
> pip install "pyhydrogeophysx[agents]"  # then add other extras
> ```

### From Source

```bash
git clone https://github.com/geohang/PyHydroGeophysX.git
cd PyHydroGeophysX
pip install -e ".[geophysics]"
```

### Optional extras

| Extra | Packages installed |
|---|---|
| `geophysics` | pygimli, simpeg, flopy, pftools |
| `agents` | openai, google-generativeai, anthropic |
| `climate` | pydaymet, pandas, xarray |
| `webapp` | streamlit, pandas, plotly, streamlit-plotly-events |
| `gpu` | cupy-cuda11x |
| `dev` | pytest, pytest-cov, black, flake8 |
| `all` | all of the above |

---

## Running the apps

**Web app (Streamlit):**

```bash
streamlit run examples/app_geophysics_workflow.py
```

**Desktop workbench (Qt):**

```bash
python -m PyHydroGeophysX.qt_apps.launcher
# or, after (re)installing the package:
pyhydrogeophysx-workbench
```

Desktop dependencies come from the `desktop` extra (`pip install "pyhydrogeophysx[desktop]"`) or `requirements-desktop.txt`. See `docs/desktop_workbench.md` for details.

---

## Package Structure

```
PyHydroGeophysX/
├── core/               # Interpolation, 2D/3D mesh utilities
├── agents/             # Multi-agent AI orchestration
├── data_processing/    # ERT field data loading, QC, export
├── model_output/       # MODFLOW and ParFlow interfaces
├── petrophysics/       # Resistivity and velocity rock-physics models
├── forward/            # ERT, SRT, TDEM, FDEM forward modeling
├── inversion/          # ERT, SRT, TDEM, FDEM, joint, time-lapse inversion
├── solvers/            # CGLS, LSQR, RRLS linear solvers (optional GPU)
├── Hydro_modular/      # Hydro-to-geophysics conversion utilities
└── Geophy_modular/     # Geophysical data processing tools
```

---

## Examples

All examples have paired `.ipynb` notebooks and `.py` scripts under `examples/`. Data is in `examples/data/`, outputs go to `examples/results/`.

| Example | Description |
|---|---|
| `Ex_ERT_data_process` | Field ERT loading, QC, RESIPY export |
| `Ex_model_output` | MODFLOW/ParFlow output loading |
| `Ex_ERT_workflow` | End-to-end ERT forward + inversion |
| `Ex_Time_lapse_measurement` | Synthetic time-lapse ERT schedules |
| `Ex_TL_inversion` | Time-lapse ERT inversion |
| `Ex_Structure_resinv` | Structure-constrained resistivity inversion |
| `Ex_structure_TLresinv` | Structure-constrained time-lapse inversion |
| `EX_SRT_forward` | SRT forward modeling |
| `Ex_SRT_inv` | SRT inversion (PyGIMLi + packaged `SRTInversion`) |
| `Ex_joint_inversion` | Joint ERT+SRT inversion |
| `Ex_cross_constraints` | Cross-gradient / structural constraints |
| `Ex_3D_ERT_forward` | 3D ERT forward with MODFLOW integration |
| `Ex_TDEM_workflow` | TDEM forward + inversion (SimPEG) |
| `Ex_FDEM_workflow` | FDEM forward + inversion (SimPEG) |
| `Ex_hydro_to_multigeophys` | Hydro → petrophysics → multi-method forward |
| `Ex_MC_Hydro` | Monte Carlo uncertainty quantification |
| `Ex_multi_agent_workflow` | Automated multi-agent ERT+seismic workflow |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Standard fork → feature branch → PR workflow.

---

## Citation

If you use PyHydroGeophysX, please cite:

```bibtex
@article{chen2026pyhydrogeophysx,
  author  = {Chen, Hang and Niu, Qifei and Wu, Yuxin},
  title   = {PyHydroGeophysX: An Extensible Open-Source Platform for Integrating
             Hydrological Models with Geophysical Measurements},
  journal = {SoftwareX},
  year    = {2026},
  note    = {In press},
  url     = {https://github.com/geohang/PyHydroGeophysX}
}
```

```bibtex
@article{chen2026agentworkflow,
  author  = {Chen, Hang},
  title   = {A Generalizable Automated Geophysical Agent Workflow for
             Accessible Subsurface Hydrology Analysis},
  journal = {Big Data and Earth System},
  pages   = {100042},
  year    = {2026}
}
```

Please also cite the underlying libraries you use:

**ERT data processing (ResIPy):**
```bibtex
@article{blanchy2020resipy,
  title   = {ResIPy, an intuitive open source software for complex geoelectrical inversion/modeling},
  author  = {Blanchy, Guillaume and Saneiyan, Sina and Boyd, Jimmy and McLachlan, Paul and Binley, Andrew},
  journal = {Computers \& Geosciences},
  volume  = {137},
  pages   = {104423},
  year    = {2020},
  doi     = {10.1016/j.cageo.2020.104423}
}
```

**Geophysical modeling (PyGIMLi):**
```bibtex
@article{rucker2017pygimli,
  title   = {pyGIMLi: An open-source library for modelling and inversion in geophysics},
  author  = {R{\"u}cker, Carsten and G{\"u}nther, Thomas and Wagner, Florian M},
  journal = {Computers \& Geosciences},
  volume  = {109},
  pages   = {106--123},
  year    = {2017},
  doi     = {10.1016/j.cageo.2017.07.011}
}
```

**EM modeling (SimPEG):**
```bibtex
@article{cockett2015simpeg,
  title   = {SimPEG: An open source framework for simulation and gradient based parameter estimation in geophysical applications},
  author  = {Cockett, Rowan and Kang, Seogi and Heagy, Lindsey J and Pidlisecky, Adam and Oldenburg, Douglas W},
  journal = {Computers \& Geosciences},
  volume  = {85},
  pages   = {142--154},
  year    = {2015},
  doi     = {10.1016/j.cageo.2015.09.015}
}
```

**Hydrological modeling (FloPy / MODFLOW):**
```bibtex
@article{bakker2016flopy,
  title   = {Scripting MODFLOW Model Development Using Python and FloPy},
  author  = {Bakker, Mark and Post, Vincent and Langevin, Christian D and Hughes, Joseph D and White, Jeremy T and Starn, J Jeffrey and Fienen, Michael N},
  journal = {Groundwater},
  volume  = {54},
  number  = {5},
  pages   = {733--739},
  year    = {2016},
  doi     = {10.1111/gwat.12413}
}
```

**Related geophysics-hydrology study:**

- Chen, H., Niu, Q., Mendieta, A., Bradford, J., & McNamara, J. (2023). Geophysics-informed hydrologic modeling of a mountain headwater catchment for studying hydrological partitioning in the critical zone. *Water Resources Research, 59*(12), e2023WR035280. https://doi.org/10.1029/2023WR035280
