Skip to content

Modernize OpenLSR-X for publication: 3D orthogonal fusion, petrophysical metrics, benchmarks, CI/CD & JOSS docs - #1

Merged
jameslehoux merged 3 commits into
mainfrom
modernize-publication-ready
Nov 17, 2026
Merged

jameslehoux merged 3 commits into
mainfrom
modernize-publication-ready

Conversation

@jameslehoux

Copy link
Copy Markdown

Summary

Brings BASE-Laboratory/OpenLSR-X from a partial PhD handoff fork to a reproducible, publication-ready Python package and porous-media XCT super-resolution benchmark suite.

Key Fixes & Architectural Upgrades

  1. Restored & Modernized src/openlsrx/data/: Fixed the unanchored data/ rule in .gitignore that had dropped the entire data package during the src/ layout refactor; implemented vectorized, leakage-free 3D spatial slab splitting (split_volume_spatially with configurable guard margins), PoreSpy 2.x/3.x synthetic porous-media generation, unified TIFF/slice-folder/NeXus-HDF5 (PairedVolumeDataModule) loading, and an open micro-CT benchmark fetcher (openlsrx download-benchmarks).
  2. 2D-to-3D Orthogonal Fourier Fusion (openlsrx.inference): Reconstructs isotropic 3D super-resolved XCT volumes from 2D-trained generators across yz, xz, and xy planes using mean, median, or directional 3D Fourier weighting—suppressing single-axis slice-stacking ("venetian blind") discontinuities.
  3. Clean PyTorch & Lightning Modules (openlsrx.models, openlsrx.losses): Converted building blocks and VGGLoss to pure torch.nn.Module, isolated frozen VGG-19 weights (~550 MB) from checkpoints while adding ImageNet normalization, added SRResNet ablation + generator warmup support, eliminated all os.chdir/os.system side effects, and fixed contiguous 3D multi-page BigTIFF export (contiguous=True).
  4. Quantitative XCT & Petrophysical Metrics (openlsrx.metrics, openlsrx.baselines): Added 2D/3D classical baselines (Nearest, Trilinear, Tricubic, Lanczos4), volumetric PSNR & isotropic tri-planar 3D SSIM, plus porous-media petrophysical metrics: segmented porosity error ($|\Delta\phi|$), pore Dice/IoU, marching-cubes specific surface area ($S_v$), 3D Euler connectivity ($\chi_V$), EDT inscribed pore-radius Wasserstein-1 distance ($W_1$), FFT radial two-point correlation $S_2(r)$, and through-plane gradient anisotropy error.
  5. Reproducible Benchmarks, Docs, Governance & CI/CD:
    • Factorial PoreSpy (scripts/benchmarks/porespy_study.py), Open Rock Micro-CT (scripts/benchmarks/public_rock_xct.py), and automated booktabs LaTeX table + 300-DPI figure builder (scripts/benchmarks/make_paper_outputs.py).
    • Unified openlsrx CLI (fit, validate, test, predict, evaluate, download-benchmarks) with schema-validated YAML configs (configs/).
    • Full CI/CD workflows: ci.yml (Ruff, Mypy, MkDocs --strict, wheel build, Python 3.10–3.12 test matrix with $\ge 85%$ coverage gate, and end-to-end benchmark smoke run), docs.yml (GitHub Pages CD), release.yml (wheel/sdist + JOSS openjournals/inara PDF compilation + GitHub Releases on v* tags), Dependabot, issue/PR templates, CITATION.cff, CONTRIBUTING.md, CODE_OF_CONDUCT.md, and JOSS manuscript draft (paper/paper.md + paper/paper.bib).

Verification

  • ruff check src tests scripts & ruff format --check src tests scripts pass (0 errors)
  • mypy src tests scripts passes (0 errors across 30 files)
  • pytest --cov=openlsrx --cov-fail-under=85 passes (52/52 passed, 89.03% coverage)
  • mkdocs build --strict builds cleanly
  • Smoke benchmarks (--fast) + make_paper_outputs.py verified end-to-end

@jameslehoux
jameslehoux merged commit 9d5ebd6 into main Nov 17, 2026
8 checks passed
@jameslehoux
jameslehoux deleted the modernize-publication-ready branch November 17, 2026 21: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