Quick Start

This guide covers the standard way to run SPINE. For full reconstruction workflows, use the published SPINE container image. Run that image with Docker on local machines or with Apptainer / Singularity on HPC systems. Use an explicit release tag when you want a pinned runtime; when in doubt, use latest or omit the tag entirely. Local Python-only installs are more appropriate for post-processing, analysis, and visualization tasks.

Run SPINE In The Container

Pull the recommended runtime container with Docker:

# Equivalent to: docker pull ghcr.io/deeplearnphysics/spine
docker pull ghcr.io/deeplearnphysics/spine:latest

# Pin to a specific release if needed
docker pull ghcr.io/deeplearnphysics/spine:<release>

Or pull the same released image with Apptainer:

# Equivalent to omitting the tag entirely in the Docker image reference
apptainer pull spine_latest.sif docker://ghcr.io/deeplearnphysics/spine:latest

# Or pin to a specific release
apptainer pull spine_<release>.sif docker://ghcr.io/deeplearnphysics/spine:<release>

Run a configuration with Docker:

docker run --gpus all -v $(pwd):/workspace \
  ghcr.io/deeplearnphysics/spine:latest \
    spine --config /workspace/config/train_uresnet.yaml --source /workspace/data.h5

# Or use a pinned release
docker run --gpus all -v $(pwd):/workspace \
  ghcr.io/deeplearnphysics/spine:<release> \
    spine --config /workspace/config/train_uresnet.yaml --source /workspace/data.h5

On Apple Silicon macOS systems, add --platform=linux/amd64 to docker run when using the published SPINE image:

docker run --platform=linux/amd64 --gpus all -v $(pwd):/workspace \
   ghcr.io/deeplearnphysics/spine:<release> \
      spine --config /workspace/config/train_uresnet.yaml --source /workspace/data.h5

For Jupyter notebook/lab use specifically, avoid the Docker Desktop combination of Apple Virtualization Framework with Rosetta enabled. Apple Virtualization Framework without Rosetta and Docker VMM have both been verified to work for Jupyter with the published image, while normal SPINE CLI commands continue to work with either setting.

Run the same configuration with Apptainer:

 # Latest published image
apptainer exec --nv spine_latest.sif \
    spine --config /workspace/config/train_uresnet.yaml --source /workspace/data.h5

# Or use a pinned release
apptainer exec --nv spine_<release>.sif \
    spine --config /workspace/config/train_uresnet.yaml --source /workspace/data.h5

Run SPINE From Python

If you want to inspect one entry interactively, start a shell in the container first:

docker run --gpus all -it --rm -v $(pwd):/workspace \
  ghcr.io/deeplearnphysics/spine:latest \
  bash

# On Apple Silicon macOS, add --platform=linux/amd64 before the image name.

From that shell, you can open Python or Jupyter and use the same driver directly. A typical workflow is to process one entry and hand the result to spine.vis.out.Drawer for visualization:

from spine.config import load_config_file
from spine.driver import Driver
from spine.vis.out import Drawer

cfg = load_config_file("/workspace/config/train_uresnet.yaml")

driver = Driver(cfg)
data = driver.process(entry=0)

drawer = Drawer(data, draw_mode="both")
fig = drawer.get("particles")
fig.show()

The same pattern works for other object families such as fragments or interactions.

Run JupyterLab Or Classic Notebook

To launch JupyterLab directly from the published container:

docker run --gpus all -it --rm -p 8888:8888 -v $(pwd):/workspace \
   ghcr.io/deeplearnphysics/spine:<release> \
   jupyter lab --ip 0.0.0.0 --port 8888 --no-browser --allow-root

On Apple Silicon macOS systems, add --platform=linux/amd64 before the image name:

docker run --platform=linux/amd64 --gpus all -it --rm -p 8888:8888 -v $(pwd):/workspace \
   ghcr.io/deeplearnphysics/spine:<release> \
   jupyter lab --ip 0.0.0.0 --port 8888 --no-browser --allow-root

If you specifically want the classic notebook UI instead of Lab:

docker run --gpus all -it --rm -p 8888:8888 -v $(pwd):/workspace \
   ghcr.io/deeplearnphysics/spine:<release> \
   jupyter notebook --ip 0.0.0.0 --port 8888 --no-browser --allow-root

Open the URL printed by Jupyter in your browser on the host machine.

When To Use Local Python Installs

If you only need to inspect outputs, make plots, or run downstream studies, a local install is often enough:

pip install spine[viz]

For broader analysis or documentation work:

pip install spine[all]

This mode is useful for spine.post, spine.ana, and spine.vis workflows, but it is not the recommended default for full reconstruction jobs when a released container image is available.

Next Steps

Review Installation for the runtime options and tradeoffs
Explore Advanced YAML Config Loader to understand SPINE configuration files
Browse the API reference for the pipeline stage you are modifying or using