Install CUDA-Q¶

Overview¶

Use this procedure to install the Quantum Rings SDK integration for the NVIDIA CUDA-Q platform (Python).

CUDA-Q is installed separately from the Quantum Rings SDK. The recommended flow is:

Ensure your system meets requirements and NVIDIA GPU setup is complete.
Install CUDA-Q in a Python virtual environment.
Install the Quantum Rings CUDA-Q toolkit.
Configure Quantum Rings credentials.
Verify CUDA-Q can select the Quantum Rings target.

For NVIDIA driver and CUDA Toolkit setup, see Install (GPU-enabled). For GPU requirements, see System Requirements.

Important

Use a separate Python environment for CUDA-Q. Do not install CUDA-Q into the same environment as QuantumRingsLib GPU.

Supported platforms¶

CUDA-Q installation and execution is performed on Linux. On Windows, install CUDA-Q using Windows Subsystem for Linux (WSL) and follow the Linux steps below.

Prerequisites¶

Supported NVIDIA GPU and working driver

Follow Install (GPU-enabled) and confirm:

nvidia-smi

Python environment

Use 64-bit Python. CUDA-Q requires a working Python environment and may have its own Python constraints depending on the CUDA-Q release.

Quantum Rings credentials

Before running the verification program, configure credentials as described in:

Quantum Rings credentials

CUDA-Q version compatibility¶

The Quantum Rings CUDA-Q toolkit requires CUDA-Q.

Installing the toolkit will install a compatible CUDA-Q package if one is not already present.
If you already have CUDA-Q installed, ensure it satisfies the toolkit requirement.

As published on PyPI for the toolkit, the dependency is:

cudaq>=0.10.0

If you must use CUDA-Q 0.9.1 specifically, the published guidance is to install:

quantumrings-toolkit-cudaq==0.1.91

Install on Linux (or WSL2)¶

Step 1 — Create and activate a virtual environment (recommended)¶

python3 -m venv qr-cudaq
source qr-cudaq/bin/activate

Step 2 — Install CUDA-Q (NVIDIA)¶

Follow NVIDIA’s CUDA-Q installation guide:

After installing, verify CUDA-Q imports successfully:

python -c "import cudaq; print('cudaq OK')"

Step 3 — Install the Quantum Rings CUDA-Q toolkit¶

pip install quantumrings-toolkit-cudaq

If you are pinned to CUDA-Q 0.9.1, install the compatible toolkit version:

pip install quantumrings-toolkit-cudaq==0.1.91

Verify the installation¶

This test confirms that:

CUDA-Q imports successfully
The Quantum Rings CUDA-Q target can be selected
A simple kernel can execute (state generation)

import cudaq

# Select the Quantum Rings engine for CUDA-Q.
cudaq.set_target("QuantumRingsLib")

kernel = cudaq.make_kernel()
qubits = kernel.qalloc(3)

kernel.x(qubits)
kernel.h(qubits)

print(cudaq.draw(kernel))

# This triggers execution and returns a state object.
state = cudaq.get_state(kernel)
print(state)

If this runs without import errors and without target-selection errors, CUDA-Q installation is working.

Troubleshooting¶

``import cudaq`` fails - Re-check that you are in the correct virtual environment. - Reinstall CUDA-Q using NVIDIA’s official instructions (see CUDA-Q Quick Start).
``cudaq.set_target(“QuantumRingsLib”)`` fails - Confirm credentials are configured (Quantum Rings credentials). - Confirm you completed GPU setup (Install (GPU-enabled)) and that the CUDA runtime is available.

For additional issues, see Troubleshooting.