Skip to content

cuQuantum

Description

NVIDIA cuQuantum is an SDK of optimized libraries and tools that accelerate quantum computing emulation at both the circuit and device level by orders of magnitude. It consists of three major components:

  • cuDensityMat: a high-performance library for quantum dynamics equation solvers
  • cuStateVec: a high-performance library for state vector quantum simulators
  • cuTensorNet: a high-performance library for tensor network computations

In addition to C APIs, cuQuantum also provides Python APIs via cuQuantum Python.

Available Versions

The following versions of cuQuantum are currently available:

  • Runtime dependencies:
    • CUDA/12.9.0
  • Optional dependencies:
    • cuTENSOR/2.3.1.0-CUDA-12.9.0
    • OpenMPI/4.1.6-GCC-13.2.0
    • Python/3.11.5-GCCcore-13.2.0

You can load the selected version (also with its runtime dependencies) as one module with the following command:

module load cuQuantum/25.09.0.7-CUDA-12.9.0

You can load the optional dependencies in a similar fashion.

Best practice for using cuQuantum

We recommend running cuQuantum applications on GPUs. cuQuantum algorithm simulations can achieve a significant speedup on the GPU over the CPU.

Examples

Examples can be found in the GitHub repository. Clone the repository using: 

git clone https://github.com/NVIDIA/cuQuantum

To use the Python bindings, load the required modules and your preferred Python version. In this example we use Python 3.11.5 and work in the $HOME directory. 

module load cuQuantum/25.09.0.7-CUDA-12.9.0
module load cuTENSOR/2.3.1.0-CUDA-12.9.0
module load OpenMPI/4.1.6-GCC-13.2.0
module load Python/3.11.5-GCCcore-13.2.0
Then create the python virtual environment with all the requirements: 
python3 -m venv cuQuantum-env
Activate the environment and upgrade the packaging tools: 
source cuQuantum-env/bin/activate
python3 -m pip install -U pip setuptools wheel
Install cuQuantum python from the module: 
cd /storage-apps/easybuild-soft/software/cuQuantum/25.09.0.7-CUDA-12.9.0/python
pip install .
There are other optional packages depending on your use case. Follow the installation guides for them:

Change directory to one of the sample directories: 

cd cuQuantum/samples/cudensitymat
Create submit script submit.sh to run sample python script: 
#!/bin/bash
#SBATCH --account=<project> # project number
#SBATCH --partition=gpu
#SBATCH --job-name=test
#SBATCH --nodes=1
#SBATCH --output=out.txt
#SBATCH --error=err.txt
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=16
#SBATCH --time=0:01:00
#SBATCH --gres=gpu:1

module load cuQuantum/25.09.0.7-CUDA-12.9.0
module load cuTENSOR/2.3.1.0-CUDA-12.9.0
module load OpenMPI/4.1.6-GCC-13.2.0
module load Python/3.11.5-GCCcore-13.2.0

source $HOME/cuQuantum-env/bin/activate
python3 operator_advanced_example.py
Submit the script to slurm scheduler: 
sbatch submit.sh

Examples in the C++ language are in the samples folder. To build the examples, set the following environment: 

module load cuQuantum/25.09.0.7-CUDA-12.9.0
module load cuTENSOR/2.3.1.0-CUDA-12.9.0
module load OpenMPI/4.1.6-GCC-13.2.0
export CUQUANTUM_ROOT=/storage-apps/easybuild-soft/software/cuQuantum/25.09.0.7-CUDA-12.9.0/
export CUTENSOR_ROOT=/storage-apps/easybuild-soft/software/cuTENSOR/2.3.1.0-CUDA-12.9.0/
export MPI_ROOT=/storage-apps/easybuild-soft/software/OpenMPI/4.1.6-GCC-13.2.0/
Change directory to sample code you want to build and run make, e.g.: 
cd cuQuantum/samples/cudensitymat
make
To run the example create a script and save it as submit.sh: 
#!/bin/bash
#SBATCH --account=<project> # project number
#SBATCH --partition=gpu
#SBATCH --job-name=test
#SBATCH --nodes=1
#SBATCH --output=out.txt
#SBATCH --error=err.txt
#SBATCH --ntasks=2
#SBATCH --cpus-per-task=16
#SBATCH --time=0:01:00
#SBATCH --gres=gpu:2

module load cuQuantum/25.09.0.7-CUDA-12.9.0
module load cuTENSOR/2.3.1.0-CUDA-12.9.0
module load OpenMPI/4.1.6-GCC-13.2.0

mpiexec -np 2 --map-by ppr:1:node ./operator_action_mpi_example
Submit the script to slurm scheduler: 
sbatch submit.sh

User guide

More information and user documentation on cuQuantum can be found here.

Created by: Jozef Federic, Marek Štekláč