General

CUDA-Q is a programming model and a toolchain to exploit quantum acceleration in heterogeneous applications; it is available both in C++ and Python.

As acceleration entities, it targets both NVIDIA GPGPUs, via the NVIDIA cuQuantum SDK, as well as real QPUs. Regarding offloading on GPGPUs, because of cuQuantum SDK, the only compatible NVIDIA architectures are from Volta onwards.

CUDA-Q is a C++ language extension and it introduces, among other entities, new types to deal with qudits and quantum gates; it is thus possible to implement quantum circuits, which are then executed by so-called quantum kernels. C++ programs are then compiled and linked using the CUDA-Q toolchain which is comprised of a dedicated C++ compiler; such compiler is realized using industry-standard LLVM compilation framework, and a set of dedicated libraries.

Project website / official documentation

https://nvidia.github.io/cuda-quantum/latest/index.html

https://github.com/NVIDIA/cuda-quantum

Author(s)

NVIDIA Development Team

License

Apache 2.0

Current version/version supported by LRZ

0.5.0

Supported HPC systems

AI System

Installation/deployment

Here we describe how to install CUDA-Q on the LRZ AI System, both in the case of C++ and Python.

C++

In the case of C++, it is necessary to deploy a Docker container; such a container is provided for free by NVIDIA in the NVIDIA NGC Catalog container registry. However, on any HPC system, and this includes the LRZ AI System, the following constraints have to be considered:

Docker is not available for security reasons

On the LRZ AI System is available the NVIDIA enroot container engine, which provides the functionality to convert and run Docker containers into Squash file format.

A pre-condition to have enroot available as a command, is to be logged in a compute node equipped with one of the available NVIDIA GPGPUs; as an example here we give the command to reserve one GPU on an NVIDIA Ampere DGX:

Reserving NVIDIA Ampere DGX

salloc -p lrz-dgx-a100-80x8 --gres=gpu:1 --time=1:00:00

Refer to this LRZ page to prepare your Linux user environment to import containers from the NVIDIA NGC Catalog container registry. After setting up the required NVIDIA NGC Account, in order to configure Enroot for using your previously generated API Key, create the file enroot/.credentials within your $HOME and append the following to it:

Enroot setup

login nvcr.io login $oauthtoken password <API_KEY>

To import the CUDA-Q Docker image run the following instruction:

Import container with enroot

# create a working directory
mkdir path/to/working/directory
cd path/to/working/directory

# login to interactive node
srun --pty bash

# import CUDA-Q image from registry
enroot import --output cuda-quantum-latest.sqsh docker://nvcr.io#nvidia/nightly/cuda-quantum:latest

If you specified the --output option, you will now have a file named as desired in your working directory; in the example we used cuda-quantum-latest.sqsh. The image file can be run as follows:

Run enroot container image

enroot start --rw --root cuda-quantum-latest.sqsh
# --rw is necessary to have read/write permission in the container
# --root give you root access to the container

Now you can compile your application to be accelerated both on single and multiple GPGPUs.

Where to implement your application

Our suggestion is to first implement your C++ application on a separate system directly in the Docker container, where all software requirements for CUDA-Q are satisfied; you could use a remote location to store your code (such as a git remote repository).

A good option for this workflow is to use VS Code with the Dev Containers extension, see CUDA-Q documentation for a walk-through.

Once you are on the LRZ AI System, inside the CUDA-Q container, you will just have to retrieve the source code for your application and compile it.

Python

CUDA-Q Python is available in the official container image provided by NVIDIA. See the above section on how to retrieve it and execute it on the LRZ AI cluster.

Once in the container, to execute your Python script you can simply run the following command on the container prompt:

Run CUDAQ Python script

 python cudaq_example_script.py

For everything regarding the optimal workflow to develop your CUDA-Q application, we refer the user to the above section.

Example(s) for usage

Valid examples can be found in the official CUDA-Q documentation.

CUDA-Q (Nvidia)