qubestack-cudaq

QuREKA backend plugin for CUDA-Q.

Execute CUDA-Q quantum circuits on various quantum backends through the QuREKA platform.

Supported Backends

Installation

pip install qubestack-cudaq

cuda-quantum-cu12==0.14.0 is automatically installed as a dependency.

Optional: [academic] extras

For running the NVIDIA CUDA-Q Academic notebooks (QEC, chemistry-simulations, QAOA, dynamics, ai-for-quantum, ...), install the academic extras:

pip install "qubestack-cudaq[academic]"

This adds cudaq-qec, cudaq-solvers (with ABI-compatible pins) plus the learning-side libraries (qutip, galois, pymatching, stim, openfermion, diffusers, transformers). External PyPI users are not forced into this set — the base pip install qubestack-cudaq remains unchanged.

The qubestack-pad notebook image bundles this [academic] bundle so users can run the Academic notebooks out of the box without additional installs.

Version compatibility matrix

The four packages below must ship together with ABI-compatible pins. qubestack-cudaq CI enforces this via scripts/verify_academic.sh (fail-fast).

New rows are appended when NVIDIA releases a new cuda-quantum-cu12 and the matching cudaq-qec/cudaq-solvers pair is validated. See QXDEV-2375 for the design rationale.

How the pin is chosen: NVIDIA ships cudaq-qec / cudaq-solvers alongside each cuda-quantum-cu12 release. Cross-checked via each *-cu12 wheel's own Requires-Dist metadata:

• cudaq-qec-cu12 0.5.0 / 0.5.0.post1 → cuda-quantum-cu12 == 0.13.*
• cudaq-qec-cu12 0.6.0 → cuda-quantum-cu12 == 0.14.* ✅ (current pin)

Mismatched pairs surface at pip resolution (ResolutionImpossible) or at import time as libcudaq-qec.so: undefined symbol: _ZN5cudaq16quantum_platform12set_exec_ctxE... and are caught by scripts/verify_academic.sh in CI (Phase 2 fail-fast).

Quick Start

import cudaq

# Set the QuREKA target
cudaq.set_target("qureka", backend="sdt.qubesim-mimiq", api_key="your-api-key")

# Define a quantum kernel
@cudaq.kernel
def bell_state():
    q = cudaq.qvector(2)
    h(q[0])
    cx(q[0], q[1])
    mz(q)

# Execute
result = cudaq.sample(bell_state, shots_count=1000)
print(result)

Configuration

License

Apache License 2.0