Bilingual scientific visualization of validated one-dimensional reactive-transport simulations.
Compare analytical, finite-volume, and neural concentration fields through a responsive, traceable, and server-independent web application.
- Overview
- Application Views
- Repository Structure
- Installation
- Quick Start
- Browser Dataset
- Scientific Scope
- Validation and Reproducibility
- Institutional Deployment
- Language and Accessibility
- Data Provenance
- Limitations and Responsible Use
- How to Cite
- Research Team
- Industry Partners
- License and Rights
- Acknowledgments
- Contact and Support
- FAQ
ADR1D Explorer is a static web application for inspecting one-dimensional advection-dispersion-reaction simulations on common spatial and temporal coordinates. It presents an analytical reference, a fine-grid finite-volume solution, and the frozen ADR1D-NN neural surrogate without recalculating or altering the published scientific values in the browser.
The interface is intended for researchers, students, technical professionals, and readers who need a direct visual account of contaminant propagation. It places concentration profiles first, keeps accuracy separate from runtime, documents the limits of the synthetic benchmark, and exposes the provenance and validation evidence behind every retained scenario.
- 📈 Large-format concentration profiles: compare the three methods at any retained simulation time.
- 🗺️ Space-time inspection: examine concentration or signed error over the full retained domain and time interval.
- ⏱️ Synchronized temporal control: step, scrub, or animate each selected scenario.
- 🔬 Scenario diagnostics: inspect RMSE, MAE, maximum error, integrated-mass error, arrival-time error, and PDE-residual evidence.
- ⚖️ Cross-scenario comparison: filter and rank diagnostically useful cases while keeping accuracy and runtime in separate views.
- 🔍 Traceable evidence: inspect coverage, data contracts, source identifiers, validation checks, and interpretation limits.
- 🌐 Complete bilingual interface: switch between English and Spanish without reloading the application.
- 💾 Portable static distribution: deploy the same
dist/contents under either approved institutional server path.
| Item | Value |
|---|---|
| Complete comparison cohort | 120 scenarios |
| Interactive subset | 14 scenarios |
| Physical regimes represented | 4 |
| Time coordinates per scenario | 49 |
| Position coordinates per scenario | 360 |
| Compared fields | Analytical, finite volume, and ADR1D-NN |
| Serialized field values | 740,880 |
| Source prediction rows checked | 2,116,800 |
| Independent numeric comparisons | 746,998 |
| Maximum copied-field discrepancy | 0.0 |
| Maximum metric discrepancy | (9.99\times10^{-16}) |
| Browser-data size | Approximately 11.6 MB |
| Scheduled development period | November-December 2025 |
| Initial software release | November 2025 |
| Validation and documentation update | August 2026 |
| Package version | 1.0.0 |
The scheduled period records the research plan. Dataset generation, independent validation, interface verification, and public-release preparation retain their actual 2026 dates in the machine-readable evidence.
The initial screen is the scientific workspace rather than a marketing page. It provides:
- scenario selection grouped by physical regime;
- Péclet and Damköhler numbers and the dimensional transport parameters;
- a concentration profile synchronized with the selected simulation time;
- independent visibility controls for analytical, finite-volume, and neural fields;
- scenario-level error and physical-diagnostic metrics;
- a complementary space-time concentration or signed-error map;
- PNG chart export and JSON scenario download.
The comparison view provides:
- paired scenario RMSE values for finite volume and ADR1D-NN;
- filters by regime and sorting by identifier, Péclet number, or disagreement;
- direct navigation from a comparison point to the complete scenario view;
- median runtime evidence for the common 120-scenario workload;
- explicit separation between accuracy evidence and computational cost.
The evidence view reports:
- dataset identity, version, validation date, coverage, and dimensions;
- machine-readable source artifact identifiers;
- independent checks and maximum numerical discrepancies;
- definitions of the three compared methods;
- known limits of the selected subset and timing environment.
The About view explains:
- the scientific purpose and represented problem class;
- the methodological chain from scenario definition to browser serialization;
- authorship, affiliation, institutional support, and contact information;
- archived project resources and scientific references;
- the non-destructive relationship between the interface and its static data.
Every view uses the same language state, method colors, units, scenario identity, and validated dataset version.
.
|-- README.md
|-- CITATION.cff
|-- LICENSE
|-- LICENSE-DATA
|-- package.json
|-- package-lock.json
|-- index.html
|-- vite.config.js
|-- src/
| |-- components/
| |-- hooks/
| |-- i18n/
| |-- lib/
| |-- assets/
| |-- App.jsx
| |-- App.test.jsx
| |-- main.jsx
| `-- styles.css
|-- public/
| |-- manifest.json
| |-- scenario_index.json
| `-- scenarios/
| `-- <scenario_id>.json
|-- contracts/
| `-- browser_data_contract.json
|-- validation/
| `-- source_validation.json
|-- scripts/
| `-- validate-public-dataset.mjs
|-- docs/
| |-- logo/
| |-- team/
| `-- partners/
`-- .github/
`-- workflows/
`-- verify.yml
public/ is copied automatically into the production build by Vite. The
generated dist/ directory is excluded from version control because it can be
reconstructed from the repository at any time.
The repository uses one authoritative README. Scientific scope, deployment, validation, licensing, and responsible-use guidance are documented here, while exact values remain available in JSON files for automated inspection.
| Component | Supported configuration |
|---|---|
| Node.js | 20.19 or newer; Node.js 22 recommended |
| Package manager | npm with the included lockfile |
| Operating system | Linux, macOS, or Windows |
| RAM | 2 GB available for development and build |
| Storage | Approximately 190 MB after installation, including node_modules/ and the production build |
| Accelerator | Not required |
| Production server | Any HTTPS-capable static file server |
git clone https://github.com/gstinoco/ADR1D-Explorer.git
cd ADR1D-Explorer
npm cinpm ci installs the versions recorded in package-lock.json. It is preferred
over an unconstrained installation when reproducing the validated release.
npm run validate:data
npm testExpected dataset-validation message:
Validation status: ok (14 scenarios, 740,880 field values).
npm run devOpen:
http://127.0.0.1:4173/
The application initially requests only manifest.json and
scenario_index.json. A scenario bundle is loaded when selected, retained in
memory, and followed by one anticipated bundle. The complete 11.6 MB subset is
therefore not transferred before the first result appears.
npm run verifyThis command:
- validates the real browser dataset and public contract;
- executes the transformation, translation, interaction, and accessibility tests;
- creates a clean production build under
dist/.
npm run previewOpen:
http://127.0.0.1:4174/
The preview uses the same relative URLs that support institutional deployment
under /ADR1D_explorer/.
public/manifest.json is the authoritative release summary. It records source
identifiers, selection counts, dimensions, file inventory, serialization
rules, limitations, and the independent validation summary.
public/scenario_index.json contains lightweight scenario metadata,
selection roles, common coordinate definitions, scenario-level RMSE, and
runtime context.
Each public/scenarios/<scenario_id>.json bundle contains:
| Object | Content |
|---|---|
metadata |
Physical parameters, source timing, regime, and dimensionless numbers |
grid.time_s |
49 elapsed-time coordinates from 0 to 86,400 s |
grid.x_m |
360 retained positions from 1.25 to 898.75 m |
fields |
Three flattened concentration fields in time-major order |
metrics |
Accuracy, mass, arrival-time, and residual diagnostics |
highlights |
Locations of selected maximum discrepancies |
provenance |
Stable public artifact identifiers |
For a position count (N_x=360), a value at time index (i) and position index (j) is stored at:
Every method preserves the same coordinate order:
analytical_reference
traditional_finite_volume
adr1d_nn
The JSON values use round-trip floating-point serialization. No decimal rounding, spatial subsampling, temporal subsampling, or new scientific approximation was introduced for the web application.
The 14-case subset was chosen before interface interpretation using documented rules:
- one central Latin-hypercube scenario per physical regime;
- one boundary-profile case per regime;
- one additional large-disagreement case per regime;
- global neural-advantage, largest-neural-RMSE, and largest-finite-volume-RMSE roles;
- duplicate scenarios retained once with every applicable role attached.
The selection is diagnostic rather than statistically representative of all possible transport problems. Complete aggregate context remains tied to the 120-scenario comparison.
After retardation scaling, the represented one-dimensional transport problem is:
The initial condition is:
The finite-pulse inlet is written without a piecewise rendering dependency:
The indicator equals one while the source pulse is active and zero otherwise. The visualized quantity is the normalized concentration (C/C_0).
| Method | Role in the application | Interpretation |
|---|---|---|
| Analytical reference | Special-case accuracy reference | Reactive finite-pulse extension of the Ogata-Banks response |
| Fine finite volume | Traditional numerical approximation | Fine 2.5 m retained grid on the documented computational domain |
| ADR1D-NN | Frozen neural surrogate | Prediction from the validated physics-constrained neural model |
The analytical solution is available only for the documented problem class. It should not be interpreted as a universal closed-form reference for general heterogeneous, multidimensional, or nonlinear transport.
The application keeps the following quantities separate:
- root-mean-square error;
- mean absolute error;
- maximum absolute error and its location;
- integrated-mass relative error;
- arrival-time absolute error;
- PDE-residual RMSE;
- median runtime under the documented common workload.
No composite score combines accuracy and execution time.
The browser dataset was checked against the complete comparison evidence before
public packaging. The preserved report is
validation/source_validation.json.
| Check | Result |
|---|---|
| Selected-scenario inventory | Passed |
| Coordinates match source | Passed |
| Field values match source exactly | Passed |
| Copied metrics match source | Passed |
| Principal metrics recomputed | Passed |
| Runtime context matches source | Passed |
| Public provenance is standalone | Passed |
| Numeric comparisons | 746,998 |
| Maximum field discrepancy | 0.0 |
| Maximum metric discrepancy | (9.99\times10^{-16}) |
Run:
npm run validate:dataThe public validator independently checks:
- manifest, index, contract, and source-validation identity;
- the 14-file scenario inventory and recorded byte sizes;
- unique and safe scenario paths;
- 49 time and 360 position coordinates per scenario;
- strictly increasing finite coordinates;
- 17,640 finite field values per method and scenario;
- recomputed total of 740,880 serialized field values;
- absence of private workspace paths in public scientific metadata.
Run:
npm testThe test suite checks:
- numerical transformation helpers;
- complete key parity between English and Spanish dictionaries;
- language persistence and HTML
langupdates; - loading, scenario selection, and all four application views;
- profile precedence over the complementary space-time map;
- standalone public provenance;
- project, DOI, GitHub, institutional, and proceedings links;
- structural accessibility audits in both languages.
The local workflow in .github/workflows/verify.yml runs npm ci and
npm run verify on pushes, pull requests, and manual requests. It uploads
dist/ as the workflow artifact ADR1D-Explorer-web-build.
The workflow does not deploy to GitHub Pages or either institutional server. Publication remains a deliberate action performed by the repository owner or an authorized server administrator.
ADR1D Explorer is publicly available through two institutional deployments:
- UMSNH: https://malla.umich.mx/ADR1D_explorer/
- SIIIA MATH: https://malla.siiia.com.mx/ADR1D_explorer/
The application does not require a subdomain, server-side runtime, database, API, or environment variable.
npm ci
npm run verifyThe deployable directory is:
dist/
Copy the contents of dist/, not the enclosing directory, into the
institutional web root corresponding to:
ADR1D_explorer/
The deployed directory should therefore contain:
ADR1D_explorer/
|-- index.html
|-- manifest.json
|-- scenario_index.json
|-- scenarios/
`-- assets/
Vite uses base: "./" in vite.config.js. JavaScript, CSS, images, the
manifest, index, and scenario bundles are referenced relative to
index.html. The same build can therefore be copied to either approved path
without rebuilding for a host-specific URL.
After copying the build:
- open the institutional URL over HTTPS;
- confirm that the header reports dataset version
1.0.0; - open at least one scenario from each physical regime;
- switch between English and Spanish;
- inspect the browser network panel for missing JSON or asset requests;
- test the application at desktop and mobile widths;
- confirm that a downloaded scenario JSON opens correctly.
Static assets may use long-lived caching because their filenames are hashed.
index.html, manifest.json, and scenario_index.json should be refreshed
when a new version is deployed.
English is the initial language. Spanish is available through the EN | ES
control, and the selection is retained locally under:
adr1d-explorer-language
Internationalization covers:
- navigation, loading, empty, and error states;
- physical parameters, regimes, and selection roles;
- chart titles, legends, axes, tooltips, and export labels;
- tables, metrics, diagnostic interpretations, and limits;
- evidence, references, institutional support, contact, and footer content;
- localized numbers, dates, and accessible names.
Accessibility provisions include:
- semantic landmarks and a skip-to-content link;
- keyboard-operable controls;
- visible focus states;
- text and line-style distinctions in addition to color;
- reduced-motion support;
- stable chart and control dimensions;
- responsive layouts from compact mobile screens to wide workstations;
- automated structural checks with
axe-core.
Automated checks do not replace manual keyboard, contrast, zoom, screen-reader, and device testing for a final institutional deployment.
ADR1D Explorer is a presentation layer over versioned products from the ADR1D research-software lineage. The public browser dataset retains stable artifact identifiers rather than local development paths.
- Tinoco-Guerrero, G., Domínguez-Mota, F. J., and Guzmán-Torres, J. A. (2026). ADR1D and WQP-NM-Nutrients: A Reproducible Contaminant-Transport Benchmark and Curated Water-Quality Snapshot. https://doi.org/10.5281/zenodo.21499528
- Tinoco-Guerrero, G., Domínguez-Mota, F. J., and Guzmán-Torres, J. A. (2026). ADR1D-NN: A Physics-Constrained Neural Surrogate for One-Dimensional Reactive Transport. https://doi.org/10.5281/zenodo.21500106
- Tinoco-Guerrero, G., Domínguez-Mota, F. J., and Guzmán-Torres, J. A. (2026). ADR1D-Validation: Reproducible Numerical Validation of ADR1D-ML and ADR1D-NN. https://doi.org/10.5281/zenodo.21499305
- Tinoco-Guerrero, G., Domínguez-Mota, F. J., and Guzmán-Torres, J. A. (2026). ADR1D-Optimized: Precision-Preserving Efficient Inference for Reactive Transport Models. https://doi.org/10.5281/zenodo.21520554
- Tinoco-Guerrero, G., Domínguez-Mota, F. J., and Guzmán-Torres, J. A. (2026). ADR1D-ML: Identifiable Parameter Inference for One-Dimensional Reactive Transport. https://doi.org/10.5281/zenodo.21500069
- Tinoco-Guerrero, G., Domínguez-Mota, F. J., and Guzmán-Torres, J. A. (2026). ADR1D-EWS: Causal Machine-Learning Early Warning for Reactive Contaminant Transport. https://doi.org/10.5281/zenodo.21538582
The first four resources directly support scenario definition, neural fields, validation, or runtime interpretation. ADR1D-ML and ADR1D-EWS document related models in the same research lineage; their parameter estimates and alert predictions are not displayed by this application.
- 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
- Chen, J.-S., and Liu, C.-W. (2011). Generalized analytical solution for advection-dispersion equation in finite spatial domain with arbitrary time-dependent inlet boundary condition. Hydrology and Earth System Sciences, 15, 2471-2479. https://doi.org/10.5194/hess-15-2471-2011
- Scharfetter, D. L., and Gummel, H. K. (1969). Large-signal analysis of a silicon Read diode oscillator. IEEE Transactions on Electron Devices, 16(1), 64-77. https://doi.org/10.1109/T-ED.1969.16566
- McKay, M. D., Beckman, R. J., and Conover, W. J. (1979). A comparison of three methods for selecting values of input variables in the analysis of output from a computer code. Technometrics, 21(2), 239-245. https://doi.org/10.1080/00401706.1979.10489755
- Efron, B., and Tibshirani, R. J. (1993). An Introduction to the Bootstrap. Chapman & Hall/CRC. https://doi.org/10.1201/9780429246593
- Paszke, A., Gross, S., Massa, F., et al. (2019). PyTorch: An imperative style, high-performance deep learning library. Advances in Neural Information Processing Systems, 32, 8024-8035. NeurIPS proceedings
- The displayed evidence is synthetic and one-dimensional; it is not a set of field observations.
- The 14 interactive scenarios are diagnostically selected and do not replace the complete 120-scenario comparison.
- The analytical reference applies only to the documented finite-pulse problem class.
- Runtime values describe one Apple arm64 CPU environment, one thread, and the retained workload. They are not universal hardware-independent benchmarks.
- Neural timings exclude offline model training.
- Low pointwise error or PDE residual does not establish field transfer, calibrated uncertainty, regulatory suitability, or operational reliability.
- The application does not infer chemical identity, source location, health risk, or remediation strategy.
- Browser interaction changes only presentation state. It does not retrain a model, recompute the scientific fields, or modify source evidence.
- ADR1D Explorer supports scientific communication and technical inspection; it should not be the sole basis for environmental, regulatory, engineering, or public-health decisions.
Gerardo Tinoco-Guerrero, Francisco J. Domínguez-Mota, and J. Alberto Guzmán-Torres (2026). ADR1D Explorer: Bilingual Interactive Visualization of Validated Reactive-Transport Simulations. Version 1.0.0. Universidad Michoacana de San Nicolás de Hidalgo. https://github.com/gstinoco/ADR1D-Explorer
Machine-readable metadata are available in CITATION.cff.
GitHub can display them through its Cite this repository interface. The
archival DOI should be added after the first public release is deposited.
Analyses using the visualized fields should also cite the upstream ADR1D, ADR1D-NN, validation, and optimization releases listed under Data Provenance.
@software{tinoco_guerrero_2026_adr1d_explorer,
author = {Tinoco-Guerrero, Gerardo and
Domínguez-Mota, Francisco J. and
Guzmán-Torres, J. Alberto},
title = {{ADR1D Explorer: Bilingual Interactive Visualization of
Validated Reactive-Transport Simulations}},
version = {1.0.0},
year = {2026},
institution = {Universidad Michoacana de San Nicolás de Hidalgo},
url = {https://github.com/gstinoco/ADR1D-Explorer}
}Researchers and students advancing reproducible numerical modeling, scientific machine learning, and environmental visualization
| 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 participate in the broader research program and its
scientific-software environment. Formal software citation, release metadata,
and copyright attribution remain limited to the three principal researchers
listed in CITATION.cff and the license files.
Connecting environmental modeling, scientific visualization, and applied engineering
|
Focus areas
|
ADR1D Explorer uses component-specific licensing:
- Source code: MIT License in
LICENSE. - Browser data, validation evidence, repository-authored documentation, and
ADR1D Explorer brand: Creative Commons Attribution 4.0 International in
LICENSE-DATA. - Upstream ADR1D products: remain subject to the attribution and licensing terms of their archived releases.
- Third-party software: remains subject to its own licenses.
- Institutional logos and personal photographs: are 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 application and data are provided without warranty. Attribution must not imply endorsement by the authors or supporting institutions.
We thank the institutions and partners whose continuing institutional and financial support made model development, validation, scientific visualization, documentation, dissemination, and student participation possible.
|
Collaboration highlights
|
Collaboration highlights
|
Scientific questions, reproducibility reports, interface problems, and institutional-deployment support
|
Primary Research Contact
Scientific coordination and visualization methodology Gerardo Tinoco-Guerrero Universidad Michoacana de San Nicolás de Hidalgo Morelia, Michoacán, Mexico |
Repository Support
Reproducible software and deployment reports
|
Does ADR1D Explorer run a numerical or neural model in the browser?
No. It loads validated static fields and metrics. Browser interaction changes the selected scenario, time, method, language, filters, and presentation state only.
Why are only 14 scenarios interactive?
The subset was selected by a documented diagnostic policy to cover all four physical regimes, representative cases, boundary profiles, large method disagreements, and global error extremes. Aggregate context still refers to the complete 120-scenario comparison.
Can I deploy the build under a directory instead of a subdomain?
Yes. All runtime resources use relative URLs. Copy the contents of
dist/ into the approved ADR1D_explorer/ directory on either institutional server.
Does the GitHub workflow publish the application automatically?
No. It validates, tests, builds, and uploads a downloadable workflow artifact. Only the repository owner or an authorized server administrator publishes files to the institutional servers.
Can I open dist/index.html directly from the file system?
Use a local HTTP server instead. Browser security policies can block JSON requests from
file:// pages. npm run preview serves the production build correctly.
Are the displayed results suitable for field or regulatory decisions?
No. The current evidence is synthetic, one-dimensional, and limited to the documented parameter space and methods. Field use requires site-specific data, calibration, uncertainty assessment, and independent validation.
How should a new release be deployed?
Tag and archive the validated source release, run
npm run verify, replace the complete contents of the institutional ADR1D_explorer/ directory with the new dist/ contents, and then repeat the post-deployment checks.











