Install

NVIDIA container

Version 0.0.4 embeds sm_75 PTX for Turing and newer NVIDIA GPUs and was built against CUDA 12.4 headers. The host needs an NVIDIA driver from the 550 series or newer and the NVIDIA Container Toolkit.

docker pull ghcr.io/hillerlab/hspz:0.0.4
docker run --rm --gpus all \
  -v "$PWD:/data" \
  ghcr.io/hillerlab/hspz:0.0.4 \
  hspZ --version

The mount matters: the image works in /data, and output must live in the mounted directory if it should survive the container.

AMD through ZLUDA

The ZLUDA image is a validated correctness backend, not a claim that AMD and native NVIDIA have the same performance.

docker pull ghcr.io/hillerlab/hspz:0.0.4-zluda
docker run --rm \
  --device=/dev/kfd --device=/dev/dri \
  --group-add video --group-add render \
  -v "$PWD:/data" \
  ghcr.io/hillerlab/hspz:0.0.4-zluda \
  hspZ --version

--gpus all is an NVIDIA container flag; it does not expose AMD KFD devices.

Floating tags

:latest and :zluda move only after the release passes the Kaggle T4 gate. Use :0.0.4 and :0.0.4-zluda when reproducibility matters.

Build from source

Use the checked-in nightly toolchain and the cuda-oxide revision pinned by Cargo.lock. Set CUDA_HOME to a CUDA toolkit compatible with the target driver, install cargo-oxide and seed its codegen-backend source at that same revision (on first use cargo-oxide otherwise clones the backend from upstream HEAD, which tracks newer nightlies), then build:

pin=$(grep -m1 -o 'cuda-oxide\.git#[0-9a-f]\{40\}' Cargo.lock | cut -d'#' -f2)
cargo install cargo-oxide --git https://github.com/NVlabs/cuda-oxide.git --rev "$pin" --locked
src=${CARGO_HOME:-$HOME/.cargo}/cuda-oxide/src
git init -q "$src" && git -C "$src" fetch -q --depth 1 https://github.com/NVlabs/cuda-oxide.git "$pin" \
  && git -C "$src" checkout -q --detach FETCH_HEAD
cargo oxide build -- --release --locked
target/release/hspZ --version

The backend links libffi (Debian/Ubuntu: libffi-dev).

A bare build targets sm_80, the default in .cargo/cuda-oxide.toml and the architecture ZLUDA expects. The NVIDIA image builds sm_75 instead, whose PTX also runs on newer cards; Turing cards such as the T4 need it: cargo oxide build --arch sm_75 -- --release --locked. The binary links libcuda.so.1, so even --version needs the NVIDIA driver (or ZLUDA’s library) on the loader path.

Plain cargo build does not run the cuda-oxide device build and is not a supported production build.