Physics-Informed Machine Learning for Soil Water Modeling

This repository implements physics-informed neural networks (PINNs) and a DeepONet for one-dimensional unsaturated soil water flow governed by the Richards equation. The main implementation lives in piml_models/, where three complementary approaches are provided:

Model	Directory	Purpose
Forward PINN	piml_models/forward_pinn/	Solve the Richards equation for a fixed upper-boundary flux and soil parameters
Inverse PINN	piml_models/inverse_pinn/	Estimate Mualem-van Genuchten hydraulic parameters from sparse synthetic data
DeepONet	piml_models/deepONet/	Learn a solution operator that generalizes over upper-boundary flux functions (Gaussian infiltration scenarios)

Reference solutions from HYDRUS-1D are stored under hydrus_data/ and used for validation and data-driven terms in the loss.

Overview

Physics-informed neural networks embed governing PDEs, initial conditions, and boundary conditions directly into the training loss, so the network respects hydrological physical laws even where data are sparse.

The DeepONet extends this idea: a branch network encodes the upper-boundary flux (sampled at sensor locations in time), and a trunk network maps spatial–temporal coordinates $(z, t)$ to matric head. Once trained, a single model can predict the matric head for new flux scenarios without re-solving the PDE from scratch.

All three models use Mualem-van Genuchten constitutive relations, nondimensionalization of the Richards equation, and MLflow for experiment tracking.

Richards Equation

The (mixed-form) Richards equation is:

$$\frac{\partial \theta}{\partial t} = \frac{\partial}{\partial z} \left[ K(\psi) \left( \frac{\partial \psi}{\partial z} + 1 \right) \right]$$

where:

• $\theta$ — volumetric water content [m³/m³]
• $\psi$ — matric head [m]
• $z$ — depth (positive upward) [m]
• $t$ — time [days]
• $K(\psi)$ — hydraulic conductivity [m/days]

Constitutive relations (Mualem-van Genuchten) link $\theta(\psi)$ and $K(\psi)$ to close the system.

piml_models/ — Model Implementations

Each subdirectory is a self-contained training pipeline with main.py as the entry point.

Forward PINN (forward_pinn/)

• Solves the Richards equation for prescribed initial and boundary conditions and fixed soil hydraulic parameters.
• Physics loss: PDE residual, initial condition, upper/lower boundary fluxes.
• Comparison against HYDRUS output.
• Sensitivity analysis via main_sensitivity.py.

Inverse PINN (inverse_pinn/)

• Treats van Genuchten parameters $(\alpha, n, K_s)$ as learnable quantities alongside the neural network weights.
• Combines physics loss with sparse matric head data (from HYDRUS).
• Useful for parameter estimation when direct laboratory measurements are limited.

DeepONet (deepONet/)

• Branch subnet: encodes the upper-boundary flux function $q(t)$ at fixed sensor times.
• Trunk subnet: maps $(z, t)$ to matric head $\psi$.
• Trained on families of Gaussian flux scenarios parameterized by $(a, b)$ see rain.py for flux definitions.
• Enables fast inference for unseen boundary conditions after training.

Shared utilities in each package include model.py, losses.py, sampling.py, train.py, soilFunctions.py, readHydrus.py, and configurator.py.

Repository Structure

pinn_soil_water_model/
├── README.md
├── requirements.txt
├── piml_models/              # Main implementations (PINNs + DeepONet)
│   ├── forward_pinn/
│   ├── inverse_pinn/
│   └── deepONet/
├── hydrus_data/                # HYDRUS-1D reference simulations
│   ├── constantUB/
│   ├── gaussianTrain/
│   ├── gaussianTest/
│   └── ...
├── notebooks/                  # Exploratory notebooks and tutorials
├── plots/                      # Figures for thesis / reports
└── evaluation/                 # Saved evaluation outputs

Getting Started

1. Install dependencies

   pip install -r requirements.txt

   Core packages: PyTorch, NumPy, pandas, matplotlib, scikit-learn, MLflow.

2. Run a model (from the respective subdirectory)

   cd piml_models/forward_pinn
   python main.py

   cd piml_models/inverse_pinn
   python main.py

   cd piml_models/deepONet
   python main.py

   Each run logs hyperparameters, metrics, and artifacts to a local MLflow database (mlflow.db in that directory).

3. HYDRUS data — Ensure reference .out files are present under hydrus_data/ before training models that load numerical solutions.

Typical Use Cases

• Forward simulation: PINN solution for a single boundary flux and soil type.
• Parameter estimation: Inverse PINN to infer hydraulic properties from $\psi(z,t)$ observations.
• Operator learning: DeepONet surrogate for rapid scenario analysis over varying rainfall / irrigation fluxes.
• Validation: Compare PIML predictions against HYDRUS-1D and published soil hydraulic curves.

References

• Raissi, M., Perdikaris, P., & Karniadakis, G. E. (2019). Physics-informed neural networks: A deep learning framework for solving forward and inverse problems involving nonlinear partial differential equations. Journal of Computational Physics.
• Lu, L., Jin, P. & Karniadakis, G. E. (2021). DeepONet: Learning nonlinear operators for identifying differential equations based on the universal approximation theorem of operators. Nature Machine Intelligence.
• Bittelli, M., Campbell, G. S., & Tomei, F. (2015). Soil Physics with Python: Transport in the Soil–Plant–Atmosphere System. Oxford University Press.

---