Installation Procedure for GPU Enabled Mode

Quantum Rings SDK now supports Nvidia GPUs, either in the native mode or together with the toolkit for Qiskit.

The following steps outline the installation procedure.

Note

If you are a Windows user, we recommend using a WSL based Linux instance on the system. Also, you have to set the directory where the CUDA Runtime is installed. See the code examples at the end of this page for additional help.

STEP - 1

Obtain your license to the Quantum Rings SDK by selecting the Login menu.

Skip this step, if you are already registered.

Login to the Quantum Rings portal. Download your access keys by selecting the Manage Keys menu in the left-hand side bar.

STEP - 2

Note

If you are using a university supercomputer or a cloud instance with NVIDIA GPUs, your system administrator may have already installed the necessary NVIDIA drivers for you. In such cases, you can skip this step.

Warning

This step may be challenging, and you may need professional help. Installing device drivers can make your installation unstable. Always proceed with a backup and read all documentation carefully. Ensure you install the correct drivers for your hardware platform. Installing open source drivers may not be a good idea.

Update the NVIDIA drivers for your system. For some Linux distributions, you may need to install the NVIDIA drivers directly from the distribution. Please search for the documentation from your Linux operating system provider and follow their recommendation.

If you are installing on WSL-based Linux, you must update the NVIDIA driver in Windows. It will automatically apply to the WSL Linux instance.

Note down the driver version by running the nvidia-smi command in the terminal and observing the version displayed in the top panel. You will need to know the driver version to install the CUDA Toolkit later.

STEP - 3

Create a virtual environment for your Python version using the following example.

virtualenv --python = /usr/bin/python3.13 myenv
source myenv/bin/activate

In some installations, the virtual environment can be created as follows :

python3.13 -m venv myenv
source myenv/bin/activate

Noe that, installing a Python virtual environment may require additional steps.

You can optionally choose to install Jupyter notebook, at this time using the following command.

pip install notebook

STEP - 4

Choose the appropriate CUDA Toolkit for your driver version. Section 2.2 CUDA Driver in Release notes outlines the CUDA Driver version range and the CUDA Toolkit (CTK) you could install. Install the CUDA Toolkit (CTK) by following the instructions in the link: CUDA Toolkit Follow the instructions on the screen after installing and setting up the CUDA Toolkit, and set the paths as directed.

Note

Linux Users:

After installing the CUDA Toolkit, you may have to set the environment variable LD_LIBRARY_PATH to point to the folder where the CUDA Toolkit library was installed. If this is not set, then there may be runtime linkage errors when you import QuantumRingsLib in your Python code.

Assuming /usr/local/cuda-13.0 is where your CUDA Toolkit is installed, add the following two lines at the bottom of your profile ~/.profile.

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

Note

Windows Users:

Ensure that the environment variable CUDA_PATH is set to the folder where the CUDA Toolkit is installed. Also, ensure that the environment variable PATH includes the path where CUDA Toolkit components are installed.

In addition, you have to tell Python where the CUDA dynamically linkable libraries (DLLs) are located.

Note that:

If you are using CUDA Toolkit version 12.x, the runtime is usually installed at: C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.9\\bin If you are using CUDA Toolkit version 13.x, the runtime is usually installed at: C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.0\\bin\\x64

Use the following lines at the top of your code, 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
        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

If environment variables are not set correctly, linker errors will occur, and the SDK will not load. If you are a Windows user, see additional instructions in Section 6 to set up the DLL search path with Python.

If you are using your university supercomputer or a cloud environment with NVIDIA GPUs, your system administrator may already have installed the necessary runtime components optimized for your hardware platform. You may only need to select the CUDA Toolkit module. Selecting the CUDA Toolkit is typically done using a module loader, as shown below. Browse the modules installed in your system and choose the most recent CUDA Toolkit. Note that your system may use a different way of loading runtime components.

module load cuda-12.6.1-gcc-12.1.0

STEP - 5

If you are using CUDA Toolkit version 13.x:

pip install quantumrings-nvidia-gpu

or

pip install quantumrings[cuda13x]

If you are using CUDA Toolkit version 12.x:

pip install quantumrings[cuda12x]

STEP - 6

Now, try the following Python program from your Jupyter notebook to ensure that everything is working fine.

# For Windows users. Linux users may skip this.
# Setup the CUDA Toolkit path with Python
import os
import platform

if platform.system() == "Windows":
    cuda_path = os.getenv("CUDA_PATH", "")
    if "" == cuda_path:
        #set a hard-coded path
        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
from QuantumRingsLib import QuantumRegister, AncillaRegister, ClassicalRegister, QuantumCircuit
from QuantumRingsLib import QuantumRingsProvider
from QuantumRingsLib import job_monitor
from QuantumRingsLib import JobStatus
from QuantumRingsLib import OptimizeQuantumCircuit
from matplotlib import pyplot as plt
import numpy as np
import math

provider = QuantumRingsProvider(token =<YOUR_TOKEN_HERE>, name=<YOUR_ACCOUNT_NAME_HERE>)
backend = provider.get_backend("amber_quantum_rings")
numberofqubits = 50
shots = 100

q = QuantumRegister(numberofqubits , 'q')
c = ClassicalRegister(numberofqubits , 'c')
qc = QuantumCircuit(q, c)

qc.h(0)
for i in range (qc.num_qubits - 1):
    qc.cnot(i, i + 1)

qc.measure_all()

job = backend.run(qc, shots=shots)
job_monitor(job)

result = job.result()
counts = result.get_counts()
print(counts)

Using the GPU Mode

Certain programs with large number of qubits (> 22) with complex entanglements and a large number of gate operations can benefit from using a GPU.

To switch to the GPU mode, select the amber_quantum_rings backend as follows

backend = provider.get_backend("amber_quantum_rings")

To switch to the CPU mode, select the scarlet_quantum_rings backend as follows

backend = provider.get_backend("scarlet_quantum_rings")

Note

Programs with a few qubits and gate operations usually run faster on the CPU mode with the scarlet_quantum_rings backend. You can also use the hybrid backend serin_quantum_rings backend, which uses CPU for most operations and switches to the GPU mode for complex operations.

You can also store the backend name in the configuration file using the key backend and allow the method provider.get_backend select it automatically by not providing any arguments. To save the backend name in the configuration file, please follow the instructions in the SDK. Once the backend name is saved in the configuration file, you can obtain the backend by providing no arguments to the provider.get_backend method as follows:

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

Installing on an AWS SageMaker instance

AWS SageMaker instances may not be preconfigured with the CUDA runtime. To install the CUDA runtime, open a terminal from the Jupyter notebook. Ensure that you are a root user with read rights in your working folder. Follow the instructions found in the link : CUDA Toolkit to install the toolkit corresponding to the driver version. You may not be allowed to update the CUDA drivers. You may want to disable this from the installation process. Set LD_LIBRARY_PATH and PATH as directed, or export them from a cell in the Jupyter notebook. Install quantumrings-nvidia-gpu as described in this document.

Using a hybrid Mode

On personal computers with a NVIDIA GPU containing lower memory, running the quantum circuit in a hybrid mode can be useful. In the hybrid mode, most operations are done by the CPU utilizing the CPU memory. Certain complex operations involving large matrices are offloaded to the GPU for added performance. To use the hybrid mode, select the serin_quantum_rings engine.

backend = provider.get_backend("serin_quantum_rings")