unitarylab-cu12

CUDA 12 native statevector and density-matrix backends for UnitaryLab.

This repository branch builds the CUDA backend as an independent Python wheel. The PyPI distribution name is unitarylab-cu12; the Python import package is unitarylab_cu12.

Supported environment

• Linux x86_64 and Linux aarch64 server environments
• Windows x86-64
• CPython 3.10, 3.11, and 3.12
• CUDA 12 runtime provided by nvidia-cuda-runtime-cu12
• cuBLAS provided by nvidia-cublas-cu12
• NVIDIA driver compatible with the CUDA version used by the wheel

Linux aarch64 wheels target server environments and do not promise Jetson compatibility. macOS, Windows ARM64, and Python 3.13 are not part of the wheel matrix.

Build

Building requires a CUDA 12 development toolkit, a C++ compiler, CMake, and Ninja. Build wheels only; source distributions are intentionally disabled.

python -m build --wheel

Override the CUDA architecture list when necessary:

UNITARYLAB_CUDA_ARCHS="80-real;86-real;89-real;90-real" \
  python -m build --wheel

Install a wheel

python -m pip install unitarylab-cu12

Verify the native extension import:

from unitarylab_cu12 import cudadensity, cugates

print(cugates.__doc__)
print(cudadensity.__doc__)

cugates provides the fused CUDA statevector backend, while cudadensity provides dense CUDA density-matrix execution. The high-level executors remain in the main unitarylab package.

On Linux, extension RUNPATH entries locate libcudart.so.12 and cuBLAS in the NVIDIA runtime wheels. On Windows, the Python package registers the runtime and cuBLAS bin directories before loading either extension; a complete system CUDA Toolkit is not required at runtime.

The machine must still have an NVIDIA driver compatible with CUDA 12. Import checks performed by GitHub Actions verify wheel and runtime-library loading on GPU-less runners; they do not execute CUDA kernels.

GitHub Actions

The Build CUDA Wheels workflow is started manually with workflow_dispatch. It builds Linux x86_64, Linux aarch64, and Windows AMD64 wheels, validates their native dependencies, then stores them as GitHub Actions artifacts for 14 days. It does not publish to PyPI.

Synchronize CUDA sources from main

Keep release-specific packaging files on this branch and synchronize only the shared CUDA source directory:

git switch release/cu12
git fetch origin main
git restore --source origin/main -- \
  unitarylab/backend/cugates/src \
  unitarylab/backend/density_matrix/cudadensity/src
git diff
git add \
  unitarylab/backend/cugates/src \
  unitarylab/backend/density_matrix/cudadensity/src
git commit -m "sync: update CUDA backends from main"

Do not merge main into this branch; doing so would restore the full UnitaryLab source tree.