Skip to content

Getting Started

Installation

OpenLSR-X targets Python 3.10–3.12 and uses uv for deterministic dependency management.

Standard GPU / Workstation Install

git clone https://github.com/BASE-Laboratory/OpenLSR-X.git
cd OpenLSR-X
uv venv --python 3.11
uv pip install -e ".[dev,docs]"

Lightweight CPU-Only Install (Laptops & CI)

uv venv --python 3.11
uv pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision
uv pip install -e ".[dev,docs]"

Verify your installation:

openlsrx --help

Core CLI Workflows

All training, validation, testing, prediction, and evaluation tasks run through the single openlsrx command (or python -m openlsrx).

1. Train on Synthetic PoreSpy 3D XCT

openlsrx fit -c configs/base/config.yaml

Override hyperparameters directly from the command line:

openlsrx fit -c configs/base/config.yaml \
  --trainer.max_epochs 200 \
  --model.learning_rate 5e-5 \
  --data.init_args.noise_regime high_noise

2. Reconstruct 3D Volumes from a Checkpoint

Run 3-axis orthogonal fusion (predict_mode: orthogonal_3axis by default) via LightningCLI predict or the standalone predict-volume subcommand:

openlsrx predict -c configs/porespy/Predict/ps_predict_config.yaml \
  --ckpt_path lightning_logs/version_0/checkpoints/last.ckpt
openlsrx predict-volume \
  --ckpt lightning_logs/version_0/checkpoints/last.ckpt \
  --input data/benchmarks/zn13x_2x_lr.tif \
  --output-dir outputs/zn13x_sr \
  --fusion confidence_fourier \
  --save-uncertainty

In orthogonal_3axis mode, predictions are exported under <output_dir>/predicted_orthogonal/ as assembled 3D (Z, Y, X) multi-page BigTIFF stacks (*_predicted_stack.tiff, *_uncertainty_std.tiff, *_low_res_stack.tiff, and *_high_res_stack.tiff when paired).

3. Evaluate Petrophysical, Spectral & Transport Metrics

openlsrx evaluate \
  --pred outputs/predicted_orthogonal/ps_predict_predicted_stack.tiff \
  --target outputs/predicted_orthogonal/ps_predict_high_res_stack.tiff \
  --include-spectral \
  --include-transport \
  --output results/eval_report.json

HPC Cluster Execution

Ready-to-customize batch scripts are provided in scripts/hpc/:

  • Isambard-AI (GH200 SLURM array): sbatch scripts/hpc/isambard_ai_array.slurm
  • Generic SLURM clusters: sbatch scripts/hpc/slurm_train.sh configs/porespy/High_Noise/ps_hn_hf_config.yaml
  • Sun Grid Engine (e.g., UCL MMM Hub Young): qsub -v CONFIG_PATH=configs/labxct/bs_config.yaml scripts/hpc/sge_young_train.sh