CUDA Quantum Open Beta Installation

Docker Image

Install the Docker Image

Docker images for all CUDA Quantum releases are available on the NGC Container Registry. To download images from NGC, please follow the following steps if you have not done so already:

  • Create an account

  • Sign in to access your account and go to Setup.

  • Click on Get API Key and generate a new key (this will invalidate any existing keys).

  • Follow the instructions that appear to use that key to log in to the NGC registry using Docker.

Once you have done so, run docker login nvcr.io (again) to confirm you can authenticate with the registry. You should see a message “Login Succeeded”.

In addition to publishing stable releases, we also publish docker images whenever we update the main branch of our GitHub repository. These images are published in a separate location nvidia/nightly on NGC, as well as on GitHub. To download the latest version on the main branch of our GitHub repository, for example, use the command

docker pull nvcr.io/nvidia/nightly/cuda-quantum:latest

Use CUDA Quantum in a Terminal

The container can be run using the following command

docker run -it --name cuda-quantum <image_name>

replacing <image_name> with the name and tag of the image you downloaded.

This will give you terminal access to the created container, for example

user@host:~$ docker run -it --name cuda-quantum nvcr.io/nvidia/nightly/cuda-quantum:latest
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

=========================
NVIDIA CUDA Quantum
=========================

Version: latest

Copyright (c) 2023 NVIDIA Corporation & Affiliates
All rights reserved.

cudaq@container:~$ ls examples/
cpp  python

Note

If you have NVIDIA GPUs available and NVIDIA Docker correctly configured, you can add --gpus all to the docker run command to expose all available GPUs to the container, or --gpus '"device=1"' to select a specific GPU device. Unless you specify this flag, you will not be able to compile to the --target nvidia target.

Note

If you would like a temporary container, pass --rm. This will delete your container upon exit.

You can stop and exit the container by typing the command exit. If you did not specify --rm, the container still exists as well as any changes you made in it. You can get back to it using the command docker start -i cuda-quantum. You can delete an existing container and any changes you made using docker rm -v cuda-quantum.

Use CUDA Quantum in VS Code

If you have VS Code installed, you can use it to work inside your container. To do so, install the Dev Containers extension:

_images/devContainersExtension.png

Follow the steps above to start the container. Open VS Code and navigate to the Remote Explorer. You should see the running cuda-quantum development container listed there.

_images/attachToDevContainer.png

Click on Attach to Container. A new VS Code instance will open in that container. Open the /home/cudaq folder to see the README.md file and the CUDA Quantum examples that are included in the container. To run the examples, open a terminal by going to the Terminal menu and select New Terminal.

_images/openTerminal.png

You can now compile and run the C++ examples using the nvq++ compiler, which is installed in your PATH, or run the Python examples using the Python interpreter.

_images/getToWork.png

Note

VS Code extensions that you have installed locally, such as e.g. an extension for Jupyter notebooks, may not be automatically active in the container environment. You may need to install your preferred extension in the container environment for all of your development tools to be available.

Python wheels

CUDA Quantum Python wheels are available on PyPI.org. Installation instructions can be found in the project description. For more information about available versions and documentation, see CUDA Quantum Versions.

At this time, wheels are distributed for Linux operating systems only.

There are currently no source distributions available on PyPI, but you can download the source code for the latest version of the CUDA Quantum Python wheels from our GitHub repository. The source code for previous versions can be downloaded from the respective GitHub Release.

To build the CUDA Quantum Python API from source using pip, run the following commands:

git clone https://github.com/NVIDIA/cuda-quantum.git
cd cuda-quantum && ./scripts/install_prerequisites.sh
pip install .

For more information about building the entire C++ and Python API’s, please see Building from Source.

Building from Source

Instructions for building the Python wheels from source are given in the section Python wheels. For more information about building the entire C++ and Python API from source, we refer to the CUDA Quantum GitHub repository.

Dependencies and Compatibility

CUDA Quantum can be used to compile and run quantum programs on a CPU-only system, but a GPU is highly recommended and necessary to use the GPU-based simulators, see also CUDA Quantum Simulation Backends.

The supported CPUs include x86_64 (x86-64-v3 architecture and newer) and ARM64 architectures.

Note

Some of the components included in the CUDA Quantum Python wheels depend on an existing CUDA installation on your system. For more information about installing the CUDA Quantum Python wheels, take a look at this section.

The following table summarizes the required components.

Supported Systems

CPU architectures

x86_64, ARM64

Operating System

Linux

Tested Distributions

CentOS 8; Debian 11, 12; Fedora 38; OpenSUSE/SELD/SLES 15.5; RHEL 8, 9; Rocky 8, 9; Ubuntu 22.04

Python versions

3.8+
Requirements for GPU Simulation

GPU Architectures

Volta, Turing, Ampere, Ada, Hopper

NVIDIA GPU with Compute Capability

7.0+

CUDA

11.x (Driver 470.57.02+), 12.x (Driver 525.60.13+)

Detailed information about supported drivers for different CUDA versions and be found here.

Next Steps

The Docker image contains a folder with example in the /home/cudaq directory. These examples are provided to get you started with CUDA Quantum and understanding the programming and execution model. If you are not using the Docker image, you can find these examples on our GitHub repository.

Start of by trying to compile a simple one, like examples/cpp/basics/static_kernel.cpp:

nvq++ examples/cpp/basics/static_kernel.cpp
./a.out

If you have GPU support (e.g. you successfully provided --gpus to your docker run command), try out the 30 qubit version of this example.

nvq++ examples/cpp/basics/cuquantum_backends.cpp --target nvidia
./a.out

For more information about developing and running CUDA Quantum code, take a look at the page Using CUDA Quantum.