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
- 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
conda env create -f environment.yml
conda activate pyhydrogeophysx# 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 installfails, install it first via conda:conda install -c gimli pygimli pip install "pyhydrogeophysx[agents]" # then add other extras
git clone https://github.com/geohang/PyHydroGeophysX.git
cd PyHydroGeophysX
pip install -e ".[geophysics]"| 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 |
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
All examples have paired .ipynb notebooks and .py scripts under examples/. Data is in examples/data/, outputs go to examples/results/.
| Example | Description |
|---|---|
Ex_hello_agent |
ERT hello-world, no API key needed |
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 |
See CONTRIBUTING.md. Standard fork → feature branch → PR workflow.
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