Skip to content

GPU Acceleration

HLQuantum provides a unified GPUConfig that works across all GPU-capable backends. The same configuration object drives target/device selection on every framework.

Configuration

from hlquantum import GPUConfig, GPUPrecision

# Single GPU (default device)
gpu = GPUConfig(enabled=True)

# Multi-GPU
gpu = GPUConfig(enabled=True, multi_gpu=True, device_ids=[0, 1])

# FP64 precision
gpu = GPUConfig(enabled=True, precision=GPUPrecision.FP64)

# Enable cuStateVec (Qiskit Aer)
gpu = GPUConfig(enabled=True, custatevec=True)

GPU Support by Backend

Backend GPU Library Auto-selected target / device
CudaQBackend CUDA-Q (native) "nvidia", "nvidia-fp64", "nvidia-mqpu"
QiskitBackend qiskit-aer-gpu AerSimulator(device='GPU')
CirqBackend qsimcirq QSimSimulator(use_gpu=True)
PennyLaneBackend pennylane-lightning[gpu] "lightning.gpu"
BraketBackend (not available) (cloud-managed hardware)
IonQBackend (not available) (cloud-managed trapped-ion hardware)

Per-Backend Examples

from hlquantum import GPUConfig, GPUPrecision
from hlquantum.backends import CudaQBackend, QiskitBackend, CirqBackend, PennyLaneBackend

gpu = GPUConfig(enabled=True)

# CUDA-Q — auto-selects "nvidia" target
cudaq = CudaQBackend(gpu_config=gpu)

# CUDA-Q — multi-GPU with FP64
cudaq_multi = CudaQBackend(
    gpu_config=GPUConfig(enabled=True, multi_gpu=True, precision=GPUPrecision.FP64)
)

# Qiskit Aer — GPU + cuStateVec
qiskit = QiskitBackend(gpu_config=GPUConfig(enabled=True, custatevec=True))

# Cirq — qsim GPU simulator
cirq = CirqBackend(gpu_config=gpu)

# PennyLane — auto-selects lightning.gpu
pl = PennyLaneBackend(gpu_config=gpu)

Detecting GPUs

from hlquantum import detect_gpus

for gpu in detect_gpus():
    print(f"GPU {gpu['id']}: {gpu['name']} ({gpu['memory_total_gb']} GB)")

Reference

GPU configuration and detection utilities.

GPUConfig dataclass

Configuration for GPU-accelerated simulation.

Source code in hlquantum/gpu.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@dataclass
class GPUConfig:
    """Configuration for GPU-accelerated simulation."""

    enabled: bool = False
    device_ids: Optional[List[int]] = None
    multi_gpu: bool = False
    precision: GPUPrecision = GPUPrecision.FP32
    memory_limit_gb: Optional[float] = None
    custatevec: bool = False
    extra: Dict[str, Any] = field(default_factory=dict)

    @property
    def num_gpus(self) -> int:
        if not self.enabled:
            return 0
        return len(self.device_ids) if self.device_ids is not None else 1

    @property
    def cuda_visible_devices(self) -> Optional[str]:
        return ",".join(str(d) for d in self.device_ids) if self.device_ids else None

    def apply_env(self) -> None:
        cvd = self.cuda_visible_devices
        if cvd is not None:
            os.environ["CUDA_VISIBLE_DEVICES"] = cvd
            logger.info("CUDA_VISIBLE_DEVICES set to %s", cvd)

    def __repr__(self) -> str:
        if not self.enabled:
            return "GPUConfig(enabled=False)"
        parts = ["enabled=True"]
        if self.device_ids:
            parts.append(f"device_ids={self.device_ids}")
        if self.multi_gpu:
            parts.append("multi_gpu=True")
        parts.append(f"precision={self.precision.value}")
        if self.custatevec:
            parts.append("custatevec=True")
        return f"GPUConfig({', '.join(parts)})"

detect_gpus()

Detect available NVIDIA GPUs.

Source code in hlquantum/gpu.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def detect_gpus() -> List[Dict[str, Any]]:
    """Detect available NVIDIA GPUs."""
    try:
        import pynvml
        pynvml.nvmlInit()
        count = pynvml.nvmlDeviceGetCount()
        gpus = []
        for i in range(count):
            handle = pynvml.nvmlDeviceGetHandleByIndex(i)
            name = pynvml.nvmlDeviceGetName(handle)
            if isinstance(name, bytes):
                name = name.decode()
            mem = pynvml.nvmlDeviceGetMemoryInfo(handle)
            gpus.append({
                "id": i,
                "name": name,
                "memory_total_gb": round(mem.total / (1024**3), 2),
            })
        pynvml.nvmlShutdown()
        return gpus
    except Exception:
        return []