Hydrosheaf: Sheaf-Theoretic Methods in Groundwater Hydrogeochemistry

Abstract

Overview Hydrosheaf is a Python-based framework for solving inverse problems in groundwater hydrogeochemistry. It determines optimal transport processes (evaporation, mixing) and geochemical reactions that explain observed chemical evolution along flow paths in aquifer networks. The framework integrates: Weighted Least Squares Optimization for transport model selection. Sparse LASSO Regression with coordinate descent for parsimonious reaction fitting. Thermodynamic Constraints utilizing PHREEQC for saturation index calculations. Isotope Hydrogeology for independent process validation (Deuterium Excess, LMWL). Graph Theory for probabilistic flow network inference. Features Transport Modeling: Distinguishes between evaporation (Rayleigh distillation-like) and end-member mixing. Reaction Path Modeling: Identifies mineral dissolution/precipitation, redox reactions (denitrification), and ion exchange. Sparsity: Uses L1 regularization to find the simplest chemical explanation for observed data. Physical Consistency: Enforces thermodynamic bounds (e.g., minerals cannot precipitate from undersaturated solutions). Network Inference: Infers flow direction probabilities from hydraulic head data with uncertainty. Nitrate Source Discrimination: Distinguishes between manure and fertilizer sources using a hybrid approach: Dual Isotope Bayesian Mixing ($\delta^{15}\text{N}, \delta^{18}\text{O}$) prioritized over CoDA-based hydrochemical statistics. Reactive Transport: Validates inverse results against kinetic rate laws (Arrhenius) and Damköhler numbers. 3D Flow Networks: Analyzes layered aquifer systems with vertical anisotropy and topographic Bayesian priors. Temporal Dynamics: Resolves time-variant signals with cross-correlation residence times and seasonal decomposition. Uncertainty Quantification: Provides rigorous confidence intervals via Bayesian MCMC (NUTS) and Bias-Corrected Bootstrap (BCa). Web Application: Full-stack web interface with FastAPI backend and React frontend that supports Real-time Analysis monitoring via WebSockets. Verified Documentation: All mathematical examples in the technical reference are computationally verified by the test suite. Full Changelog: https://github.com/dabdul-wahab1988/Hydrosheaf/compare/0.3.0...0.5.0