Metadata-Version: 2.4
Name: unitarylab-cu12
Version: 0.1.0
Summary: CUDA 12 gate backend for UnitaryLab.
Author: UnitaryLab
License-Expression: LicenseRef-UnitaryLab-LICENSE
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.zh-CN
License-File: LICENSE.en
Requires-Dist: numpy
Requires-Dist: unitarylab>=1.4
Requires-Dist: nvidia-cuda-runtime-cu12<13,>=12.8; platform_system == "Linux" and (platform_machine == "x86_64" or platform_machine == "aarch64")
Requires-Dist: nvidia-cuda-runtime-cu12<13,>=12.8; platform_system == "Windows" and platform_machine == "AMD64"
Dynamic: license-file

# unitarylab-cu12

CUDA 12 native gate backend 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`
- 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.

```bash
python -m build --wheel
```

Override the CUDA architecture list when necessary:

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

## Install a wheel

```bash
python -m pip install unitarylab-cu12
```

Verify the native extension import:

```python
from unitarylab_cu12 import cugates

print(cugates.__doc__)
```

On Linux, the extension RUNPATH locates `libcudart.so.12` in the NVIDIA runtime
wheel. On Windows, the Python package registers the runtime wheel's
`nvidia/cuda_runtime/bin` directory before loading `cugates.pyd`; 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:

```bash
git switch release/cu12
git fetch origin main
git restore --source origin/main -- unitarylab/backend/cugates/src
git diff
git add unitarylab/backend/cugates/src
git commit -m "sync: update cugates sources from main"
```

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