Meshless numerical-machine-learning defect correction for two-dimensional reactive contaminant transport.
An accepted rectangular-domain hybrid model, reproducible numerical evidence, reusable inference interfaces, and a transparent audit of transfer to irregular geometries.
- Overview
- Repository Structure
- Installation
- Quick Start
- Scientific Formulation
- Numerical Core
- Hybrid Architecture
- Data and Evaluation Design
- Validated Results
- Irregular-Geometry Audit
- Visual Results
- Reusable Inference Interface
- Validation and Reproducibility
- Scientific and Software Provenance
- Limitations
- How to Cite
- Research Team
- Industry Partners
- License and Rights
- Acknowledgments
- Contact and Support
- FAQ
ADR2D-Hybrid combines a two-dimensional meshless generalized finite difference (mGFD) solver with a neural defect corrector for reactive contaminant transport. The numerical component computes a moderate-resolution trajectory; the learned component estimates its discrepancy relative to an accepted refined numerical solution at exactly shared points.
The accepted model was trained and selected with scenario-independent partitions, then evaluated once on 18 held-out controlled-pulse scenarios. It preserves non-negativity and Dirichlet boundary values through an explicit physical projection. The release also includes a pure-ML comparator, a numerical baseline, the refined reference evidence, and interchangeable mGFD point-cloud interfaces.
The principal quantitative claim is deliberately narrow:
ADR2D-Hybrid is accepted for the locked unit-square controlled-pulse domain with constant coefficients, 31 retained times,
8 <= Pe <= 40, and0 <= Da <= 1.2.
Transfer to irregular domains was investigated after model selection. The
hybrid reduced numerical-baseline error in all 27 geometry-scenario cases, but
the finest perforated-domain reference developed a nonphysical growing mode.
The locked audit therefore returned reference_inadequate, not
transfer_supported. This repository preserves that result rather than
retuning a threshold or overstating geometric generalization.
- 📐 Two-dimensional reactive transport: advection, anisotropic dispersion, retardation, first-order decay, and source terms.
- 🔹 Meshless discretization: coordinate and boundary arrays are accepted directly; no Cartesian connectivity is required.
- 🔀 Defect correction: the neural network learns
refined mGFD - base mGFD, rather than replacing the complete solver. - 🔒 Leakage-controlled development: complete scenarios remain in train, validation, or test, and test features are not constructed during model selection.
- ⚖️ Comparable methods: base mGFD, pure ML, hybrid mGFD-ML, and refined mGFD use identical test scenarios, times, and evaluation nodes.
- 🛡️ Explicit physical projection: negative learned values are clipped and exact boundary values are restored after inference.
- 🔄 Reusable interface: a saved checkpoint can correct any compatible base trajectory without invoking the training code.
- 🔬 Independent validation: component validators reconstruct fields, metrics, cloud contracts, and scientific decisions.
| Item | Value |
|---|---|
| Spatial dimensions | 2 |
| Synthetic controlled-pulse scenarios | 108 |
| Train / validation / test scenarios | 72 / 18 / 18 |
| Retained output times | 31 |
| Base nodes per rectangular scenario | 289 |
| Refined reference nodes before exact extraction | 4,225 |
| Hybrid input features | 27 |
| Hybrid trainable parameters | 18,273 |
| Held-out comparisons per method | 161,262 |
| Hybrid median peak-normalized RMSE | 0.002538 |
| Hybrid / base median-error ratio | 0.257620 |
| Held-out scenarios improved | 18 of 18 |
| Observed refined-reference / hybrid speed-up | 8.09x |
| Irregular geometry-scenario audit cases | 27 |
| Irregular-audit decision | reference_inadequate |
| Scheduled development period | January-March 2026 |
| Initial code release | January 2026 |
| Validation and documentation update | August 2026 |
| Release version | 1.0.0 |
The scheduled period records the project plan. Training, held-out evaluation, irregular-domain auditing, validation, and public-release preparation retain their actual 2026 dates in the machine-readable evidence.
.
|-- README.md
|-- CITATION.cff
|-- LICENSE
|-- LICENSE-DATA
|-- requirements.txt
|-- configs/
| |-- manufactured_verification.json
| |-- pulse_scenario_protocol.json
| |-- hybrid_model_protocol.json
| |-- point_cloud_protocol.json
| `-- irregular_transfer_audit.json
|-- data/
| |-- pulse_transport_corpus.npz
| |-- selected_point_cloud.npz
| |-- irregular_transfer_corpus.npz
| |-- irregular_domain_contour.csv
| |-- irregular_concave_contour.csv
| `-- irregular_hole_contour.csv
|-- models/
| |-- pure_ml_model.pt
| |-- hybrid_defect_model.pt
| `-- model_contract.json
|-- scripts/
| |-- mgfd_reactive_2d.py
| |-- controlled_pulse_2d.py
| |-- hybrid_ml_2d.py
| |-- hybrid_predictor_2d.py
| |-- point_cloud_2d.py
| |-- irregular_transfer_2d.py
| |-- generate_*.py
| |-- train_hybrid_models.py
| |-- evaluate_hybrid_models.py
| |-- run_*.py
| |-- validate_*.py
| `-- validate_release.py
|-- results/
| |-- pulse_scenarios.csv
| |-- hybrid_evaluation_summary.json
| |-- hybrid_evaluation_validation.json
| |-- irregular_transfer_summary.json
| |-- irregular_transfer_validation.json
| `-- additional CSV, JSON, NPZ, and PNG evidence
`-- docs/
|-- figures/
|-- team/
`-- partners/
| Directory | Purpose |
|---|---|
configs/ |
Prospectively locked numerical, scenario, model, cloud, and transfer-audit protocols |
data/ |
Reusable numerical corpora, normalized point clouds, and polygonal contours |
models/ |
Selected PyTorch checkpoints and the model-development contract |
scripts/ |
Numerical solver, ML interfaces, generators, training, evaluation, and independent validators |
results/ |
Machine-readable validation reports, metrics, histories, and retained scientific figures |
docs/ |
README figures, research-team photographs, and presentation copies of institutional marks |
The repository uses one authoritative README. Exact numerical evidence remains in JSON and CSV files so that readers can inspect values without parsing prose.
| Component | Supported configuration |
|---|---|
| Python | 3.12 recommended; 3.10 or newer required |
| Operating system | Linux, macOS, or Windows |
| RAM | 2 GB for inference; 8 GB recommended for training and full regeneration |
| Storage | Approximately 3 GB including the pinned PyTorch environment |
| Accelerator | Not required; all retained workflows were executed on CPU |
The canonical training and held-out evaluation environment used Python 3.12.2 on Apple arm64. Exact wall times vary across hardware and operating systems.
| Package | Version | Role |
|---|---|---|
| NumPy | 2.0.2 | Numerical arrays and corpus storage |
| pandas | 2.2.3 | Scenario, metric, and evidence tables |
| SciPy | 1.15.2 | Sparse systems, neighbors, geometry, and spectral diagnostics |
| Matplotlib | 3.10.0 | Scientific figures and visual validation |
| PyTorch | 2.7.1 | Pure-ML and hybrid neural networks |
| mGFD | 0.10.0 | Public point-cloud generation and loading API |
git clone https://github.com/gstinoco/ADR2D-Hybrid.git
cd ADR2D-Hybrid
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txtOn Windows PowerShell, activate the environment with:
.venv\Scripts\Activate.ps1python scripts/validate_release.py --overwriteThis command executes the six independent component validators and then checks
the repository contract, corpora, checkpoints, documentation links, accepted
rectangular claims, and irregular-audit decision. A successful run writes
results/release_validation.json.
Run the following example from the repository root:
from pathlib import Path
import sys
import numpy as np
import pandas as pd
ROOT = Path.cwd()
sys.path.insert(0, str(ROOT / "scripts"))
from hybrid_predictor_2d import HybridPredictor2D
scenario_id = "S108-P3-D3-TG"
scenario_table = pd.read_csv(ROOT / "results/pulse_scenarios.csv").set_index("scenario_id")
scenario = scenario_table.loc[scenario_id]
with np.load(ROOT / "data/pulse_transport_corpus.npz", allow_pickle=False) as corpus:
scenario_index = int(np.flatnonzero(corpus["scenario_id"] == scenario_id)[0])
points_m = corpus["points_m"][scenario_index]
boundary_mask = corpus["boundary_mask"][scenario_index]
times_s = corpus["times_s"]
base_concentration = corpus["base_concentration"][scenario_index]
predictor = HybridPredictor2D.from_repository(ROOT)
result = predictor.correct(points_m, boundary_mask, times_s, base_concentration, scenario)
hybrid_concentration = result["concentration"]
print(hybrid_concentration.shape)
print(result["applicability"])Expected field shape:
(31, 289)
The result also contains predicted_defect, raw_concentration, and explicit
applicability metadata. The raw field is retained for diagnostics; scientific
evaluation uses the physically projected concentration field.
ADR2D-Hybrid represents two-dimensional advection-dispersion-reaction through
\nabla\cdot\left(\mathbf{D}\nabla c\right) -\mathbf{v}\cdot\nabla c -\lambda R c +q, \qquad (x,y)\in\Omega,\quad t>0, $$
where:
| Symbol | Meaning | Unit |
|---|---|---|
| dissolved contaminant concentration | normalized | |
| retardation factor | dimensionless | |
| advective velocity | m/s | |
| symmetric positive-definite dispersion tensor | m2/s | |
| first-order decay rate | 1/s | |
| volumetric source term | concentration/s |
For constant coefficients, the spatial operator supplied to the local mGFD stencils is
\frac{D_{xx}}{R}c_{xx} +\frac{2D_{xy}}{R}c_{xy} +\frac{D_{yy}}{R}c_{yy} -\frac{v_x}{R}c_x -\frac{v_y}{R}c_y. $$
Reaction, source terms, time integration, and Dirichlet conditions are handled by the repository's reactive interface rather than attributed to capabilities that are not present in the upstream transient mGFD routine.
The retained benchmark starts from zero concentration and uses no volumetric source. On the inlet, the temporal factor is
for 0 outside that interval. A Gaussian
profile centered at
The scenario design spans nine Péclet-Damköhler cells:
| Regime | Interval | Interpretation |
|---|---|---|
| P1 | dispersion-controlled transport | |
| P2 | mixed transport | |
| P3 | advection-influenced transport | |
| D1 | nearly conservative behavior | |
| D2 | moderate reaction | |
| D3 | strong reaction |
The release does not claim validity for the gaps between these intervals or
for
scripts/mgfd_reactive_2d.py implements an
independent reactive-transport interface informed by the published mGFD
methodology. It:
- accepts coordinates and a boundary mask without mesh connectivity;
- selects 24 local neighbors with
cKDTree; - constructs scaled second-order Taylor stencils;
- assembles a sparse advection-dispersion operator;
- applies reaction and source terms with physical units;
- advances the field with a theta method (
theta = 0.5for the retained Crank-Nicolson runs); - imposes Dirichlet values at every time level;
- returns stencil conditioning and polynomial-reproduction diagnostics.
The implementation does not vendor the upstream mGFD repository or its
datasets. The public mGFD==0.10.0 dependency is used directly for contour-
based point-cloud generation and loading.
A protocol with nonzero, spatially varying, time-dependent Dirichlet data was locked before the retained run. Four clouds produced the following final-time convergence:
| Points per axis | Nodes | Nominal spacing [m] | Final relative |
Observed order |
|---|---|---|---|---|
| 11 | 121 | 0.10000 | 0.014772 | - |
| 17 | 289 | 0.06250 | 0.005956 | 1.933 |
| 25 | 625 | 0.04167 | 0.002634 | 2.013 |
| 33 | 1,089 | 0.03125 | 0.001490 | 1.980 |
The finest-cloud all-time relative 0.000814; the maximum
reproduction error of the local stencils was 4.76e-15. The independent
validator reproduced all stored values and passed its 22 checks.
The accepted hybrid field is
\mathcal{P}{\mathrm{phys}} \left(c{\mathrm{mGFD}}^{17}+\widehat{\Delta c}{\theta}\right), \qquad \Delta c=c{\mathrm{mGFD}}^{65}-c_{\mathrm{mGFD}}^{17}, $$
where the superscripts identify the rectangular point count per axis before the refined field is extracted at exactly shared base nodes. The corrector operates on 31 retained outputs; it does not modify hidden states inside the time integrator.
| Method | Input | Output role |
|---|---|---|
| Base mGFD | physical scenario and 17x17 cloud | moderate-resolution numerical baseline |
| Pure ML | coordinates, time, boundary geometry, and scenario parameters | direct refined-field approximation |
| Hybrid mGFD-ML | pure-ML features plus local and temporal base-trajectory features | refined-minus-base defect |
| Refined mGFD | accepted 65x65 solution | numerical target and comparison reference |
The pure-ML comparator uses 22 causal features:
- coordinates, time, distance to boundary, and boundary indicator;
-
$Pe$ ,$Da$ , retardation, decay, velocity, and dispersion components; - pulse amplitude, center, width, start, and duration;
- cloud irregularity and known pulse factors.
The hybrid adds five quantities calculated only from the available base trajectory:
- current and previous base concentration;
- temporal base increment;
- mean and standard deviation of the eight nearest base neighbors.
Reference concentrations, future base values, scenario identifiers, partition labels, and test roles are forbidden model inputs. Feature and target scaling statistics were fitted on the 72 training scenarios only.
Both learned comparators use a multilayer perceptron with hidden widths
96-96-64, SiLU activations, and AdamW optimization. The pure-ML model has
17,793 trainable parameters; the hybrid model has 18,273.
The physical projection applies two transparent operations:
- set negative learned concentrations to zero;
- restore exact Dirichlet values from the controlled pulse or supplied base trajectory.
This projection is part of the accepted interface and is not described as a learned physical law. Raw fields remain available so that its effect can be audited.
Each of the nine
| Partition | Scenarios | Role |
|---|---|---|
| Training | 72 | fit model weights and preprocessing statistics |
| Validation | 18 | select checkpoints and stopping epochs |
| Test | 18 | one-time final comparison after both models were frozen |
Nine test scenarios interpolate the training-cloud perturbation range; nine
use stronger rectangular-cloud perturbations fixed in advance as
geometry_stress cases. Test feature matrices, targets, predictions, and
metrics were not constructed during training or model selection.
data/pulse_transport_corpus.npz stores:
| Array | Shape | Description |
|---|---|---|
scenario_id |
(108,) |
stable scenario identifiers |
split |
(108,) |
train, validation, or test membership |
times_s |
(31,) |
retained physical times |
points_m |
(108, 289, 2) |
base-cloud coordinates |
boundary_mask |
(108, 289) |
Dirichlet-node indicators |
base_concentration |
(108, 31, 289) |
moderate-resolution mGFD fields |
reference_concentration |
(108, 31, 289) |
refined fields at shared base nodes |
All scenarios are synthetic. No field observations, Water Quality Portal records, personal information, or licensed publisher data are included.
The rectangular hierarchy uses 17, 33, 65, and 129 points per axis with exact node nesting. Before ML targets were generated, nine geometry-stress anchors were compared between the 65- and 129-point levels. Every prospectively locked criterion passed:
| Diagnostic | Maximum result | Limit |
|---|---|---|
| Peak-normalized RMSE | 0.001181 | 0.005 |
| Peak-normalized pointwise error | 0.033256 | 0.05 |
| Reference undershoot relative to pulse | 0.000171 | 0.005 |
| Boundary error | 0 | 1e-12 |
| Stencil reproduction error | 2.77e-14 |
1e-10 |
| Stencil condition-number p95 | 6.43 | 50 |
The 65-point-per-axis field was therefore accepted as a numerical target only inside the locked rectangular benchmark domain.
The held-out partition contains 18 scenarios, 31 times, 289 nodes per scenario, and 161,262 comparisons per method.
| Method | Median peak-normalized RMSE | Maximum peak-normalized RMSE | Median relative |
Median mass error / peak |
|---|---|---|---|---|
| Base mGFD | 0.009851 | 0.017503 | 0.200614 | 0.027936 |
| Pure ML | 0.006349 | 0.017797 | 0.129911 | 0.073843 |
| Hybrid mGFD-ML | 0.002538 | 0.005753 | 0.053410 | 0.025466 |
The hybrid reduced median peak-normalized RMSE to 0.257620 of the base mGFD
value, equivalent to a 74.24% reduction. It improved all 18 held-out scenarios
and degraded none. In the nine predeclared geometry-stress cases, the median
hybrid/base error ratio was 0.316689.
Before projection, the hybrid minimum was -0.013918 and its maximum boundary
error was 0.014688. After projection:
| Constraint | Result | Locked limit |
|---|---|---|
| Minimum hybrid concentration | 0 | >= -1e-12 |
| Maximum hybrid boundary error | 0 | <= 1e-12 |
The raw negative fraction is large in nearly empty regions because small negative corrections affect many values close to zero. Reporting only the projected field would conceal that behavior, so both raw and projected diagnostics are retained.
Aggregate wall times for all 18 test scenarios were:
| Method | Time [s] | Refined-reference speed-up |
|---|---|---|
| Base mGFD | 0.674 | 9.15x |
| Pure ML, including preparation and projection | 0.077 | 80.19x |
| Hybrid, including base solve and correction | 0.762 | 8.09x |
| Refined mGFD reference | 6.167 | 1.00x |
These are observations from one software and hardware environment, not hardware-independent performance guarantees.
All seven locked acceptance checks passed. The independent held-out validator
reconstructed inference, projection, metrics, and the reusable interface with
a maximum stored-value difference of 4.996e-16; it passed 41 of 41
checks.
After model selection and held-out evaluation, the unchanged checkpoints were tested on three new geometry families:
- a convex nonrectangular basin;
- a concave channel;
- a basin with an interior obstacle.
Each geometry used exactly nested mGFD clouds with nominal spacings of 0.06,
0.03, and 0.015 m. Nine pre-existing geometry_stress scenarios produced
27 transfer cases. No irregular case was used for training, checkpoint
selection, threshold setting, or feature scaling.
| Method | Cases | Median peak-normalized RMSE | Maximum peak-normalized RMSE |
|---|---|---|---|
| Base mGFD | 27 | 0.007680 | 0.015181 |
| Pure ML | 27 | 0.010646 | 0.020129 |
| Hybrid mGFD-ML | 27 | 0.003520 | 0.008443 |
The hybrid improved all 27 comparisons against the retained intermediate
reference. Its overall median hybrid/base ratio was 0.458329; the three
geometry-specific ratios ranged from 0.436367 to 0.466048.
The anchor scenario was also solved on the finest audit cloud. Convex and concave references behaved consistently, but the perforated-domain solution developed a nonphysical mode near the interior boundary:
| Geometry | Reference-audit NRMSE / peak | Maximum pointwise error / peak | Minimum audit concentration | Outcome |
|---|---|---|---|---|
| Convex basin | 0.003176 | 0.056177 | 0.000000 | acceptable |
| Concave channel | 0.003137 | 0.056113 | 0.000000 | acceptable |
| Interior obstacle | 0.006440 | 1.000038 | -40.721872 | not acceptable |
The locked pointwise limit was 0.12. Eight of nine acceptance checks passed,
but the failed reference check forced the decision
reference_inadequate. A post-audit spectral diagnostic found dominant
real eigenvalues of -4.9872 1/s, -5.0868 1/s, and 10.1144 1/s for the
convex, concave, and perforated audit operators, respectively. The positive
perforated-domain mode supports the numerical-instability diagnosis.
This outcome does not establish model failure or geometric transfer. It means the current reference cannot distinguish those alternatives for domains with interior holes. The next scientific step is to stabilize and re-audit the interior-boundary discretization before deciding whether retraining is needed.
The independent transfer validator regenerated all three cloud hierarchies, reconstructed 54 learned inference calls, recalculated 81 metric rows, and reapplied the decision rule. It passed 208 of 208 integrity checks while preserving the failed scientific criterion.
The most demanding predeclared rectangular geometry-stress case shows how the defect corrector recovers plume magnitude and structure without replacing the base numerical field:
The cloud interface accepts an mGFD-compatible CSV, normalizes coordinates, flags, boundary membership, inlet membership, and boundary distance, and then passes the same contract to the numerical and learned components:
This figure demonstrates software interoperability. Accuracy on a new geometry must be established separately with an accepted reference.
The perforated visualization uses the retained intermediate reference; the separate refinement audit is what prevents a transfer claim.
scripts/hybrid_predictor_2d.py exposes the
public HybridPredictor2D interface. A request contains:
| Input | Required shape or type |
|---|---|
points_m |
(n_nodes, 2) finite unique coordinates |
boundary_mask |
(n_nodes,) Boolean-compatible vector |
times_s |
the 31 retained model times |
base_concentration |
(31, n_nodes) base numerical trajectory |
scenario |
mapping or pandas row with the locked physical and pulse fields |
For a geometry outside the validated rectangular support, the interface refuses inference unless the caller explicitly opts in:
result = predictor.correct(
points_m,
boundary_mask,
times_s,
base_concentration,
scenario,
allow_unvalidated_geometry=True,
)The opt-in acknowledges an experiment; it does not create accuracy evidence.
Returned metadata preserve
predictive_accuracy_validated_for_geometry=False, and physical projection
uses the supplied base-trajectory boundary values.
- dimensions, finiteness, and coordinate uniqueness are checked;
- retained times must match the model contract;
- the supplied base trajectory must align with the cloud;
- unvalidated geometries require explicit authorization;
- raw and projected fields are both returned;
- projection provenance is recorded in
result["applicability"].
python scripts/validate_release.py --overwriteThe release validator runs these independent checks:
| Validator | Scope | Retained outcome |
|---|---|---|
validate_manufactured_verification.py |
exact solution, convergence, boundary data, and figure | 22 checks passed |
validate_pulse_scenarios.py |
ranges, partitions, equations, seeds, and nested clouds | 63 / 63 |
validate_pulse_corpus.py |
corpus arrays, times, boundaries, errors, and integrals | 39 / 39 |
validate_hybrid_evaluation.py |
checkpoints, inference, projection, metrics, and interface | 41 / 41 |
validate_point_cloud_interface.py |
official mGFD reader, masks, distances, and opt-in behavior | 31 / 31 |
validate_irregular_transfer_audit.py |
hierarchies, 54 inferences, 81 metrics, figures, and decision | 208 / 208 |
Validation status and scientific acceptance are intentionally distinct. The
irregular-audit validator returns ok because it reproduces the experiment
and its reference_inadequate decision exactly.
python scripts/validate_manufactured_verification.py --overwrite
python scripts/validate_pulse_scenarios.py --overwrite
python scripts/validate_pulse_corpus.py --overwrite
python scripts/validate_hybrid_evaluation.py --overwrite
python scripts/validate_point_cloud_interface.py --overwrite
python scripts/validate_irregular_transfer_audit.py --overwriteThe following sequence rebuilds the scientific workflow. Training overwrites the bundled checkpoints and should be performed in a clean clone when the published artifacts must remain unchanged.
python scripts/run_manufactured_verification.py --overwrite
python scripts/validate_manufactured_verification.py --overwrite
python scripts/generate_pulse_scenarios.py --overwrite
python scripts/validate_pulse_scenarios.py --overwrite
python scripts/run_pulse_reference_audit.py --overwrite
python scripts/generate_pulse_corpus.py --overwrite
python scripts/validate_pulse_corpus.py --overwrite
python scripts/train_hybrid_models.py --overwrite
python scripts/evaluate_hybrid_models.py --overwrite
python scripts/validate_hybrid_evaluation.py --overwrite
python scripts/prepare_point_cloud.py --overwrite
python scripts/run_irregular_cloud_demo.py --overwrite
python scripts/validate_point_cloud_interface.py --overwrite
python scripts/run_irregular_transfer_audit.py --overwrite
python scripts/validate_irregular_transfer_audit.py --overwrite
python scripts/validate_release.py --overwrite --skip-component-validationRandom seeds and protocols are fixed. Wall times and timestamp fields may vary with hardware and execution date; accepted numerical metrics and decisions must remain within their declared tolerances.
The local-stencil design follows the mGFD methodology described by Tinoco-Guerrero, Domínguez-Mota, Guzmán-Torres, Pedraza-Jiménez, and Tinoco-Ruiz (2025). The reactive solver in this repository is an independent implementation adapted to explicit transport units, source callbacks, time-dependent Dirichlet data, and model-correction interfaces.
The technical implementation was informed by public mGFD commit
cb9330a,
consulted on August 2, 2026. The upstream project is MIT-licensed and is not
vendored here. Point-cloud generation and reading use the official
mGFD 0.10.0 package.
- The 108 controlled-pulse scenarios are generated from the locked protocol
in
configs/pulse_scenario_protocol.json. - Base and refined fields are computed by the bundled reactive mGFD solver.
- Training targets are exact shared-node differences between accepted refined and base numerical fields.
- Irregular contours are project-authored polygonal geometries distributed as plain CSV files.
- No externally licensed environmental measurements are redistributed.
NumPy, pandas, SciPy, Matplotlib, PyTorch, and mGFD remain subject to their own
licenses. Their inclusion in requirements.txt does not transfer ownership or
relicense those projects.
- The accepted predictive evidence is synthetic and restricted to the locked unit-square controlled-pulse family with constant coefficients.
- The retained reference is a numerically accepted refined mGFD solution, not an analytical truth field.
- The model has not been validated with field measurements, uncertain sensor streams, heterogeneous coefficients, mixed boundary conditions, or changing chemistry.
- The centered local discretization is not used to generate targets for
Pe > 40; more advective regimes require a dedicated stabilization study. - The architecture can process another node count, but accuracy is established only on the rectangular 289-node support used for training and held-out evaluation.
- Convex and concave irregular references passed the retained anchor audit, but the perforated-domain reference did not. No transfer claim is made for domains with interior obstacles.
- The current interface requires the same 31 retained times used during training.
- The learned corrector modifies reported mGFD outputs, not the integrator's internal states between those outputs.
- Non-negativity and boundary consistency depend on an explicit projection; the raw neural field does not satisfy those constraints by itself.
- Reported speed-ups describe one CPU execution and should not be generalized across hardware, batch sizes, or sparse-solver implementations.
- ADR2D-Hybrid is a research artifact. It must not be the sole basis for environmental, regulatory, engineering-safety, or public-health decisions.
Gerardo Tinoco-Guerrero, Francisco J. Domínguez-Mota, and J. Alberto Guzmán-Torres (2026). ADR2D-Hybrid: Meshless Numerical-Machine Learning for Two-Dimensional Reactive Contaminant Transport. Version 1.0.0. Universidad Michoacana de San Nicolás de Hidalgo. https://doi.org/10.5281/zenodo.22240358
Machine-readable metadata are available in CITATION.cff.
GitHub can expose them through its Cite this repository interface. The
archived v1.0.0 release and its reusable citation metadata are preserved in
Zenodo.
G. Tinoco-Guerrero, F. J. Domínguez-Mota, J. A. Guzmán-Torres, G. Pedraza-Jiménez, and J. G. Tinoco-Ruiz (2025). “mGFD: A meshless generalized finite difference method.” Computers & Mathematics with Applications, 195, 396-418. https://doi.org/10.1016/j.camwa.2025.07.034
When reporting model results, state whether the accepted rectangular evaluation or the inconclusive irregular-geometry audit was used. They support different scientific claims.
Researchers and students advancing reproducible numerical methods and scientific machine learning for environmental transport
| Photo | Researcher | Affiliation | Contact |
|---|---|---|---|
 |
Gerardo Tinoco-Guerrero Meshless 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 |
|
 |
| Photo | Student | Institution | Contact |
|---|---|---|---|
 |
Gabriela Pedraza-Jiménez |
|
|
 |
Eli Chagolla-Inzunza |
|
|
| Photo | Student | Institution | Contact |
|---|---|---|---|
 |
Jorge L. González-Figueroa |
|
|
 |
Christopher N. Magaña-Barocio |
|
|
| Photo | Student | Institution | Contact |
|---|---|---|---|
 |
Maria Goretti Fraga-Lopez |
|
|
Student contributors are acknowledged for their participation in the broader
research program and its numerical, computational, and dissemination work.
Formal software citation, release authorship, and copyright attribution remain
limited to the three principal researchers listed in CITATION.cff and the
license files.
Connecting meshless numerical methods, scientific machine learning, environmental modeling, and applied engineering
 SIIIA MATH Soluciones en Ingeniería 
Focus areas
|
ADR2D-Hybrid uses component-specific licensing:
- Source code and serialized model checkpoints: MIT License in
LICENSE. - Numerical corpora, structured evidence, and project figures: Creative
Commons Attribution 4.0 International in
LICENSE-DATA. - Upstream mGFD software: remains subject to the MIT terms of the mGFD repository.
- Third-party software: remains subject to its own licenses.
- Institutional logos and personal photographs: excluded from the MIT and CC BY grants and retained by their respective rights holders.
Copyright attribution identifies Gerardo Tinoco-Guerrero, Francisco J. Domínguez-Mota, and J. Alberto Guzmán-Torres as the principal investigators. The software and models are provided without warranty. Attribution must not imply endorsement by the authors or supporting institutions.
We thank the institutions and partners whose continuing support made numerical development, model training, independent validation, documentation, dissemination, and student participation possible.
 Universidad Michoacana de San Nicolás de Hidalgo UMSNH · Academic institution · Mexico 
Support provided
|
 Secretaría de Ciencia, Humanidades, Tecnología e Innovación SECIHTI · Federal science agency · Mexico 
Support provided
|
 International Centre for Numerical Methods in Engineering CIMNE · Research center and international collaboration 
Support provided
|
SIIIA MATH: Soluciones en Ingeniería Engineering and innovation partner 
Support provided
|
|
Aula CIMNE Morelia Research collaboration and training space 
Collaboration highlights
|
Coordinación de la Investigación Científica CIC-UMSNH · Institutional research coordination 
Collaboration highlights
|
| 📦 Framework | 👥 Community | ⭐ Contribution |
|---|---|---|
 |
Python Community | Reproducible scientific workflows |
 |
NumPy Community | Numerical arrays and corpus storage |
 |
SciPy Community | Sparse systems, geometry, and diagnostics |
 |
pandas Community | Scenario and validation tables |
 |
PyTorch Community | Training and reusable inference |
 |
mGFD Project | Point-cloud generation and methodological foundation |
 |
Matplotlib Community | Scientific visualization |
Scientific questions, reproducibility reports, and hybrid-model integration support
|
Primary Research Contact
Scientific coordination and hybrid-model integration Gerardo Tinoco-Guerrero Universidad Michoacana de San Nicolás de Hidalgo Morelia, Michoacán, Mexico 
|
Repository Support
Questions, reproducibility reports, and integration problems
|
What part of ADR2D-Hybrid is validated?
The selected hybrid checkpoint is accepted for the locked rectangular controlled-pulse domain with constant coefficients, 31 retained times, 289 base nodes, 8 <= Pe <= 40, and 0 <= Da <= 1.2. It improved all 18 held-out scenarios under that contract.
Is transfer to arbitrary irregular domains validated?
No. The unchanged hybrid improved all 27 retained irregular comparisons, but the finest perforated-domain numerical reference was unstable. The audit correctly reports
reference_inadequate, so geometric transfer has not been established.
Does the neural network replace the mGFD solver?
No. The hybrid receives a completed moderate-resolution mGFD trajectory and predicts a correction at the 31 retained output times. It does not replace internal numerical time steps.
Can I supply a different point cloud?
Yes. The point-cloud protocol can generate a cloud from a contour or load an mGFD-compatible CSV. Learned inference outside the validated support requires
allow_unvalidated_geometry=True, and the returned metadata continue to state that predictive accuracy is unvalidated.
Why are negative values clipped?
Both learned models can produce small negative values, especially in nearly empty regions. The accepted interface explicitly clips them and then restores exact boundary values. Raw fields and projection diagnostics remain available for transparency.
Are the reported speed-ups portable?
No. They describe one CPU implementation and environment. Rebenchmark the complete workflow on the intended hardware before making performance claims.
Is ADR2D-Hybrid ready for autonomous environmental decisions?
No. The evidence is synthetic and does not include field measurements, heterogeneous media, uncertain sensors, or independent deployment campaigns. It is a research and prototyping artifact.
Reproducible meshless hybrid modeling for two-dimensional reactive transport
If this model supports your research, please cite the release and its mGFD methodological reference.