This repository demonstrates the GAGAW (Generalizable Automated Geophysical Agent Workflow) framework applied to hydrogeophysics, implemented as AQUAH within PyHydroGeophysX.
GAGAW is a generalizable automated geophysical agent workflow framework for subsurface characterization (Chen, 2025, Geophysical Research Letters, under review). AQUAH represents the hydrogeophysics-specific implementation of GAGAW, providing:
- 🤖 AI-Powered Multi-Agent System built on the GAGAW framework
- 🌊 Hydrogeophysics Focus for subsurface water content and hydrological properties
- 🗣️ Natural Language Interface for intuitive workflow descriptions
- 🔄 Three Workflow Types optimized for hydrological applications
AQUAH provides a revolutionary natural language interface to complex geophysical workflows. Simply describe your analysis goals in plain English, and AQUAH automatically:
- Interprets your requirements using advanced LLMs (GPT-4, Gemini, Claude)
- Selects appropriate processing workflows and parameters
- Executes multi-method data fusion (ERT, seismic, climate data)
- Generates comprehensive reports with uncertainty quantification
No programming expertise required - just describe what you want to analyze!
- 🤖 Natural Language Interface: Describe workflows in plain English - no coding required
- 🌐 Web Application: User-friendly Streamlit interface for drag-and-drop analysis
- 📊 Three Workflow Types: Standard ERT, Time-Lapse, and Multi-Method Data Fusion
- 🔄 Automatic Workflow Detection: AQUAH intelligently determines the analysis type from your description
- ⏱️ Time-Lapse Analysis: Monitor temporal changes with climate data integration (precipitation, PET)
- 🔬 Uncertainty Quantification: Monte Carlo methods with layer-specific parameter distributions
- 🏔️ Structure-Constrained Inversion: Use seismic interfaces to guide ERT inversion
- 🎯 AI-Powered Interpretation: LLM-generated insights and recommendations
- 📝 Automated Reporting: Comprehensive reports with visualizations and metadata
GAGAW_Hydrogeophysics/
├── app_geophysics_workflow.py # 🌐 Streamlit Web Application (AQUAH Interface)
├── Ex_Unified_Workflow.ipynb # Example 1: Standard ERT Workflow
├── Ex_Unified_Workflow_ex2.ipynb # Example 2: Time-Lapse ERT with Climate
├── Ex_Unified_Workflow_ex3.ipynb # Example 3: Multi-Method Data Fusion
├── detail_explaination_code/ # Legacy detailed workflow examples
│ ├── direct_ERT_converion.ipynb # Step-by-step ERT conversion
│ ├── Ex_DataFusion_NaturalLanguage.ipynb
│ └── Ex_TimeLapse_NaturalLanguage.ipynb
├── data/ # Example geophysical data
│ ├── climate/ # Climate data and PET estimates
│ ├── ERT/ # Electrical resistivity data
│ │ ├── Bert/ # BERT format field data
│ │ ├── DAS/ # DAS-1 instrument data
│ │ └── E4D/ # E4D format time-series
│ └── Seismic/ # Seismic refraction travel times
└── results/ # Processing results
└── unified_workflow/ # AQUAH workflow outputs
├── example_1/ # Standard ERT results
├── example2/ # Time-lapse results
└── example3/ # Data fusion results
- Python Environment: Python 3.8 or higher
- PyHydroGeophysX: The main dependency
pip install pyhydrogeophysx
- LLM API Key: Get an API key from one of:
-
Clone this repository:
git clone https://github.com/yourusername/GAGAW_Hydrogeophysics.git cd GAGAW_Hydrogeophysics -
Install dependencies:
pip install -r requirements.txt
-
Set your API key as an environment variable:
# For OpenAI export OPENAI_API_KEY='your-api-key-here' # For Gemini export GEMINI_API_KEY='your-api-key-here' # For Claude export ANTHROPIC_API_KEY='your-api-key-here'
AQUAH provides a user-friendly web interface built with Streamlit, making geophysical analysis accessible without coding.
Features:
- 📝 Natural Language Input: Describe your workflow in a text box
- 📤 File Upload: Drag-and-drop ERT data, seismic data, and electrode files
- 🔄 Automatic Detection: AQUAH automatically identifies workflow type
- ⚙️ Multiple LLM Support: Choose between OpenAI (GPT-4), Google (Gemini), or Anthropic (Claude)
- 📊 Results Dashboard:
- AI-generated interpretation and insights
- Execution plan visualization
- Key metrics (resistivity range, water content, model quality)
- Interactive plots and visualizations
- 💾 Download Results: One-click download of reports, models, and figures
How to Use:
-
Launch the app:
cd GAGAW_Hydrogeophysics streamlit run app_geophysics_workflow.pyThe web app will open in your browser at
http://localhost:8501 -
Configure (in sidebar):
- Select LLM provider (OpenAI/Gemini/Claude)
- Enter API key
- Set output directory
- Click "Initialize System"
-
Describe your workflow:
Example: "Run time-lapse ERT on 4 E4D files from March to June 2022. Fetch climate data for coordinates (38.93°N, -107.0°W). Apply temporal regularization of 10." -
Upload files (optional):
- ERT data files (.ohm, .dat, .Data)
- Seismic data (.dat, .txt)
- Electrode positions (.dat, .txt)
-
Run and download results!
AQUAH web interface showing Configuration panel, Natural Language input area, and file upload zones
For programmatic access or to understand the internals:
# Standard ERT workflow
jupyter notebook Ex_Unified_Workflow.ipynb
# Time-lapse with climate integration
jupyter notebook Ex_Unified_Workflow_ex2.ipynb
# Multi-method data fusion
jupyter notebook Ex_Unified_Workflow_ex3.ipynbAQUAH supports three main workflow types, each accessible through natural language or the web interface:
Notebook: Ex_Unified_Workflow.ipynb
Best For: Single ERT dataset → resistivity model → water content estimation
Example Natural Language Request:
We have ERT data from DAS-1 instrument at examples/data/ERT/DAS/20171105_1418.Data
with electrode file at examples/data/ERT/DAS/electrodes.dat in the Snowy Range,
southeastern Wyoming. The bedrock consists of foliated gneiss in the Cheyenne Belt.
Use petrophysical parameters: rho_sat=541, porosity=0.37, n=1.24
What AQUAH Does:
- Loads ERT data (supports E4D, BERT, DAS, Syscal formats)
- Incorporates topography from electrode file
- Runs resistivity inversion with appropriate regularization
- Converts to water content using specified or estimated petrophysical parameters
- Performs Monte Carlo uncertainty quantification (100 realizations)
- Generates comprehensive report with visualizations
Key Features:
- ✅ Automatic instrument detection
- ✅ Topography incorporation
- ✅ Petrophysical parameter extraction from site descriptions
- ✅ Uncertainty quantification
- ✅ Quality metrics and coverage analysis
Notebook: Ex_Unified_Workflow_ex2.ipynb
Best For: Monitoring temporal changes in subsurface moisture with climate context
Example Natural Language Request:
Run TIME-LAPSE ERT inversion to monitor moisture infiltration.
DATA FILES (4 E4D format files in data/ERT/E4D):
- Baseline: 2022-03-26_0030.ohm
- Time 2: 2022-04-26_0030.ohm
- Time 3: 2022-05-26_0030.ohm
- Time 4: 2022-06-26_0030.ohm
INVERSION SETTINGS:
- Inversion Type: TIME-LAPSE (difference method)
- Temporal Regularization: 10
- Spatial Lambda: 15
CLIMATE INTEGRATION:
- Site: Mt. Snodgrass, Colorado (38.92584°N, -106.97998°W)
- Date Range: March 2022 to June 2022
- Variables: precipitation, temperature, solar radiation, PET
- Method: Penman-Monteith PET calculation
What AQUAH Does:
- Loads multiple time-lapse ERT datasets with automatic date extraction
- Runs temporal inversion with difference method and temporal regularization
- Fetches climate data from DayMet API (automatic conda environment setup)
- Computes potential evapotranspiration (PET) using Penman-Monteith
- Aligns climate data with ERT acquisition timestamps
- Generates time-series plots correlating resistivity changes with weather
- Creates comprehensive temporal analysis report
Key Features:
- ✅ Automatic time-lapse detection from multiple files
- ✅ Climate data integration (DayMet, OpenMeteo)
- ✅ PET computation with multiple methods
- ✅ Antecedent precipitation analysis
- ✅ Temporal regularization for smooth changes
- ✅ Climate-hydrology correlation plots
Notebook: Ex_Unified_Workflow_ex3.ipynb
Best For: Integrating seismic and ERT data for structure-constrained hydrogeological analysis
Example Natural Language Request:
Characterize subsurface water content using multi-method data fusion:
1. Use field seismic refraction data at data/Seismic/srtfieldline2.dat
- Identify boundary between regolith and fractured bedrock
- Velocity threshold: 1000 m/s for interface extraction
2. Use seismic structure to constrain ERT inversion
- ERT data: data/ERT/Bert/fielddataline2.dat
- Lambda: 20 (moderate regularization with structural constraints)
3. Convert to water content with layer-specific petrophysics:
REGOLITH LAYER:
- rho_sat: 50-250 Ωm
- n: 1.3-2.2
- porosity: 0.25-0.5
FRACTURED BEDROCK LAYER:
- rho_sat: 165-350 Ωm
- n: 2.0-2.2
- porosity: 0.2-0.3
4. Monte Carlo uncertainty: 100 realizations
What AQUAH Does:
- Processes seismic refraction data → velocity model
- Extracts geological interface at specified velocity threshold
- Creates ERT mesh with seismic-derived structural constraints
- Runs structure-constrained ERT inversion with interface boundaries
- Converts resistivity to water content using layer-specific petrophysical models
- Performs Monte Carlo uncertainty quantification for each layer
- Generates comprehensive data fusion report with multi-panel visualizations
Key Features:
- ✅ Automatic multi-method detection (seismic + ERT)
- ✅ Interface extraction from velocity gradients
- ✅ Structure-constrained inversion with geological boundaries
- ✅ Layer-specific petrophysical parameter distributions
- ✅ Cross-method validation and consistency checking
- ✅ Comprehensive uncertainty propagation through workflow
The repository includes field geophysical datasets to demonstrate AQUAH workflows:
- ERT Data: Multiple formats (BERT, E4D, DAS-1) from field sites in Wyoming and Colorado
- Seismic Data: First-arrival travel times for refraction tomography
- Climate Data: Sample climate data and configuration for Mt. Snodgrass monitoring site
These datasets allow you to:
- Test AQUAH's natural language understanding
- Explore automatic workflow detection
- Compare different workflow types
- Evaluate uncertainty quantification methods
- Learn best practices for describing geophysical workflows
ERT measures subsurface electrical resistivity by injecting current and measuring voltage. Resistivity is sensitive to:
- Water content (higher water → lower resistivity)
- Salinity (higher ions → lower resistivity)
- Temperature (higher temp → lower resistivity)
- Geological structure (clay vs sand vs bedrock)
Convert resistivity (ρ) to water content (θ) using the Waxman-Smits model:
Monte Carlo sampling accounts for:
- Measurement noise in resistivity
- Uncertainty in petrophysical parameters (porosity, cementation exponent)
- Spatial variability in geological properties
- Model resolution and regularization effects
AQUAH uses a hierarchical multi-agent system powered by large language models:
Natural Language Request
↓
ContextInputAgent (LLM-powered parsing)
↓
BaseAgent.run_unified_agent_workflow()
↓
WorkflowOrchestratorAgent (determines workflow type)
↓
┌────┴────┬─────────────────┐
↓ ↓ ↓
Standard Time-Lapse Data Fusion
ERT ERT Workflow
↓ ↓ ↓
└────┬────┴────┬────────────┘
↓ ↓
Results Reports
- ContextInputAgent: Parses natural language → structured configuration
- WorkflowOrchestratorAgent: Detects workflow type and orchestrates execution
- ERTLoaderAgent: Handles multi-format ERT data loading
- ERTInversionAgent: Manages resistivity inversion
- TimeLapseAgent: Coordinates temporal analysis
- SeismicAgent: Processes seismic refraction data
- StructureConstraintAgent: Implements structure-constrained inversion
- PetrophysicsAgent: Converts resistivity to hydrological properties
- ClimateDataAgent: Fetches and processes meteorological data
- ReportAgent: Generates comprehensive analysis reports
AQUAH automatically detects workflow type based on:
| Workflow Type | Detection Criteria |
|---|---|
| Standard ERT | Single ERT file, no time-lapse/fusion keywords |
| Time-Lapse | Multiple ERT files OR "time-lapse" keyword |
| Data Fusion | Seismic + ERT files OR "structure" keyword |
AQUAH workflow results are saved in results/unified_workflow/:
results/unified_workflow/example_X/
├── inversion/
│ ├── resistivity_model.npy # Inverted resistivity model
│ ├── coverage.npy # Data coverage/sensitivity
│ └── inversion_quality.json # Chi-squared, RMS, iterations
├── petrophysics/
│ ├── water_content_mean.npy # Mean water content
│ ├── water_content_std.npy # Uncertainty (standard deviation)
│ ├── saturation_mean.npy # Mean saturation
│ └── mc_parameters.json # Monte Carlo parameter distributions
├── climate/ (time-lapse only)
│ ├── climate_data.csv # Daily meteorological data
│ ├── climate_config.json # DayMet configuration
│ └── pet_timeseries.csv # Potential evapotranspiration
├── structure/ (data fusion only)
│ ├── seismic_velocity.npy # Velocity model
│ ├── interface_coords.npy # Extracted interface positions
│ └── constrained_mesh.bms # Structure-constrained mesh
├── visualizations/
│ ├── resistivity_section.png # Resistivity cross-section
│ ├── water_content_uncertainty.png # Water content with uncertainty
│ ├── temporal_changes.png # Time-series (time-lapse)
│ └── multi_method_fusion.png # Integrated view (data fusion)
└── reports/
├── workflow_report.md # Comprehensive markdown report
├── workflow_report.html # HTML version
├── execution_plan.json # Agent execution sequence
└── interpretation.txt # LLM-generated insights
Standard ERT:
- Resistivity cross-sections with topography
- Water content distributions with uncertainty bounds
- Data coverage and quality metrics
- Petrophysical parameter sensitivity plots
Time-Lapse:
- Temporal resistivity changes (difference plots)
- Climate correlation plots (precipitation, PET)
- Time-series evolution animations
- Antecedent precipitation analysis
Data Fusion:
- Seismic velocity models with extracted interfaces
- Structure-constrained ERT results
- Layer-specific water content distributions
- Multi-panel integrated visualizations
- Cross-method consistency plots
Contributions are welcome! This repository demonstrates practical applications of PyHydroGeophysX. If you have:
- Additional field datasets to include
- Improved workflow configurations
- Bug fixes or enhancements
- Documentation improvements
Please open an issue or submit a pull request.
If you use AQUAH or these workflows in your research, please cite:
GAGAW Framework (Primary Citation):
@article{chen2025gagaw,
author = {Chen, Hang},
title = {A Generalizable Automated Geophysical Agent Workflow in Subsurface Hydrology},
journal = {Geophysical Research Letters},
year = {2025},
note = {under review}
}PyHydroGeophysX Package (Software Implementation):
@software{chen2025pyhydrogeophysx,
author = {Chen, Hang and Niu, Qifei and Wu, Yuxin},
title = {PyHydroGeophysX: An Extensible Open-Source Platform for Bridging
Hydrological Models and Geophysical Measurements},
year = {2025},
publisher = {Water Resources Research (under review)},
url = {https://github.com/geohang/PyHydroGeophysX}
}AQUAH Demonstration Repository (Applications):
@software{gagaw2025aquah,
author = {Chen, Hang},
title = {GAGAW Hydrogeophysics: AQUAH (Autonomous Query-driven Understanding Agent
for Hydrogeophysics) - Demonstration Workflows},
year = {2025},
publisher = {GitHub},
url = {https://github.com/geohang/GAGAW_Hydrogeophysics},
note = {Implementation of GAGAW framework for hydrogeophysical applications}
}This project is licensed under the Apache License 2.0 - the same license as PyHydroGeophysX. See the LICENSE file for details.
- PyHydroGeophysX development team for the multi-agent framework
- PyGIMLi for geophysical modeling and inversion
- RESIPY developers for ERT data processing
- OpenAI, Google DeepMind, and Anthropic for LLM APIs powering AQUAH's natural language understanding
- Streamlit team for the web application framework
- DayMet and Open-Meteo for climate data APIs
- Open-source scientific Python community (NumPy, SciPy, Matplotlib, pandas)
Data in this repository comes from:
- Mt. Snodgrass Monitoring Site (Crested Butte, CO) - Time-lapse ERT and climate data
- Snowy Range Field Site (Wyoming) - Standard ERT and multi-method fusion data
For questions about AQUAH:
- Issues: Open an issue in this repository
- Email: [email protected]
- PyHydroGeophysX: Visit the main repository
For collaboration or custom workflows:
- Contact the development team through GitHub issues or email
- OpenAI API - GPT-4, GPT-3.5
- Google AI - Gemini Pro
- Anthropic - Claude
- DayMet - North American daily meteorological data
- Open-Meteo - Global weather API
This repository demonstrates AQUAH - the hydrogeophysics-specific implementation of the GAGAW framework.
The GAGAW (Generalizable Automated Geophysical Agent Workflow) framework provides a generalizable approach to automated geophysical data processing across different applications. AQUAH implements GAGAW specifically for hydrogeophysical analysis, focusing on subsurface water content and hydrological property estimation.
The included field datasets from Wyoming and Colorado are for demonstration and educational purposes. AQUAH can be applied to any ERT, seismic, or multi-method geophysical dataset with appropriate configuration.
Ready to try AQUAH? Start with the web application (streamlit run app_geophysics_workflow.py) or explore the Jupyter notebook examples!
Last Updated: 2025 | GAGAW Framework | AQUAH Version: 1.0 | PyHydroGeophysX: v0.1.0