ADR1D-Optimized ⚡

Precision-preserving optimized inference for ADR1D reactive-transport machine-learning models.

Two independently validated variants with lower processing time, unchanged scientific contracts, and reproducible public interfaces.

🔗 Quick Links

📋 Table of Contents

Overview
Repository Structure
Installation
Quick Start
Optimized Models
Optimization Design
Validated Results
Visual Results
Input and Output Contracts
Validation and Reproducibility
Data Provenance
Limitations
How to Cite
Research Team
Industry Partners
License and Rights
Acknowledgments
Contact and Support
FAQ

🌟 Overview

ADR1D-Optimized distributes two execution variants derived from the public ADR1D-ML and ADR1D-NN version 1.0.0 models:

ADR1D-ML-Compact-Conservative reduces the serialized inverse-parameter bundle by retaining the complete velocity and dispersion estimators and the classifier while shortening only the conditional-decay tree ensemble.
ADR1D-NN-Fast retains the original neural checkpoint byte for byte and replaces DataLoader inference with direct contiguous tensor batches.

Each variant was selected against its own source model and task. ADR1D-ML operates on one feature row per sensor scenario, whereas ADR1D-NN evaluates a space-time concentration field. Their raw times and RMSE values must therefore not be interpreted as rankings between the two models.

🔧 Key Capabilities

⚡ Faster inference: 1.25x for ADR1D-ML-Compact and 2.84x for ADR1D-NN-Fast on the documented one-thread CPU workloads.
🛡️ Preserved precision: exact source velocity, dispersion, and classification outputs plus non-inferior conditional-decay RMSE for ADR1D-ML; exact raw and constrained predictions for ADR1D-NN.
📦 Smaller inverse bundle: 1.32% secondary size reduction for the strict conservative ADR1D-ML artifact.
🔒 Frozen scientific contracts: no changed feature transformation, unit, domain range, decision threshold, checkpoint weight, or hard boundary condition.
🔬 Independent checks: separate validators reproduce the saved models, metrics, interfaces, and example workflows.
🔁 Self-contained release audit: one command verifies both public bundles without rewriting bundled evidence.

📊 Release at a Glance

Item	Value
Recommended optimized models	2
ADR1D-ML workload	45 parameter-inference scenarios
ADR1D-NN workload	112,455 concentration-field points
ADR1D-ML inference acceleration	1.25x
ADR1D-NN inference acceleration	2.84x
ADR1D-ML bundle reduction	1.32%
Maximum preserved-output difference	0.0 for both models
Independent validation status	Passed for both models
Scheduled development period	July 2025
Initial code release	July 2025
Optimization and documentation update	July 2026
Package version	1.0.0

The scheduled period records the project plan. Candidate execution, independent validation, and release preparation occurred in July 2026 and retain their actual dates in the machine-readable evidence.

📂 Repository Structure

.
|-- README.md
|-- CITATION.cff
|-- LICENSE
|-- LICENSE-DATA
|-- requirements.txt
|-- configs/
|   |-- optimization_protocol.json
|   |-- adr1d_nn_fast_protocol.json
|   `-- adr1d_nn_model_protocol.json
|-- data/
|   |-- example_features.csv
|   |-- example_sources.csv
|   |-- example_sensor_observations.csv
|   `-- example_points.csv
|-- models/
|   |-- adr1d_parameter_models_compact.joblib
|   |-- adr1d_ml_compact_manifest.json
|   |-- adr1d_nn_fast.pt
|   `-- adr1d_nn_fast_manifest.json
|-- results/
|   |-- adr1d_ml_compact_*.json
|   |-- adr1d_nn_fast_*.json
|   |-- example_parameter_predictions.csv
|   |-- example_concentration_predictions.csv
|   |-- optimized_model_comparison.csv
|   `-- optimization_summary.json
|-- scripts/
|   |-- extract_sensor_features.py
|   |-- predict_parameters.py
|   |-- predict_concentration_fast.py
|   `-- validate_release.py
`-- docs/
    |-- optimization_comparison.png
    |-- optimization_comparison.pdf
    |-- team/
    `-- partners/

The repository keeps one authoritative README rather than placing additional documentation files inside every directory. Protocols, schemas, commands, and limitations are maintained here and in the corresponding machine-readable JSON files.

📦 Installation

System Requirements

Component	Supported configuration
Python	3.12
Operating system	Linux, macOS, or Windows
RAM	4 GB minimum; 8 GB recommended
Accelerator	Not required; reported benchmarks use CPU
Trusted artifacts	Use only the model files distributed with this release

Pinned Dependencies

Package	Version	Role
NumPy	2.0.2	Numerical transformations and validation
pandas	2.2.3	Sensor, feature, and point tables
SciPy	1.16.2	scikit-learn runtime dependency
scikit-learn	1.7.0	Extra Trees and logistic-classifier inference
Joblib	1.4.2	ADR1D-ML bundle loading
PyTorch	2.7.1	ADR1D-NN inference

Clone and Install

git clone https://github.com/gstinoco/ADR1D-Optimized.git
cd ADR1D-Optimized

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

Installation Check

python -c "import joblib, numpy, pandas, sklearn, torch; print('Dependencies available')"
python scripts/validate_release.py

The second command verifies models, examples, optimization reports, and the two public inference interfaces.

🚀 Quick Start

Validate the Complete Release

python scripts/validate_release.py

A successful run ends with "status": "ok", reports two optimized models, and confirms that both reduce inference time while preserving precision.

Infer Parameters from Prepared Features

python scripts/predict_parameters.py \
  --input-csv data/example_features.csv \
  --output-csv results/my_parameter_predictions.csv

Start from Six-Sensor Histories

python scripts/extract_sensor_features.py \
  --sources-csv data/example_sources.csv \
  --observations-csv data/example_sensor_observations.csv \
  --output-csv results/my_features.csv

python scripts/predict_parameters.py \
  --input-csv results/my_features.csv \
  --output-csv results/my_parameter_predictions.csv

Predict Concentration Fields

python scripts/predict_concentration_fast.py \
  --input-csv data/example_points.csv \
  --output-csv results/my_concentration_predictions.csv \
  --device cpu

The quick-start outputs are ignored by Git and do not replace the bundled reference examples.

⚙️ Optimized Models

ADR1D-ML-Compact-Conservative

ADR1D-ML estimates effective transport quantities from 86 descriptors derived from six noisy sensor histories. The source bundle contains three 300-tree Extra Trees regressors plus a logistic classifier for decay resolvability.

The conservative variant uses:

Component	Source trees	Optimized trees	Treatment
Effective velocity	300	300	Source pipeline retained exactly
Effective dispersion	300	300	Source pipeline retained exactly
Conditional decay	300	50	Validation-selected deterministic prefix
Decay resolvability	Logistic classifier	Unchanged	Parameters and threshold retained exactly

The classifier threshold remains 0.19. An earlier 25/50/50-tree candidate was smaller and faster but increased canonical-test velocity RMSE by 20.8%. That candidate remains part of the internal study but is deliberately excluded from this recommended public release. A later 300/50/50-tree variant retained the source velocity pipeline but its 50-tree dispersion estimator increased validation RMSE by 2.59%. The strict 300/300/50-tree release therefore changes only conditional decay. The test result informed the conservative revision, so the test comparison is descriptive and is not called an unseen final evaluation.

ADR1D-NN-Fast

ADR1D-NN is a 34,177-parameter coordinate-conditioned multilayer perceptron that predicts normalized concentration from position, time, effective transport parameters, and finite-pulse source timing. The optimized release:

keeps the 141,059-byte checkpoint byte-identical to ADR1D-NN 1.0.0;
retains all seven feature transformations and their stored statistics;
evaluates contiguous float32 tensor slices directly;
uses the validation-selected batch size of 16,384 points;
preserves the exact zero initial interior condition;
preserves the exact active and inactive finite-pulse inlet conditions.

The optimization removes per-row TensorDataset and DataLoader indexing from inference. It does not retrain, prune, quantize, or otherwise alter the neural weights.

📐 Optimization Design

Pre-Specified Comparison Rules

Both studies use paired measurements under one native CPU thread. Input tables and transformed features are resident in memory before timing; CSV parsing and output serialization are excluded. Each timing report contains warm-up runs, 15 measured repetitions, medians, quartiles, extrema, and the complete timing vector.

Time, precision, artifact size, and Python-traced memory are reported together. A candidate cannot be promoted solely because it is faster.

ADR1D-ML Chronology

Candidate tree counts were trained with train and selected with validation.
A shared tree count produced no useful compression.
Independent counts produced the aggressive 25/50/50-tree candidate.
Canonical test exposed the velocity degradation.
Protocol revision 1.2 retained the complete velocity estimator and defined a 300/50/50-tree conservative bundle.
Review of the official product wording required no precision sacrifice; the 2.59% validation-RMSE increase from reduced dispersion was therefore rejected.
Protocol revisions 1.3 and 1.3.1 defined the strict 300/300/50-tree bundle, with a minimum 1.10x inference acceleration and no required percentage of artifact-size reduction.
The resulting comparison is labelled descriptive because test informed an earlier revision.

ADR1D-NN Chronology

validation compared the reference DataLoader, direct eager tensor batches, frozen TorchScript batches, and dynamic int8 quantization.
Batch sizes 8,192, 16,384, 32,768, 65,536, and the complete field were evaluated.
Quantization was unsupported by the available CPU engine and was retained as an explicit negative result.
Eager and TorchScript candidates reproduced all validation predictions exactly.
The protocol preferred direct eager execution when it lay within 5% of the fastest eligible candidate; 16,384 rows was selected.
The fixed candidate was then evaluated once on canonical test without any weight or execution-rule revision.

The locked details are available in optimization_protocol.json and adr1d_nn_fast_protocol.json.

📊 Validated Results

Computational Comparison

Measure	ADR1D-ML source	ADR1D-ML Compact	ADR1D-NN source	ADR1D-NN Fast
Work units	45 scenarios	45 scenarios	112,455 points	112,455 points
Median inference	0.01878 s	0.01504 s	0.23742 s	0.08371 s
Paired acceleration	1.00x	1.25x	1.00x	2.84x
Persisted model or bundle	7,114,591 B	7,020,956 B	141,059 B	141,059 B
Source-size percentage	100%	98.68%	100%	100%
Peak Python-traced memory	100%	100.03%	100%	32.41%

The workloads represent different scientific tasks. Only each optimized-source pair is comparable.

Precision Comparison

Quantity	Source	Optimized	Difference
ADR1D-ML velocity RMSE, log10	0.0241082	0.0241082	0.0
ADR1D-ML dispersion RMSE, log10	0.2245863	0.2245863	0.0
ADR1D-ML conditional-decay RMSE, log10	0.2852087	0.2814055	-0.0038032
ADR1D-ML balanced classification accuracy	0.7564103	0.7564103	0.0
ADR1D-NN concentration RMSE	0.0215128	0.0215128	0.0
ADR1D-NN concentration R-squared	0.9910480	0.9910480	0.0
ADR1D-NN maximum prediction difference	--	--	0.0
ADR1D-NN constraint-label mismatches	--	--	0

The complete candidate grids and timing vectors are distributed in the results/ JSON reports. The concise two-model table is available as optimized_model_comparison.csv. For conditional decay, the 50-tree candidate attained a validation-to-source RMSE ratio of 0.9000 before development refitting and a test-to-source ratio of 0.9867 after refitting; values below 1 indicate lower error.

🎨 Visual Results

Validated comparison of ADR1D-ML-Compact and ADR1D-NN-Fast

Task-specific acceleration, artifact size, RMSE preservation, and Python-traced memory. Each optimized model is compared only with its own source.

Vector PDF | Comparison table | Structured summary

📥 Input & Output Contracts

ADR1D-ML-Compact Input

predict_parameters.py expects the 86 columns declared by the serialized bundle. The public feature extractor creates these columns from:

Table	Required information
Source metadata	`scenario_id`, source concentration, source start, source duration
Sensor observations	Six fixed sensors, 49 times, observed concentration, detection-limit flag

The exact public schema is demonstrated in example_features.csv. Additional metadata columns are allowed.

ADR1D-ML-Compact Output

Column	Meaning
`effective_velocity_m_s`	Estimated effective advection velocity
`effective_dispersion_m2_s`	Estimated effective dispersion coefficient
`decay_resolvable_probability`	Classifier probability for resolvable decay
`decay_resolvable`	Binary decision at threshold 0.19
`decay_status`	Operational interpretation of the decision
`decay_rate_if_resolvable_s_1`	Conditional decay-regressor output
`reported_decay_rate_s_1`	Decay estimate only when classified as resolvable

An unresolved decay rate is reported as missing, not silently replaced by zero.

ADR1D-NN-Fast Input

Column	Unit	Constraint
`x_m`	m	Within the modeled domain
`time_s`	s	Within the modeled interval
`domain_length_m`	m	Positive; 1,000 m in the strict contract
`final_time_s`	s	Positive; 86,400 s in the strict contract
`effective_velocity_m_s`	m/s	Positive and within the design range
`effective_dispersion_m2_s`	m2/s	Positive and within the design range
`decay_rate_s_1`	1/s	Non-negative and within the design range
`source_start_s`	s	Non-negative
`source_duration_s`	s	Positive; pulse must end within final time

Optional scenario_id values are propagated. The complete domain ranges are defined in adr1d_nn_model_protocol.json.

ADR1D-NN-Fast Output

Column	Meaning
`scenario_id`	Propagated identifier when provided
`x_m`, `time_s`	Input coordinates
`predicted_normalized_concentration`	Bounded prediction in [0, 1]
`constraint_applied`	Neural interior, initial interior, active inlet, or inactive inlet

✅ Validation & Reproducibility

Level 1: Self-Contained Release Validation

python scripts/validate_release.py

This read-only workflow verifies the complete release contract:

both serialized model digests before deserialization;
the ML bundle and manifest protocol contract;
the NN checkpoint, source protocol, optimization protocol, and interface;
exact reproduction of 86 features for three sensor scenarios;
reproduction of three compact parameter predictions;
reproduction of 9,996 fast concentration predictions for four fields;
the strict 300/300/50 tree configuration and preserved ML components;
non-inferior conditional-decay RMSE during selection and test;
all bundled model and validation statuses;
two accepted optimized models;
reduced inference time for both models;
preserved precision for both models.

To save the validation output outside the tracked evidence:

python scripts/validate_release.py --output reproduction/release_validation.json

Level 2: Inspect Candidate Selection

The complete validation-only candidate records are text-based JSON files:

They retain accepted, rejected, and unsupported candidates, full timing vectors, memory probes, exactness checks, and the fixed selection rule.

Level 3: Inspect Independent Validation

adr1d_ml_compact_validation.json reloads the conservative bundle through the ADR1D-ML public API, verifies every strict precision condition, and repeats a paired public-interface benchmark that measured a 1.27x acceleration in the documented environment.
adr1d_nn_fast_validation.json reloads both public interfaces, checks complete validation and test splits, exercises the CLI, and repeats an independent timing measurement.

Complete retraining data are not duplicated here. The optimization depends on the public ADR1D, ADR1D-ML, and ADR1D-NN releases described below.

🔍 Data Provenance

Upstream resource	Role	Location
ADR1D 1.0.0	Canonical scenarios and analytical fields	GitHub, Zenodo
ADR1D-ML 1.0.0	Source inverse-parameter bundle and feature contract	GitHub
ADR1D-NN 1.0.0	Source neural checkpoint and physical contract	GitHub
ADR1D-Validation	Independent challenge and computational baseline	GitHub

The release does not redistribute publisher material, private measurements, or external credentials. Example tables are derived from the open ADR1D benchmark and are covered by LICENSE-DATA.

⚠️ Limitations & Responsible Use

Timings describe the documented Apple arm64 machine, Python 3.12.2, package versions, warm-cache state, workload sizes, and one-thread CPU policy.
Speed-ups should be remeasured on the intended deployment platform.
Python tracemalloc may not observe every allocation retained exclusively by NumPy, scikit-learn, PyTorch, BLAS, or operating-system libraries.
ADR1D-ML-Compact inherits the sensor geometry, feature contract, uncertainty, and decay-resolvability limits of ADR1D-ML 1.0.0.
The conservative ADR1D-ML test comparison is descriptive because the test result informed recovery of the complete velocity pipeline.
ADR1D-NN-Fast inherits the one-dimensional domain, parameter ranges, source formulation, and extrapolation limits of ADR1D-NN 1.0.0.
Exact equality on the documented CPU environment does not imply bitwise identity across every hardware backend or future library version.
Faster learned inference is not evidence of improved physical fidelity and does not replace model calibration, uncertainty analysis, or field validation.

📝 How to Cite

Preferred Software Citation

Gerardo Tinoco-Guerrero, Francisco J. Domínguez-Mota, and J. Alberto Guzmán-Torres (2026). ADR1D-Optimized: Precision-Preserving Efficient Inference for Reactive Transport Models. Version 1.0.0. Universidad Michoacana de San Nicolás de Hidalgo. https://github.com/gstinoco/ADR1D-Optimized

Machine-readable metadata are available in CITATION.cff. GitHub can display these data directly through its Cite this repository interface. An archival DOI can be added to the citation metadata after the first public release is deposited.

Analyses should also cite the upstream model actually used:

ADR1D for the benchmark data;
ADR1D-ML for parameter inference;
ADR1D-NN for concentration-field inference.

Scientific References

Geurts, P., Ernst, D., and Wehenkel, L. (2006). Extremely randomized trees. Machine Learning, 63, 3-42. https://doi.org/10.1007/s10994-006-6226-1
Paszke, A., et al. (2019). PyTorch: An imperative style, high-performance deep learning library. Advances in Neural Information Processing Systems, 32, 8024-8035.
Ogata, A., and Banks, R. B. (1961). A solution of the differential equation of longitudinal dispersion in porous media. U.S. Geological Survey Professional Paper 411-A. https://doi.org/10.3133/pp411A

🧑‍🔬 Research Team

🌟 Meet the Team

Researchers and students advancing reproducible scientific machine learning and numerical modeling for reactive transport

👥 Main Researchers

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

🎓 Ph.D. Research Students

Gabriela Pedraza-Jiménez
_{Ph.D. research student}

Eli Chagolla-Inzunza
_{Ph.D. research student}

🎓 M.Sc. Research Students

Jorge L. González-Figueroa
_{M.Sc. research student}

Christopher N. Magaña-Barocio
_{M.Sc. research student}

🎓 Undergraduate Research Students

Maria Goretti Fraga-Lopez
_{Undergraduate research student}

Student contributors are acknowledged for their participation in the broader research program. Formal software citation and copyright attribution remain limited to the three principal researchers listed in CITATION.cff and the license files.

🏭 Industry Partners Supporting Innovation

🌟 Academic-Industry Collaboration

Connecting efficient scientific machine learning with applied engineering and technology transfer

SIIIA MATH: Soluciones en Ingeniería supports applied research, engineering development, financial continuity, and technology-transfer perspectives for the broader research program.

📄 License & Rights

ADR1D-Optimized uses component-specific licensing:

Source code and serialized model bundles: MIT License in LICENSE.
Example tables, reported results, and figures: Creative Commons Attribution 4.0 International in LICENSE-DATA.
Upstream ADR1D content: remains subject to the attribution and licensing terms of the archived ADR1D release.
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.

🙏 Acknowledgments

❤️ Institutional and Financial Support

We thank the institutions whose continuing support made model development, optimization, validation, documentation, dissemination, and student participation possible.

Universidad Michoacana de San Nicolás de Hidalgo _{Research infrastructure, academic supervision, CIC-UMSNH coordination, and institutional funding}	Secretaría de Ciencia, Humanidades, Tecnología e Innovación _{Scientific, technological, and financial support in Mexico}
CIMNE and Aula CIMNE Morelia _{Collaboration, training, numerical methods, and international scientific links}	SIIIA MATH: Soluciones en Ingeniería _{Applied research, engineering development, funding, and technology transfer}

The authors acknowledge the Coordinación de la Investigación Científica de la Universidad Michoacana de San Nicolás de Hidalgo (CIC-UMSNH) and Aula CIMNE Morelia for their continuing institutional support.

📧 Contact & Support

Scientific questions, reproducibility reports, and model-integration support

Channel	Use
GitHub Issues	Reproducible software, model-loading, or documentation problems
gerardo.tinoco@umich.mx	Scientific coordination and research questions
ORCID	Researcher identity and related outputs

When reporting a problem, include the operating system, Python version, exact command, complete traceback, and whether python scripts/validate_release.py succeeds.

💬 FAQ

Are these newly trained models?

No. ADR1D-ML-Compact shortens only the deterministic conditional-decay tree ensemble, while ADR1D-NN-Fast keeps the original checkpoint byte for byte and changes only its inference path.

Does either recommended model lose precision?

No loss was observed under the documented comparisons. ADR1D-ML preserves source velocity, dispersion, and classification exactly while slightly improving conditional-decay RMSE during selection and test. ADR1D-NN reproduces every raw and constrained prediction exactly.

Why is the aggressive compact model not included?

Its 25-tree velocity estimator increased canonical-test velocity RMSE by 20.8%. It remains documented internally as an efficiency trade-off but does not satisfy this release's precision-preservation requirement.

Will the same speed-up occur on every computer?

Not necessarily. The reported values are paired measurements for one documented environment. Run the release validator and benchmark the intended application on its deployment hardware.

Can the models be used outside the ADR1D ranges?

Such use is not validated. ADR1D-NN rejects out-of-range inputs by default, and both models inherit the applicability limits of their upstream releases.

Advancing reproducible and efficient scientific machine learning for environmental transport

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