Skip to content

feat: Stage 3 npj Computational Materials upgrade (2.5D SwinIR, physics/topology losses, epistemic uncertainty & 3D FSC metrology) - #4

Merged
jameslehoux merged 2 commits into
mainfrom
stage3-npj-physics-uncertainty-swinir
Nov 17, 2026
Merged

jameslehoux merged 2 commits into
mainfrom
stage3-npj-physics-uncertainty-swinir

Conversation

@jameslehoux

Copy link
Copy Markdown

Summary

Implements the Stage 3 (npj Computational Materials) novelty roadmap across four pillars:

1. Zero-Overhead Orthogonal Epistemic Uncertainty & 2.5D Multi-Slice Context (Phase 3A)

  • compute_orthogonal_uncertainty (src/openlsrx/inference/orthogonal.py): Computes zero-overhead voxel-wise epistemic uncertainty $\sigma_{\text{ortho}}(\mathbf{x}) = \text{std}(V_{yz}, V_{xz}, V_{xy})$, peak-to-peak range, and cv across perpendicular 2D/2.5D sweep planes.
  • Confidence-Weighted Fusion (mode="confidence" | "confidence_fourier"): Suppresses single-axis streak/blur outliers via inverse-disagreement weighting, optionally combined with directional Fourier cone weighting and optical PSF cutoff (psf_cutoff).
  • 2.5D Multi-Slice Context (context_slices = 2k + 1): Boundary-safe per-axis reflect-padded windowing with zero cross-axis boundary bleeding and $O(3)$ through-plane z-flip symmetry in extract_paired_slices_from_subvolume, PairedSliceDataset, PairedVolumeDataModule, and super_resolve_volume_orthogonal.

2. Physics- & Topology-Preserving Objectives (Phase 3B)

  • AttenuationConservationLoss (src/openlsrx/losses/physics.py): Enforces Beer–Lambert X-ray linear attenuation conservation between super-resolved sub-voxels and measured LR voxels under the optical PSF ($\mathcal{P}{\sigma, s}(\hat{I}{\text{SR}}) = I_{\text{LR}}$) in 2D, 2.5D, and 3D.
  • SoftCLDiceLoss & soft_skeletonize: Differentiable morphological skeletonization preserving narrow percolating pore throats.
  • SobelGradientLoss & FocalFrequencyLoss: 2D/3D Sobel phase-boundary sharpness and adaptive high-frequency Fourier reconstruction losses, wired into both SRGAN and SR3DResNet.

3. 2.5D SwinIR Shifted-Window Transformer Backbone (Phase 3C)

  • SwinIRGenerator (src/openlsrx/models/swinir.py): Pure-PyTorch shifted-window 2D self-attention generator (WindowAttention2D, SwinTransformerLayer, ResidualSwinBlock) supporting odd context_slices, arbitrary input dimensions (automatic pad-and-crop), and integer/fractional synchrotron optical magnifications (2x, 2.5x, 4x) via ArbitraryScaleUpsample.
  • Validated YAML profile: configs/i13-xct/zn13x_2x_swinir_25d_physics.yaml.

4. Synchrotron 3D FSC / 2D FRC Metrology, Tri-Phase Zn-13X & Uncertainty-Propagated Transport (Phase 3D)

  • compute_fsc_3d, compute_frc_2d, evaluate_spectral_metrics (src/openlsrx/metrics/spectral.py): Radial Fourier Shell/Ring Correlation against 0.143 and information-theoretic 1/2-bit curves, reporting effective spatial resolution in $\mu\text{m}$ and spectral AUC.
  • evaluate_triphase_zn13x_metrics (src/openlsrx/metrics/petrophysics.py): Multi-Otsu reactive ion-exchange evaluation (Macropore, Na-13X Core, Zn-13X Rim Dice & volume-fraction errors).
  • compute_tortuosity_uncertainty_bounds (src/openlsrx/metrics/transport.py): Propagates orthogonal epistemic uncertainty $\pm k,\sigma_{\text{ortho}}(\mathbf{x})$ into conservative/optimistic 3D steady-state Laplace effective diffusivity bounds $[D_{\text{eff}}^-, D_{\text{eff}}^+]$ and tortuosity intervals $[\tau^-, \tau^+]$.
  • CLI, Campaign Runner & Study Design Docs: Added --include-spectral and --include-triphase to openlsrx evaluate, expanded zn13x_synchrotron_study.py to 7 methods (including OpenLSR-X-SwinIR-2.5D-Physics-ConfFourier), updated aggregate_campaign.py, and added docs/npj-study-design.md.

Verification

  • ruff format --check & ruff check: 0 issues
  • mypy src tests scripts examples: 0 issues across 44 files
  • mkdocs build --strict: clean strict build
  • pytest --cov=openlsrx --cov-fail-under=85: 71/71 passed, 90.45% total coverage
  • End-to-end 7-method zn13x_synchrotron_study.py --fast + aggregate_campaign.py smoke test verified.

@jameslehoux
jameslehoux merged commit 2c20ebd into main Nov 17, 2026
5 checks passed
@jameslehoux
jameslehoux deleted the stage3-npj-physics-uncertainty-swinir branch November 17, 2026 23:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant