PINN Strength Carbonation Diffusion

Reproducible Python research code for inverse physics-informed neural network (PINN) modeling of 1D carbonation reaction-diffusion in CO2 storage backfill materials.

The repository implements the full path from raw CSV validation to empirical baselines, finite-difference forward simulation, inverse PINN training, held-out model comparison, uncertainty diagnostics, and manuscript-facing publication artifacts.

Highlights

• Python 3.13 research codebase with editable package installation.
• Raw CSV inputs are kept immutable under data/.
• Schema validation and standardized observation-table generation.
• Empirical carbonation-front baselines.
• 1D finite-difference reaction-diffusion forward solver.
• PyTorch-first inverse PINN implementation.
• Constant-diffusion and carbonation-dependent decaying-diffusion variants.
• Depth-only and depth-plus-UCS training modes.
• Grouped and global parameter workflows by initial carbonation age.
• Formal held-out protocol and final campaign commands.
• Tests for data handling, solvers, PINNs, diagnostics, and reporting.

Scientific Scope

The v1 model uses a 1D axial-ingress formulation motivated by side-sealed CO2 exposure:

dc/dt = d/dx(D(alpha) dc/dx) - k c b
db/dt = -nu k c b
alpha(x,t) = 1 - b(x,t)

where c(x,t) is normalized CO2 concentration, b(x,t) is normalized remaining reactive capacity, and alpha(x,t) is the carbonation degree.

Implemented diffusion laws:

constant: D(alpha) = D0
decaying: D(alpha) = D0 exp(-gamma alpha)

Carbonation depth is treated as the primary inverse target. UCS is an auxiliary observation target and is not modeled as a PDE state.

Repository Layout

.
|-- configs/        # JSON configs for validation, training, protocols, campaigns
|-- data/           # Immutable raw and curated CSV inputs
|-- experiments/    # Revision-suite orchestration scripts
|-- figures/        # Manuscript/supporting figures included with this release
|-- scripts/        # Dataset preparation and paper-figure helper scripts
|-- src/            # Python package source code
|-- tables/         # Manuscript/supporting tables included with this release
|-- tests/          # pytest test suite
|-- AGENTS.md       # Development and modeling rules used during implementation
|-- PLANS.md        # Recorded implementation plans
|-- pyproject.toml  # Package metadata, dependencies, and CLI entry points
`-- README.md

Generated training outputs are intentionally not committed. Commands write new artifacts under outputs/.

Installation

Create a Python 3.13 environment and install the package in editable mode:

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e .[dev]

On Linux or macOS, activate the environment with:

source .venv/bin/activate

Core dependencies are numpy, scipy, torch, and matplotlib. pytest is installed through the dev extra. DeepXDE is intentionally optional and is not required for the default workflows.

Quick Start

Run data validation, the baseline model, the finite-difference solver, PINN training, evaluation, and tests:

pcd-validate-data --config configs/data_validation.json
pcd-train-baseline --config configs/baseline.json
pcd-forward-solve --config configs/forward_solver.json
pcd-train-pinn --config configs/pinn.json
pcd-evaluate --config configs/evaluation.json
pytest

Main Phase 2 outputs are written to:

• outputs/validate_data/latest/standardized_observations.csv
• outputs/train_baseline/latest/
• outputs/forward_solve/latest/
• outputs/train_pinn/latest/
• outputs/evaluate/latest/

Data

The repository uses CSV files already placed under data/. The primary supervised table is:

data/fang2024_core_timeseries_long.csv

It contains digitized carbonation-depth and UCS observations for initial carbonation-age groups of 3, 7, 14, and 28 days. Additional CSV files provide metadata, chemistry, fiber properties, porosity, aperture distributions, and literature-derived auxiliary observations.

Raw input files should not be renamed or overwritten. The validation workflow infers and validates schemas before building standardized observation tables.

Command-Line Workflows

The package exposes these console commands after editable installation:

pcd-validate-data
pcd-train-baseline
pcd-forward-solve
pcd-train-pinn
pcd-evaluate
pcd-run-phase3-ablation
pcd-run-phase3-identifiability
pcd-run-phase3-uncertainty
pcd-run-phase3-sensitivity
pcd-run-phase3-report
pcd-run-phase3b-protocol
pcd-run-final-campaign
pcd-run-manuscript-synthetic-recovery
pcd-run-manuscript-targeted-ablation
pcd-run-multisource-inverse
pcd-run-revision-suite
pcd-collect-revision-results

Each command accepts a JSON config through --config when applicable.

Phase 3: Ablation and Diagnostics

Phase 3 expands the inverse-model evaluation with ablations, identifiability checks, uncertainty estimates, and sensitivity workflows.

Shortlist run:

pcd-run-phase3-ablation --config configs/phase3_standard.json

Expanded workflows:

pcd-run-phase3-ablation --config configs/phase3_ablation.json
pcd-run-phase3-identifiability --config configs/phase3_identifiability.json
pcd-run-phase3-uncertainty --config configs/phase3_uncertainty.json
pcd-run-phase3-sensitivity --config configs/phase3_sensitivity.json
pcd-run-phase3-report --config configs/phase3_report.json

Typical outputs include experiment matrices, grouped metrics, parameter intervals, parameter-correlation diagnostics, alpha-threshold sweeps, residual plots, front-evolution plots, and compact markdown summaries.

Phase 3B: Formal Held-Out Protocol

Phase 3B is the formal held-out evaluation layer. It creates a saved split manifest, reuses the same split and seed list across variants, selects best checkpoints using validation metrics, and saves observation-level predictions and residuals.

pcd-run-phase3b-protocol --config configs/phase3b_protocol.json

Key outputs:

• outputs/phase3b_protocol/latest/split_manifest.json
• outputs/phase3b_protocol/latest/experiment_matrix.csv
• outputs/phase3b_protocol/latest/seedwise_metrics.csv
• outputs/phase3b_protocol/latest/parameter_intervals.csv
• outputs/phase3b_protocol/latest/local_sensitivity.csv
• outputs/phase3b_protocol/latest/parameter_correlation.csv
• outputs/phase3b_protocol/latest/publication_summary.md
• outputs/phase3b_protocol/latest/main_result_recommendation.json

Phase 4: Final Campaign

The final campaign reuses the formal protocol, compares the final candidate set, applies a simplest-adequate-model selection rule, and writes locked manuscript-facing artifacts.

pcd-run-final-campaign --config configs/final_campaign.json

Key outputs:

• outputs/final_campaign/latest/final_model_ranking.csv
• outputs/final_campaign/latest/final_model_lock.json
• outputs/final_campaign/latest/publication_table_metrics.csv
• outputs/final_campaign/latest/publication_table_metrics_by_group.csv
• outputs/final_campaign/latest/publication_table_parameters.csv
• outputs/final_campaign/latest/final_methods_summary.md
• outputs/final_campaign/latest/final_results_summary.md

For the selected final model, the command also saves locked config, split, seeds, observation-level predictions, residuals, front predictions, and learned parameter summaries.

Multi-Source Inverse Learning

The multi-source workflow is isolated from the final Phase 4 ranking outputs. It supports group-conditioned neural fields and task-specific observation heads for depth, UCS, uptake, and extent observations when those data are available.

pcd-run-multisource-inverse --config configs/multisource_inverse.json

Manuscript-facing multi-source figures can be regenerated from saved outputs:

python scripts/generate_multisource_paper_figures.py ^
  --run-dir outputs/multisource_inverse/latest ^
  --final-campaign-dir outputs/final_campaign/latest ^
  --paper-dir paper

Revision Suite

The revision suite collects several manuscript-supporting experiments.

Quick smoke run:

python experiments/run_revision_suite.py --mode quick

Full configured run:

python experiments/run_revision_suite.py --mode full

Collect summaries from existing full-run artifacts without retraining:

python experiments/collect_revision_results.py --mode full

Testing

Run the full test suite with:

pytest

The tests cover data validation, empirical baselines, the finite-difference forward solver, PINN components, uncertainty and sensitivity diagnostics, Phase 3B protocol outputs, and final-campaign consistency checks.

Outputs and Reproducibility

All run commands save timestamped artifacts under outputs/<workflow>/. The code records configs, seeds, metrics, learned parameters, predictions, residuals, plots, and markdown reports where relevant.

The repository is designed so that generated outputs can be deleted and regenerated from the committed source code, configs, and CSV inputs.

Assumptions and Limitations

• The model is one-dimensional and represents axial CO2 ingress only.
• Carbonation depth is the primary calibration and evaluation target.
• UCS is auxiliary and does not define an additional PDE state.
• Boundary conditions are simple: Dirichlet CO2 ingress at x=0 and zero flux at the far boundary.
• The primary dataset is digitized from published figures and should be treated as reproducible development data rather than direct raw laboratory records.
• Identifiability diagnostics should be interpreted separately from predictive fit; weak or degenerate diagnostics are reported as such by the formal workflows.

Citation

If you use this repository in academic work, cite the associated manuscript and reference this code release. A BibTeX entry can be added here after the paper or repository DOI is available.

License

The package metadata declares an MIT license. Add a top-level LICENSE file before public release if the GitHub repository needs an explicit license text.