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.

Links: Documentation · Examples gallery · Live demo app · 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)

conda env create -f environment.yml
conda activate pyhydrogeophysx

From PyPI

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

conda install -c gimli pygimli
pip install "pyhydrogeophysx[agents]"  # then add other extras

From Source

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):

streamlit run examples/app_geophysics_workflow.py

Desktop workbench (Qt):

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. Standard fork → feature branch → PR workflow.

---

Citation

If you use PyHydroGeophysX, please cite:

@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}
}

@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):

@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):

@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):

@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):

@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