"Warning: not using the GPU — … this PyTorch build cannot run on it" — the default pip PyTorch wheels no longer include kernels for older GPUs (e.g. Pascal cards: GTX 10xx, Quadro P series). MindGlide falls back to CPU automatically. To use such a GPU, install a compatible PyTorch first:

pip install "torch==2.6.0+cu118" --index-url https://download.pytorch.org/whl/cu118
pip install git+https://github.com/MS-PINPOINT/mindGlide.git

GPU out of memory — try --sw-batch-size 1, or --device cpu.

Apple Silicon — auto uses MPS when available. If an operation is unsupported, run with --device cpu or set PYTORCH_ENABLE_MPS_FALLBACK=1.

Offline / air-gapped machines — download the checkpoint once and pass --model-path /path/to/model.pt (or set MODEL_PATH).

Model cache location — the auto-downloaded model lives in the Hugging Face cache (~/.cache/huggingface by default); set HF_HOME to move it.

Build once (model weights are baked in, so the container works offline):

git clone https://github.com/MS-PINPOINT/mindGlide.git
cd mindGlide
docker build -t mindglide .

Run (drop --gpus all on CPU-only hosts; --user makes the output files owned by you rather than the container user):

docker run --gpus all --ipc=host --user $(id -u):$(id -g) -v /data:/data \
  mindglide -i /data/scan.nii.gz -o /data/scan_seg.nii.gz

For Apptainer/Singularity on HPC:

apptainer build mindglide.sif docker-daemon://mindglide:latest
apptainer run --nv -B /data:/data mindglide.sif -i /data/scan.nii.gz -o /data/scan_seg.nii.gz

The checkpoint (_20240404_conjurer_trained_dice_7733.pt) is downloaded automatically from Hugging Face: MS-PINPOINT/mindglide on first run. Additional and legacy checkpoints are archived in the same repository. Models were trained on the datasets described in the paper.

From a source checkout you can also fetch the weights as a git submodule (requires Git LFS):

git submodule update --init --recursive
git submodule foreach 'git lfs pull'

git clone https://github.com/MS-PINPOINT/mindGlide.git
cd mindGlide
pip install -e ".[test]"

pytest                          # fast unit tests (seconds, no model download)
MINDGLIDE_RUN_SLOW=1 pytest -v  # + end-to-end on a public MNI scan (CPU, and GPU if present)

The original container-based training/fine-tuning pipeline was retired from the main branch and is preserved at the legacy-container tag.

@article{Goebl2025,
    author = {Goebl, Philipp and Wingrove, Jed and Abdelmannan, Omar and {Brito Vega}, Barbara and Stutters, Jonathan and Ramos, {Silvia Da Graca} and Kenway, Owain and Rossor, Thomas and Wassmer, Evangeline and Arnold, Douglas L. and Collins, Louis and Hemingway, Cheryl and Narayanan, Sridar and Chataway, Jeremy and Chard, Declan and Iglesias, {Juan Eugenio} and Barkhof, Frederik and Parker, Geoffrey J. M. and Oxtoby, Neil P. and Hacohen, Yael and Thompson, Alan and Alexander, Daniel C. and Ciccarelli, Olga and Eshaghi, Arman},
    title = {Enabling new insights from old scans by repurposing clinical {MRI} archives for multiple sclerosis research},
    journal = {Nature Communications},
    volume = {16},
    number = {1},
    pages = {3149},
    year = {2025},
    month = apr,
    doi = {10.1038/s41467-025-58274-8},
    pmid = {40195318},
    pmcid = {PMC11976987}
}