Richards2D-DL 💧

Deep learning for transient water infiltration in heterogeneous two-dimensional soil sections.

A qualified Richards-equation reference, a scenario-independent synthetic corpus, a selected time-conditioned U-Net, and portable inference with explicit applicability checks.

🔗 Quick Links

📋 Table of Contents

Overview
Repository Structure
Installation
Quick Start
Scientific Formulation
Numerical Reference
Corpus and Data Contract
Deep-Learning Model
Validated Results
Visual Results
Reusable Inference
Validation and Reproducibility
Scientific and Software Provenance
Limitations
How to Cite
Research Team
Industry Partners
License and Rights
Acknowledgments
Contact and Support
FAQ

🌟 Overview

Richards2D-DL approximates the early-time evolution of water content in a vertical, heterogeneous, two-dimensional soil section. Its numerical reference solves the mixed form of the Richards equation with van Genuchten--Mualem hydraulic relations. A time-conditioned U-Net then maps the hydraulic setting, the heterogeneous saturated-conductivity field, depth, and query time to a bounded field of effective saturation.

The repository contains the complete release needed to inspect or use the selected model: a prospectively locked protocol, a 208-scenario numerical corpus, scenario-level development and evaluation partitions, the selected PyTorch checkpoint, its preprocessing contract, portable inference code, qualification records, retained figures, and independent validators.

The evidence supports a deliberately bounded claim:

Richards2D-DL is validated for nine snapshots over the first two hours of infiltration on a 1.20 m x 0.80 m, 36 x 24 cell domain, for the four documented textural soil classes and the qualified parameter envelope.

Inputs outside that support can be executed only through an explicit override. Such predictions are marked as unsupported extrapolations and do not inherit the quantitative performance reported here.

🔧 Key Capabilities

💧 Nonlinear unsaturated flow: mixed-form Richards dynamics with pressure-dependent storage and hydraulic conductivity.
🗺️ Two spatial dimensions: heterogeneous conductivity produces lateral as well as vertical variation in infiltration fronts.
🌱 Four textural classes: sandy loam, loam, silt loam, and clay loam parameterized from published class averages.
🔒 Scenario-level separation: all nine snapshots from one scenario remain together in training, validation, test, or challenge.
🧠 Time-conditioned prediction: one compact U-Net evaluates any of the documented query times without autoregressive rollout.
🛡️ Bounded output: the network preserves the initial state exactly and constrains effective saturation to [0, 1] by construction.
⚡ Fast repeated queries: a warm nine-snapshot trajectory required a median of 4.43 ms in the retained Apple MPS timing experiment.
📦 Portable inference: the selected model can run without loading SimPEG, discretize, or the Richards reference solver.
🔬 Auditable evidence: qualification, model selection, locked evaluation, and release checks are distributed as JSON and CSV files.

📊 Release at a Glance

Item	Value
Spatial dimensions	2
Domain	`1.20 m x 0.80 m`
Production mesh	`36 x 24` cells
Simulated horizon	`7,200 s`
Retained snapshots per scenario	9
Soil classes	4
Complete scenarios	208
Training / validation / test / challenge	128 / 32 / 32 / 16
Spatiotemporal target fields	1,872
U-Net input channels	9
Trainable parameters	264,985
Selected epoch	117
Test effective-saturation RMSE	0.005784
Challenge effective-saturation RMSE	0.009004
Test RMSE reduction over initial persistence	91.2%
Final-time test wetting-front MAE	34.23 mm
Locked acceptance checks	7 of 7 passed
Model-package checks	15 of 15 passed
Scheduled development period	May 2026
Initial code release	May 2026
Training, evaluation, and documentation update	September 2026
Release version	1.0.0

The scheduled period records the project plan. Numerical execution, training, evaluation, and release preparation retain their actual timestamps in the machine-readable evidence.

📂 Repository Structure

.
|-- README.md
|-- CITATION.cff
|-- LICENSE
|-- LICENSE-DATA
|-- requirements.txt
|-- configs/
|   `-- infiltration_benchmark.json
|-- data/
|   |-- infiltration_corpus.npz
|   `-- infiltration_scenarios.csv
|-- models/
|   |-- soil_infiltration_unet.pt
|   `-- model_contract.json
|-- scripts/
|   |-- richards_reference_2d.py
|   |-- soil_infiltration_unet.py
|   |-- predict_infiltration.py
|   |-- design_infiltration_corpus.py
|   |-- generate_infiltration_corpus.py
|   |-- train_infiltration_unet.py
|   |-- evaluate_infiltration_unet.py
|   |-- qualify_*.py
|   `-- validate_*.py
|-- results/
|   |-- reference_qualification.{csv,json,png}
|   |-- scenario_envelope_qualification.{csv,json,png}
|   |-- infiltration_corpus_validation.json
|   |-- development_metrics.json
|   |-- final_evaluation.{json,png}
|   |-- final_evaluation_metrics.csv
|   |-- model_artifact_validation.json
|   `-- additional retained evidence and figures
`-- docs/
    |-- figures/
    |-- team/
    `-- partners/

Directory	Purpose
`configs/`	Locked physical, numerical, sampling, model, and acceptance protocol
`data/`	Consolidated synthetic corpus and one-row-per-scenario manifest
`models/`	Selected PyTorch checkpoint and its executable preprocessing contract
`scripts/`	Reference solver, corpus workflow, model training, inference, evaluation, and validators
`results/`	Machine-readable qualification records, metrics, training history, and scientific figures
`docs/`	README figures, research-team photographs, and presentation copies of institutional marks

The 208 per-scenario reference archives used during resumable generation are not duplicated in this release. Their complete fields are already present in data/infiltration_corpus.npz; the generator recreates the individual archives when a full regeneration is requested.

📦 Installation

System Requirements

Component	Supported configuration
Python	3.12 recommended
Operating system	Linux, macOS, or Windows
RAM	2 GB for one custom-scenario inference; 8 GB recommended for corpus workflows
Storage	Approximately 3 GB for the complete pinned environment
Accelerator	Optional; CPU inference is supported

Training and locked evaluation were performed with Python 3.12.2 and PyTorch 2.7.1 on Apple MPS. Wall times depend on hardware, operating system, linear solver, device warm-up, and process state.

Pinned Dependencies

Package	Version	Role
NumPy	2.5.2	Array operations and portable NPZ archives
SciPy	1.18.1	Spatial filtering and numerical utilities
pandas	2.2.3	Scenario, training, and metric tables
Matplotlib	3.10.0	Scientific figures
discretize	0.12.0	Tensor mesh and finite-volume operators
SimPEG	0.25.2	Richards-equation reference framework
pymatsolver	0.4.0	Sparse linear-solver interface
PyTorch	2.7.1	U-Net training and inference

Create an Environment

git clone https://github.com/gstinoco/Richards2D-DL.git
cd Richards2D-DL

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

On Windows PowerShell, activate the environment with:

.venv\Scripts\Activate.ps1

Only NumPy and PyTorch are needed for direct model inference. The complete requirements file installs the numerical-reference and regeneration toolchain as well.

🚀 Quick Start

Predict a Bundled Scenario

Run the selected checkpoint on a documented validation scenario:

python scripts/predict_infiltration.py \
  --scenario-id INF-LO-VA-001 \
  --output prediction_INF-LO-VA-001.npz

The output contains nine 24 x 36 effective-saturation and volumetric-water- content fields together with coordinates, hydraulic parameters, support diagnostics, and provenance metadata.

Inspect the result without any plotting dependency:

import numpy as np

with np.load("prediction_INF-LO-VA-001.npz", allow_pickle=False) as result:
    print(result.files)
    print(result["effective_saturation"].shape)
    print(result["times_s"])

Expected field shape:

(9, 24, 36)

Validate the Complete Release

python scripts/validate_release.py --overwrite

The release validator reruns the three independent component validators and then checks the repository contract, corpus shape, partition counts, selected model, principal metrics, documentation links, and publication hygiene. A successful run writes results/release_validation.json.

📐 Scientific Formulation

Coordinate System and State Variable

The domain is a vertical section of width Lx = 1.20 m and height Ly = 0.80 m. Coordinate x is horizontal, coordinate y increases upward, and depth below the soil surface is d = Ly - y. The primary numerical state is pressure head h(x, y, t) in metres.

The mixed Richards equation with specific storage is

$$ \frac{\partial [\theta(h)+S_s h]}{\partial t} =\nabla!\cdot!\left[K(h,\mathbf{x})\left(\nabla h+\mathbf{e}_y\right)\right], \qquad S_s=10^{-4};\mathrm{m}^{-1}. $$

The corresponding Darcy flux is

$$ \mathbf{q}=-K(h,\mathbf{x})\left(\nabla h+\mathbf{e}_y\right). $$

The specific-storage term regularizes saturated cells and is included in the stored quantity used for the numerical water-balance audit. The learned target is effective saturation, while volumetric water content is reconstructed from the constitutive parameters.

van Genuchten--Mualem Relations

For negative pressure head,

$$ S_e(h)=\left[1+(\alpha |h|)^n\right]^{-m}, \qquad m=1-\frac{1}{n}, $$

and

$$ \theta(h)=\theta_r+(\theta_s-\theta_r)S_e(h). $$

The unsaturated conductivity is

$$ K(h,\mathbf{x})=K_s(\mathbf{x})S_e^{\ell} \left[1-\left(1-S_e^{1/m}\right)^m\right]^2, \qquad \ell=0.5. $$

For nonnegative pressure head, the implementation sets Se = 1, theta = theta_s, and K = Ks. This piecewise statement is written explicitly to avoid implying that the unsaturated branch is evaluated beyond its domain.

Boundary and Initial Conditions

Boundary	Condition	Interpretation
Top	Prescribed negative pressure head	Maintained, near-saturated unsaturated surface
Left	Zero normal pressure-head gradient	No lateral pressure-driven flux
Right	Zero normal pressure-head gradient	No lateral pressure-driven flux
Bottom	Zero vertical pressure-head gradient	Free drainage under gravity

Each scenario begins from a spatially uniform negative pressure head. Its top pressure head remains greater than the initial value, producing infiltration. The scenario manifest records both values for every numerical realization.

Soil Classes

The four parameter sets are mean values for USDA textural classes reported by Carsel and Parrish. They are class-level reference values, not site-specific measurements.

Soil	`theta_r`	`theta_s`	`alpha` (`m^-1`)	`n`	Mean `Ks` (`m s^-1`)
Sandy loam	0.065	0.410	7.5	1.89	1.22778e-5
Loam	0.078	0.430	3.6	1.56	2.88889e-6
Silt loam	0.067	0.450	2.0	1.41	1.25000e-6
Clay loam	0.095	0.410	1.9	1.31	7.22222e-7

Only saturated hydraulic conductivity varies spatially within a scenario. It is generated as a smooth, clipped lognormal field:

$$ K_s(\mathbf{x})=\overline{K}_s \exp!\left[\sigma Z(\mathbf{x})-\frac{1}{2}\sigma^2\right]. $$

The normalized field Z is generated on a fixed latent grid before sampling to the numerical mesh. This makes a conductivity realization reproducible at shared physical coordinates across mesh-refinement levels.

🧮 Qualified Numerical Reference

Discretization and Nonlinear Solution

The reference uses SimPEG 0.25.2 and discretize 0.12.0 on a cell-centered TensorMesh. Spatial fluxes use finite-volume operators; time integration is implicit and first order. Each time step is solved with damped Newton updates, line search, adaptive step control, strict residual checks, and an explicit water-balance acceptance gate.

The project implementation subclasses SimulationNDCellCentered. During verification, the transpose of the SimPEG 0.25.2 aveF2CC operator did not preserve a constant cell field when transferring conductivity to faces in two dimensions. The local residual therefore uses the directionally normalized average_cell_to_face operator and a harmonic average between the top cell and the prescribed Dirichlet boundary conductivity. The original package is not modified or vendored.

At constitutive branch crossings, only nonfinite entries of the conductivity derivative are replaced by zero in the Jacobian. This local Picard linearization leaves conductivity values and the nonlinear residual unchanged. Every accepted time step must still satisfy the recorded residual and mixed water-balance criteria.

Production Configuration

Quantity	Production value	Verification value
Mesh	`36 x 24`	`48 x 32`
Initial time step	0.1 s	0.05 s
Maximum time step	300 s	150 s
Minimum time step	0.00625 s	0.003125 s
Simulation horizon	7,200 s	7,200 s

Retained snapshot times are 0, 120, 300, 600, 1,200, 2,400, 3,600, 5,400, and 7,200 s.

Refinement Qualification

The selected production configuration was compared against the verification mesh under all four soil classes. The maximum value across those comparisons remained within every threshold fixed in the protocol.

Metric	Maximum observed	Acceptance threshold	Result
Effective-saturation RMSE	0.00278	0.003	Passed
Effective-saturation maximum absolute error	0.0191	0.025	Passed
Final infiltration relative error	0.455%	0.5%	Passed
Wetting-front MAE	4.83 mm	5 mm	Passed

The solver-validation report contains 33 passing checks. Numerical qualification accepted 20 of 20 mesh-time runs, and the scenario-envelope audit accepted all 16 soil-corner combinations.

📥 Corpus & Data Contract

Scenario Design

The core scenarios were sampled with an independent scrambled Latin hypercube inside each soil and development partition. The sampling seed was fixed before numerical generation. Challenge scenarios use the four qualified corners of the parameter envelope and common conductivity-field seeds across soil classes to support controlled comparison.

Parameter	Qualified interval
Initial pressure head	`-0.20` to `-0.05 m`
Surface pressure head	`-0.030` to `-0.005 m`
Log-conductivity standard deviation	`0.15` to `0.45`
Horizontal correlation length	`0.16` to `0.32 m`
Vertical correlation length	`0.10` to `0.20 m`

Partition Policy

Partition	Scenarios	Fields	Permitted use
Training	128	1,152	Weight fitting and input normalization
Validation	32	288	Checkpoint selection and early stopping
Test	32	288	One locked final evaluation
Challenge	16	144	Qualified envelope-corner evaluation
Total	208	1,872

All nine snapshots from a scenario belong to exactly one partition. Test and challenge data were not used to fit normalization, update weights, stop training, select a checkpoint, or choose the architecture.

Consolidated Archive

data/infiltration_corpus.npz is a compressed, pickle-free NumPy archive. Its central field shape is (scenario, time, depth, x) = (208, 9, 24, 36).

Array group	Names	Shape	Units or meaning
Identity	`scenario_id`, `split`, `scenario_role`, `soil_name`	`(208,)`	Scenario metadata
Reproducibility	`field_seed`	`(208,)`	Conductivity realization seed
Coordinates	`x_m`	`(36,)`	Horizontal cell centers, m
Coordinates	`y_m`, `depth_m`	`(24,)`	Vertical centers and depth, m
Time	`times_s`	`(9,)`	Retained query times, s
Scenario scalars	`initial_pressure_head_m`, `surface_pressure_head_m`	`(208,)`	Pressure head, m
Heterogeneity scalars	`log_ks_standard_deviation`, `correlation_length_x_m`, `correlation_length_y_m`	`(208,)`	Dimensionless, m, m
Constitutive scalars	`theta_r`, `theta_s`, `alpha_m_1`, `n`, `Ks_m_s`	`(208,)`	Hydraulic parameters
Hydraulic input	`saturated_conductivity_m_s`	`(208, 24, 36)`	Spatial `Ks`, m/s
Numerical state	`pressure_head_m`	`(208, 9, 24, 36)`	Pressure head, m
Reported field	`water_content_m3_m3`	`(208, 9, 24, 36)`	Volumetric water content
Learning target	`effective_saturation`	`(208, 9, 24, 36)`	Dimensionless `[0,1]`
Balance diagnostics	`cumulative_infiltration_m2`, `cumulative_drainage_m2`	`(208, 9)`	Area per unit out-of-plane width
Archive metadata	`metadata_json`	scalar	Protocol and generation metadata

The companion data/infiltration_scenarios.csv contains one row per scenario and can be inspected without loading the field arrays.

Corpus Validation

Independent validation passed 20 checks covering structure, identities, partition counts, finite values, constitutive consistency, physical bounds, positive conductivity, cumulative fluxes, accepted nonlinear residuals, water balance, and a genuinely two-dimensional response.

Diagnostic	Retained value
Minimum / maximum effective saturation	0.54320 / 1.00000
Maximum global water-balance error	1.065e-6
Maximum accepted residual RMS	9.246e-11 s^-1
Median reference runtime per scenario	1.589 s
Total recorded reference runtime	366.79 s
Compressed corpus size	12.62 MB

🧠 Deep-Learning Model

Input Representation

The model receives one 24 x 36 map for each of nine channels, in this fixed order:

Index	Channel	Construction
1	`log10_Ks`	Base-10 logarithm of spatial saturated conductivity
2	`theta_r`	Residual water content repeated over the grid
3	`theta_s`	Saturated water content repeated over the grid
4	`log10_alpha`	Logarithm of van Genuchten `alpha`
5	`n`	van Genuchten shape parameter
6	`initial_pressure_head`	Initial pressure head repeated over the grid
7	`surface_pressure_head`	Surface pressure head repeated over the grid
8	`normalized_query_time`	Query time divided by 7,200 s
9	`normalized_depth`	Cell-center depth divided by 0.80 m

Each channel is standardized with statistics fitted only on training scenarios. Exact means and standard deviations are stored in models/model_contract.json.

Architecture

TimeConditionedUNet is a two-level convolutional encoder-decoder with skip connections, 24 base feature maps, GroupNorm, SiLU activations, and 264,985 trainable parameters. Time enters as a spatially repeated input channel, so a single selected checkpoint evaluates all documented snapshots.

The decoder predicts a correction in logit space. The reported output is

$$ \widehat{S}_e(t)=\operatorname{sigmoid}!\left[ \operatorname{logit}(S_{e,0})+\frac{t}{7200},\Delta\eta \right]. $$

At t = 0, the implementation directly returns the initial field. This parameterization guarantees a prediction in [0,1] and exact preservation of the initial state, but it does not by itself enforce the Richards residual or water balance.

Training and Selection

Setting	Value
Framework	PyTorch 2.7.1
Random seed	1202602
Optimizer	AdamW
Learning rate	5e-4
Weight decay	1e-5
Batch size	32
Loss	Mean squared effective-saturation error
Maximum epochs	250
Early-stopping patience	35 epochs
Completed epochs	152
Selected epoch	117
Selected validation RMSE	0.007357
Recorded training duration	248.65 s on Apple MPS

The selected checkpoint is the minimum-validation-loss state. Neither test nor challenge features or targets were constructed for model selection. The first locked evaluation used the selected checkpoint without any subsequent fitting.

📊 Validated Results

Locked Acceptance Evaluation

Evidence	Observed	Threshold	Result
Validation effective-saturation RMSE	0.00736	`<= 0.03`	Passed
Test effective-saturation RMSE	0.00578	`<= 0.03`	Passed
Challenge effective-saturation RMSE	0.00900	`<= 0.05`	Passed
Maximum per-soil test RMSE	0.01099	`<= 0.04`	Passed
Test RMSE reduction over initial persistence	91.2%	`>= 40%`	Passed
Final-time test wetting-front MAE	34.23 mm	`<= 50 mm`	Passed
Predicted effective-saturation range	`[0.5473, 1.0000]`	Inside `[0,1]`	Passed

All seven prospectively defined checks passed. The persistence baseline repeats the initial effective-saturation field at every later time; it measures whether the network learned useful transient evolution rather than merely preserving a plausible starting state.

Held-Out Results by Soil

Test soil	Scenarios	Effective-saturation RMSE	MAE	Maximum absolute error	Final wetting-front MAE
Sandy loam	8	0.01099	0.00473	0.22344	18.52 mm
Loam	8	0.00293	0.00160	0.03487	41.67 mm
Silt loam	8	0.00153	0.00095	0.01442	44.10 mm
Clay loam	8	0.00150	0.00082	0.01569	32.64 mm

Sandy loam is the most demanding class because the wetting front moves rapidly and can occupy only a few cells between retained snapshots. The largest point error was 0.2234 in test and 0.3224 in challenge. Both occurred near sharp sandy-loam wetting fronts. Low global RMSE therefore should not be interpreted as uniformly small pointwise error.

Post-Selection Physical Diagnostics

The integrated-storage RMSE was 4.98e-4 m2 in test and 9.51e-4 m2 in challenge. These values describe, but do not establish, conservation: the network is not constrained by a discrete flux balance during inference.

Effective saturation is not monotone at every cell because redistribution and free drainage can lower local water content. Decreases greater than 0.001 occurred in 6.80% of temporal cell pairs in the test reference and 5.89% in the test prediction. A monotonicity constraint was therefore not added after model selection.

Observed Query Time

The retained MPS timing measured warm inference for all nine snapshots of one scenario. Model loading and input assembly were excluded. The numerical time includes solution and snapshot extraction.

Measurement	Retained value
Median U-Net trajectory latency	4.43 ms
Mean U-Net trajectory latency	4.95 ms
95th-percentile latency	8.20 ms
Median numerical-reference runtime	1.590 s
Observed median reference / U-Net ratio	358.6x

This is an online query comparison, not a total-cost comparison. It excludes corpus generation, model training, model loading, and development effort, and it should not be generalized to other hardware without new measurements.

🎨 Visual Results

Reference and Prediction Fields

The retained comparison shows the heterogeneous saturated-conductivity input, the numerical effective-saturation field, the U-Net prediction, and their absolute difference for held-out scenarios and times.

Qualified Parameter Envelope

The envelope plot summarizes the 16 extreme soil-condition combinations used to establish the numerically supported parameter range before corpus sampling.

All plotted values are also available in CSV or JSON form under results/. Figures are explanatory views, not substitutes for the machine-readable evidence.

💻 Reusable Inference

Bundled Corpus Scenario

python scripts/predict_infiltration.py \
  --scenario-id INF-SL-TE-001 \
  --device cpu \
  --output prediction.npz

Use --corpus to select another compatible consolidated archive and --overwrite to replace an existing prediction intentionally.

Independent Hydraulic Scenario

python scripts/predict_infiltration.py \
  --input custom_scenario.npz \
  --output custom_prediction.npz

The custom NPZ archive must contain:

Name	Shape	Requirement
`saturated_conductivity_m_s`	`(24, 36)`	Finite, strictly positive field
`theta_r`	scalar	Must match a documented soil set
`theta_s`	scalar	Must match a documented soil set
`alpha_m_1`	scalar	Must match a documented soil set
`n`	scalar	Must match a documented soil set
`initial_pressure_head_m`	scalar	Inside the qualified interval
`surface_pressure_head_m`	scalar	Inside the qualified interval
`times_s`	one-dimensional, optional	Defaults to the nine contract times
`x_m`	`(36,)`, optional	Defaults to contract cell centers
`depth_m`	`(24,)`, optional	Defaults to contract cell centers

An input can be created with NumPy:

import numpy as np

x = np.linspace(0.0, 1.0, 36, dtype=np.float32)
depth = np.linspace(0.0, 1.0, 24, dtype=np.float32)
pattern = np.sin(2.0 * np.pi * x[None, :]) * np.cos(np.pi * depth[:, None])
pattern = (pattern - pattern.mean()) / pattern.std()

mean_ks_m_s = 2.888888888888889e-6
conductivity = mean_ks_m_s * np.exp(0.20 * pattern)
conductivity *= mean_ks_m_s / conductivity.mean()

np.savez_compressed(
    "custom_scenario.npz",
    saturated_conductivity_m_s=conductivity,
    theta_r=np.array(0.078),
    theta_s=np.array(0.430),
    alpha_m_1=np.array(3.6),
    n=np.array(1.56),
    initial_pressure_head_m=np.array(-0.12),
    surface_pressure_head_m=np.array(-0.015),
)

Applicability Safeguards

Before inference, the interface checks grid coordinates, constitutive parameters, pressure heads, mean conductivity relative to the selected soil, and the global logarithmic standard deviation of Ks. Spatial smoothness and correlation lengths cannot be established from array dimensions alone; the person preparing a custom field remains responsible for those properties.

An unsupported request is rejected by default. It can be run deliberately with

python scripts/predict_infiltration.py \
  --input custom_scenario.npz \
  --allow-out-of-domain \
  --output unsupported_prediction.npz

The resulting archive records every applicability reason and states that the release's quantitative validation does not apply.

✅ Validation & Reproducibility

One-Command Release Validation

python scripts/validate_release.py --overwrite

The command performs scientific checks rather than comparing opaque file hashes. It reruns the independent reference-solver, corpus, and model-package validators; checks the release structure and local README links; reconstructs key corpus and metric claims; and rejects private paths or temporary artifacts.

For a quick structural audit using the retained component reports:

python scripts/validate_release.py \
  --skip-component-validation \
  --overwrite

Component Validators

python scripts/validate_reference_solver.py --overwrite
python scripts/validate_infiltration_corpus.py --overwrite
python scripts/validate_model_artifacts.py --overwrite

The model validator runs on CPU, reconstructs predictions, checks repeatability and constitutive outputs, confirms the 264,985-parameter architecture, and verifies that reference-solver modules are not imported by the inference path.

Full Regeneration Order

The following workflow rebuilds the numerical evidence, corpus, checkpoint, and locked evaluation from the protocol:

python scripts/validate_reference_solver.py --overwrite
python scripts/qualify_reference_solver.py --overwrite
python scripts/qualify_scenario_envelope.py --overwrite
python scripts/design_infiltration_corpus.py --overwrite
python scripts/generate_infiltration_corpus.py --overwrite --regenerate-cases
python scripts/validate_infiltration_corpus.py --overwrite
python scripts/train_infiltration_unet.py --overwrite
python scripts/evaluate_infiltration_unet.py --overwrite
python scripts/validate_model_artifacts.py --overwrite
python scripts/validate_release.py --skip-component-validation --overwrite

This is an intentional replacement workflow. Preserve the released checkpoint and evaluation before experimenting. Once test or challenge results have informed a modeling choice, a later run is no longer an untouched first locked evaluation and must be described accordingly.

Reproducibility Scope

Scenario sampling and conductivity fields use recorded seeds.
Corpus fields and validation decisions are deterministic for the pinned numerical environment.
Training uses a fixed seed, but bitwise-identical neural weights are not guaranteed across devices, PyTorch builds, or nondeterministic kernels.
Reported wall times are observations from one environment, not acceptance requirements.

🔍 Scientific & Software Provenance

Data Provenance

All 208 scenarios are synthetic and were generated from the locked protocol.
Hydraulic class averages come from Carsel and Parrish (1988), with units converted from cm^-1 and cm/h to m^-1 and m/s.
The numerical target fields were produced by the bundled Richards reference implementation using SimPEG and discretize.
The corpus contains no field measurements, personal data, or third-party environmental observations.
Scenario seeds, sampled values, partition labels, and run diagnostics are retained in plain CSV and JSON files.

Numerical and Learning Foundations

M. Th. van Genuchten (1980). “A closed-form equation for predicting the hydraulic conductivity of unsaturated soils.” Soil Science Society of America Journal, 44(5), 892-898.
M. A. Celia, E. T. Bouloutas, and R. L. Zarba (1990). “A general mass-conservative numerical solution for the unsaturated flow equation.” Water Resources Research, 26(7), 1483-1496.
R. F. Carsel and R. S. Parrish (1988). “Developing joint probability distributions of soil water retention characteristics.” Water Resources Research, 24(5), 755-769.
R. Cockett, S. Kang, L. J. Heagy, A. Pidlisecky, and D. W. Oldenburg (2015). “SimPEG: An open source framework for simulation and gradient based parameter estimation in geophysical applications.” Computers & Geosciences, 85, 142-154.
R. Cockett, L. J. Heagy, and E. Haber (2018). “Efficient 3D inversions using the Richards equation.” Computers & Geosciences, 116, 91-102.
O. Ronneberger, P. Fischer, and T. Brox (2015). “U-Net: Convolutional Networks for Biomedical Image Segmentation.” MICCAI 2015, 234-241.

Third-Party Software

NumPy, SciPy, pandas, Matplotlib, discretize, SimPEG, pymatsolver, and PyTorch remain subject to their own licenses. Listing them in requirements.txt does not transfer ownership or relicense those projects. The repository does not vendor their source code.

Note on mGFD

mGFD 0.10.0 was assessed during numerical-method selection but is not used by the version 1.0.0 Richards reference. At the time of this release, its public solver did not expose the mixed nonlinear storage equation, state-dependent hydraulic conductivity, nonlinear iteration, and boundary-condition combination required by this benchmark. A future version may revisit that choice after a dedicated verification study.

⚠️ Limitations & Responsible Use

The corpus is synthetic and does not replace measurements from a field site, lysimeter, or controlled laboratory experiment.
Soil parameters are textural-class averages, not calibrated properties for a particular location.
Only saturated hydraulic conductivity varies spatially; the remaining constitutive parameters are uniform within each scenario.
Conductivity heterogeneity is smooth and clipped. Abrupt material interfaces, macropores, fractures, preferential flow, hysteresis, and dynamic surface ponding are outside the release.
Quantitative validation is limited to the documented domain, mesh, four soil classes, parameter envelope, and first two hours of infiltration.
Intermediate times can be queried inside the two-hour interval, but only the nine retained times were evaluated independently.
The largest local errors occur near rapid sandy-loam wetting fronts; an acceptable domain-wide RMSE does not guarantee cellwise accuracy.
The U-Net enforces output bounds and its initial state, but it does not solve a discrete conservation equation during inference.
The checkpoint does not provide calibrated predictive uncertainty.
Reported speed-up excludes data generation and training and represents one hardware and software environment.
Richards2D-DL is a research artifact. It must not be the sole basis for irrigation, environmental, regulatory, engineering-safety, or public-health decisions.

📝 How to Cite

Preferred Software Citation

Gerardo Tinoco-Guerrero, Francisco J. Domínguez-Mota, and J. Alberto Guzmán-Torres (2026). Richards2D-DL: Deep Learning for Two-Dimensional Soil Infiltration. Version 1.0.0. Universidad Michoacana de San Nicolás de Hidalgo. https://doi.org/10.5281/zenodo.22258878

Machine-readable metadata are available in CITATION.cff, which GitHub exposes through its Cite this repository interface. Zenodo archives the exact v1.0.0 release under DOI 10.5281/zenodo.22258878.

When reporting numerical results, identify the release version, evaluation partition, soil class, metric, and whether timing refers to model inference or the complete development workflow.

🧑‍🔬 Research Team

🌟 Meet the Team

Researchers and students advancing reproducible numerical modeling and scientific machine learning for environmental systems

👥 Main Researchers

Photo	Researcher	Affiliation	Contact
	Gerardo Tinoco-Guerrero _{Numerical methods and environmental modeling}
	Francisco J. Domínguez-Mota _{Applied mathematics and numerical analysis}
	J. Alberto Guzmán-Torres _{Engineering applications and artificial intelligence}

🎓 Ph.D. Research Students

Photo	Student	Institution	Contact
	Gabriela Pedraza-Jiménez
	Eli Chagolla-Inzunza

🎓 M.Sc. Research Students

Photo	Student	Institution	Contact
	Jorge L. González-Figueroa
	Christopher N. Magaña-Barocio

🎓 Undergraduate Research Student

Photo	Student	Institution	Contact
	Maria Goretti Fraga-Lopez

Students are acknowledged as project contributors and members of the research group. The formal software citation and copyright statement list the three principal investigators.

🏭 Industry Partners Supporting Innovation

🌟 Academic-Industry Collaboration

SIIIA MATH: Soluciones en Ingeniería
_{Engineering, technology transfer, and applied research support}

📄 License & Rights

Source code is released under the MIT License.
The synthetic corpus, scientific results, and project figures are released under Creative Commons Attribution 4.0 International.
Institutional logos and personal photographs are excluded from CC BY 4.0 and remain subject to the rights of their owners or depicted persons.
Third-party dependencies retain their respective licenses.

Copyright is held by Gerardo Tinoco-Guerrero, Francisco J. Domínguez-Mota, and J. Alberto Guzmán-Torres. Institutional support does not imply endorsement of every result, interpretation, or downstream use.

🙏 Acknowledgments

❤️ Institutional and Financial Support

The authors gratefully acknowledge institutional and financial support from the following organizations for the development, numerical experimentation, validation, documentation, and dissemination of this work.

Universidad Michoacana de San Nicolás de Hidalgo _{Academic infrastructure and research support through CIC-UMSNH}	Secretaría de Ciencia, Humanidades, Tecnología e Innovación _{Public research funding in Mexico}
International Centre for Numerical Methods in Engineering _{Scientific collaboration and training, including Aula CIMNE Morelia}	SIIIA MATH: Soluciones en Ingeniería _{Financial, engineering, and technology-transfer support}

💻 Technology Communities

Technology	Community	Role in the release
	Python Community	Reproducible scientific workflows
	NumPy Community	Numerical arrays and corpus storage
	SciPy Community	Spatial fields and numerical utilities
	SimPEG Community	Finite-volume Richards framework
	PyTorch Community	Training and portable inference
	Matplotlib Community	Scientific visualization

📧 Contact & Support

Gerardo Tinoco-Guerrero
Universidad Michoacana de San Nicolás de Hidalgo
Morelia, Michoacán, Mexico

For reproducible bug reports, include the operating system, Python and package versions, command used, complete traceback, scenario source, and whether the request was inside the documented support.

💬 FAQ

Does inference require SimPEG?

No. Direct inference imports NumPy and PyTorch only. SimPEG, discretize, SciPy, pandas, pymatsolver, and Matplotlib are needed for reference generation, training, evaluation, or their supporting evidence workflows.

Can I predict a soil class not listed here?

The interface rejects constitutive parameter sets outside the four documented classes unless --allow-out-of-domain is supplied. An overridden result is an unsupported extrapolation and has no quantitative validation claim.

Why is the target effective saturation rather than water content?

Effective saturation places every soil class on the same dimensionless range. Water content is then reconstructed exactly from theta_r, theta_s, and the predicted effective saturation.

Why are the 208 individual numerical case files absent?

They are resumable generation intermediates. The consolidated corpus already contains all pressure-head, water-content, saturation, conductivity, flux, and metadata arrays needed for reuse. Full regeneration recreates the individual case directory automatically.

Does the reported speed-up include training?

No. It compares a warm nine-snapshot model query with one recorded numerical reference trajectory. Corpus generation, training, model loading, and input assembly are excluded.

Is the model mass-conservative?

Not by construction. The reference solver is balance-audited, while the model enforces the initial state and output bounds. Integrated-storage error is reported as a post-selection diagnostic and should not be confused with a discrete conservation guarantee.

How should a modified model be reported?

Record the changed protocol, new training seed, data partitions, normalization source, selected epoch, untouched evaluation set, hardware, and complete metrics. Do not describe a test set as locked after its results have guided model selection.

Richards2D-DL | Reproducible deep learning for two-dimensional soil infiltration

Version 1.0.0 | September 2026

Name		Name	Last commit message	Last commit date
configs		configs
data		data
docs		docs
models		models
results		results
scripts		scripts
.gitignore		.gitignore
CITATION.cff		CITATION.cff
LICENSE		LICENSE
LICENSE-DATA		LICENSE-DATA
README.md		README.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation