Install (GPU-enabled)¶

Overview¶

Use this procedure if you have a supported NVIDIA GPU and want GPU-accelerated execution.

GPU-enabled installation is supported on Windows and Linux (including WSL2-based Linux). macOS is CPU-only.

If you do not have an NVIDIA GPU (or you want the simplest install), see Install (CPU-only).

Note

Install either the CPU-only package or the GPU-enabled package — not both. The GPU-enabled installation includes CPU execution support.

Before you begin, make sure you have Quantum Rings credentials. See Quantum Rings credentials.

Supported GPUs and CUDA runtime¶

Supported GPU architectures and CUDA runtime requirements are listed in System Requirements.

At a high level, GPU mode requires:

NVIDIA Ampere (compute capability 8.0 / 8.6), Hopper (9.0), or Blackwell (10.0+)
Compute capability 8.0 or higher
At least 4 GB of GPU memory
CUDA Runtime 12.9 or 13.0 (Windows/Linux)
CUDA Runtime 13.0 on NVIDIA GB10 Grace Blackwell Superchip

Prerequisites¶

NVIDIA drivers installed

Verify the driver is installed and working:

nvidia-smi

Note

On WSL2, the NVIDIA driver is installed and updated in Windows, and applies to the WSL Linux instance.

CUDA Toolkit installed (Windows/Linux)

Install a CUDA Toolkit version compatible with your driver. NVIDIA’s release notes describe driver ↔ toolkit compatibility.

After installing CUDA Toolkit, ensure the runtime libraries can be found:

Windows: CUDA_PATH and PATH should point to the CUDA Toolkit install.
Linux: LD_LIBRARY_PATH may need to include the CUDA Toolkit lib64 directory.

Install on Windows¶

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

python -m venv qr-gpu
qr-gpu\Scripts\activate

Step 2 (Windows) — Install the GPU-enabled package¶

Choose the package that matches your CUDA Toolkit major version:

CUDA Toolkit 13.x

pip install quantumrings-nvidia-gpu

or:

pip install quantumrings[cuda13x]

CUDA Toolkit 12.x

pip install quantumrings[cuda12x]

Step 3 (Windows) — Configure the CUDA DLL search path in Python¶

On Windows, you must tell Python where the CUDA runtime DLLs are located before importing QuantumRingsLib.

Typical runtime locations (as installed by CUDA Toolkit):

CUDA 12.x: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.9\bin
CUDA 13.x: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0\bin\x64

Add this at the very top of your script (before importing QuantumRingsLib):

import os
import platform

if platform.system() == "Windows":
    cuda_path = os.getenv("CUDA_PATH", "")
    if "" == cuda_path:
        # set a hard-coded path (adjust if your CUDA Toolkit is installed elsewhere)
        cuda_path = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.0\\bin\\x64"
    else:
        # create from the environment
        if "13" in cuda_path:
            cuda_path += "\\bin\\x64"
        else:
            cuda_path += "\\bin"

    os.add_dll_directory(cuda_path)

import QuantumRingsLib

Install on Linux¶

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

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

Step 2 (Linux) — Ensure CUDA runtime libraries can be found¶

After installing CUDA Toolkit, you may need to set LD_LIBRARY_PATH so runtime linking succeeds when importing QuantumRingsLib.

Example (adjust the CUDA version and install path to match your system):

export PATH="$PATH:/usr/local/cuda-13.0/bin"
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/cuda-13.0/lib64"

Note

On managed environments (university clusters, cloud instances), your administrator may provide CUDA via environment modules. In that case, load an appropriate CUDA module for your system before running Python.

Step 3 (Linux) — Install the GPU-enabled package¶

Choose the package that matches your CUDA Toolkit major version:

CUDA Toolkit 13.x

pip install quantumrings-nvidia-gpu

or:

pip install quantumrings[cuda13x]

CUDA Toolkit 12.x

pip install quantumrings[cuda12x]

Install on NVIDIA GB10 Grace Blackwell Superchip¶

On GB10 systems, CUDA Runtime 13.0 is required. Installation is otherwise the same as Linux:

Create a virtual environment
Ensure CUDA runtime libraries can be found
Install the GPU-enabled package (CUDA 13.x)

Verify the installation¶

This test confirms that:

QuantumRingsLib imports successfully (CUDA runtime linkage is working)
The GPU backend can be acquired
A simple circuit can run

# Windows users: include the "configure CUDA DLL search path" block above before importing QuantumRingsLib.

from QuantumRingsLib import QuantumCircuit, QuantumRingsProvider

provider = QuantumRingsProvider()
backend = provider.get_backend("amber_quantum_rings")

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cnot(0, 1)
qc.measure_all()

job = backend.run(qc, shots=100)
result = job.result()
print(result.get_counts())

If you see counts printed without import/runtime errors, GPU-enabled installation is working.

Note

Backend selection depends on your installation: amber_quantum_rings (GPU), scarlet_quantum_rings (CPU), and serin_quantum_rings (hybrid). See Backends.

Troubleshooting¶

Windows import errors / missing CUDA DLLs - Confirm CUDA Toolkit is installed - Confirm CUDA_PATH is set - Ensure you call os.add_dll_directory(...) before importing QuantumRingsLib
Linux import errors / runtime linkage - Confirm CUDA Toolkit is installed - Ensure LD_LIBRARY_PATH includes the CUDA Toolkit lib64 directory

For additional issues, see Troubleshooting.