Welcome to the CUDA-Q Python API

CUDA-Q is a comprehensive framework for quantum programming. It features:

• A programming model which extends C++ and Python with quantum kernels, enabling high-level programming in familiar languages
• A high-performance quantum compiler, nvq++, based on the industry standard LLVM toolchain
• Interoperability with all of the leading models and tools for accelerated computing, including CUDA, ISO standard parallelism, OpenMP, and OpenACC
• The ability to utilize and seamlessly switch between different quantum technologies, including state-of-the-art simulator backends with NVIDIA cuQuantum and a number of different physical quantum processors (QPUs)

The CUDA-Q Python wheels contain the Python API and core components of CUDA-Q. This package installs CUDA-Q binaries that are compatible with a CUDA version ${{ cuda_version_requirement }}. More information about available packages as well as a link to the documentation and examples for each version can be found in the release notes. System and compatibility requirements are listed in the Installation Guide of the linked documentation.

Note: CUDA-Q is supported on Linux (x86_64 and aarch64/arm64) and macOS (ARM64/Apple silicon, CPU-only simulation). GPU-accelerated simulation requires Linux with a supported NVIDIA GPU.

Installation Including GPU-Acceleration

CUDA-Q does not require a GPU to use, but some components are GPU-accelerated. Getting started with CUDA-Q requires pip install ${{ package_name }}. Please make sure your pip version is >= 24.0.

${{ deprecation_notice }}

Important: Please check if you have an existing installation of the cuda-quantum, cudaq-quantum-cu11, cuda-quantum-cu12, or cuda-quantum-cu13 package, and uninstall it prior to installation. Different CUDA-Q binary distributions may conflict with each other causing issues.

Platform-specific instructions: Linux | macOS

Linux: GPU-Acceleration and Multi-GPU

If you have an NVIDIA GPU on your host system, you will be able to use it without any further installation steps.

If you want to perform multi-GPU simulations, additional components must be installed. We recommend using Conda to do so. If you are not already using Conda, you can install a minimal version following miniconda instructions here. The following commands will create and activate a complete environment for CUDA-Q with all its dependencies:

cuda_version=${{ cuda_version_conda }} # set this variable to version ${{ cuda_version_requirement }}
conda create -y -n cudaq-env python=3.11 pip
conda install -y -n cudaq-env -c "nvidia/label/cuda-${cuda_version}" cuda
conda install -y -n cudaq-env -c conda-forge mpi4py openmpi">=5.0.3" cxx-compiler
conda env config vars set -n cudaq-env LD_LIBRARY_PATH="$CONDA_PREFIX/envs/cudaq-env/lib:$LD_LIBRARY_PATH"
conda env config vars set -n cudaq-env MPI_PATH=$CONDA_PREFIX/envs/cudaq-env
conda activate cudaq-env
pip install ${{ package_name }}
source $CONDA_PREFIX/lib/python3.11/site-packages/distributed_interfaces/activate_custom_mpi.sh

Warning (conda-forge): Installing cudaq from the conda-forge channel on recent versions of Python can lead to segmentation faults. If you see such errors, please switch to one of the Python versions 3.11.10 or 3.12.7 as per the issue #2999 or #3104.

You must configure MPI by setting the following environment variables:

export OMPI_MCA_opal_cuda_support=true OMPI_MCA_btl='^openib'

If you do not set these variables you may encounter a segmentation fault.

Important: It is not sufficient to set these variable within the Conda environment, like the commands above do for LD_LIBRARY_PATH. To avoid having to set them every time you launch a new shell, we recommend adding them to ~/.profile (create the file if it does not exist), and to ~/.bash_profile or ~/.bash_login if such a file exists.

macOS

GPU-acceleration is not available on macOS, so a virtual environment is all you need:

python3 -m venv .venv
source .venv/bin/activate
pip install cudaq

MPI uses SSH or RSH to communicate with each node unless another resource manager, such as SLURM, is used. If you are encountering an error "The value of the MCA parameter plm_rsh_agent was set to a path that could not be found", please make sure you have an SSH Client installed.

Running CUDA-Q

You should now be able to import CUDA-Q and start building quantum programs in Python!

import cudaq

kernel = cudaq.make_kernel()
qubit = kernel.qalloc()
kernel.x(qubit)
kernel.mz(qubit)

result = cudaq.sample(kernel)

Additional examples and documentation are linked in the release notes.

Contributing

There are many ways in which you can get involved with CUDA-Q. If you are interested in developing quantum applications with CUDA-Q, our GitHub repository is a great place to get started! For more information about contributing to the CUDA-Q platform, please take a look at Contributing.md.

License

CUDA-Q is an open source project. The source code is available on GitHub and licensed under Apache License 2.0. CUDA-Q makes use of the NVIDIA cuQuantum SDK to enable high-performance simulation, which is held to its own respective license.

Feedback

Please let us know your feedback and ideas for the CUDA-Q platform in the Discussions tab of our GitHub repository, or file an issue. To report security concerns please reach out to cuda-quantum@nvidia.com.