Linux / amd64
The NVIDIA cuQuantum Appliance is a highly performant multi-GPU multi-node solution for quantum circuit simulation. It contains NVIDIA’s cuStateVec and cuTensorNet libraries which optimize state vector and tensor network simulation, respectively. The cuTensorNet library functionality is accessible through Python for Tensor Network operations. With the cuStateVec libraries, NVIDIA provides the following simulators:
IBM’s Qiskit Aer frontend via cusvaer, NVIDIA’s distributed state vector backend solver.
A multi-GPU-optimized Google Cirq frontend via qsim, Google’s state vector simulator.
Using NVIDIA’s cuQuantum Appliance NGC Container requires the host system to have the following installed:
Docker Engine
NVIDIA GPU Drivers
NVIDIA Container Toolkit
For supported versions, see the container release notes. No other installation, compilation, or dependency management is required.
...$ docker pull nvcr.io/nvidia/cuquantum-appliance:23.10 # pull the image
...$ docker run --gpus all -it --rm nvcr.io/nvidia/cuquantum-appliance:23.10 # launch the container interactively
...$ docker run --gpus '"device=0,3"' -it --rm nvcr.io/nvidia/cuquantum-appliance:23.10 # ... interactive launch, but enumerate only GPUs 0,3
The examples are located under /home/cuquantum/examples
. Confirm this with the following command:
...$ docker run --gpus all --rm nvcr.io/nvidia/cuquantum-appliance:23.10 ls -la /home/cuquantum/examples
...
==========================================================================
=== NVIDIA CUQUANTUM APPLIANCE v23.10 ===
==========================================================================
=== COPYRIGHT © NVIDIA CORPORATION & AFFILIATES. All rights reserved. ===
==========================================================================
INFO: nvidia devices detected
INFO: gpu functionality will be available
total 36
drwxr-xr-x 2 cuquantum cuquantum 4096 Nov 10 01:52 .
drwxr-x--- 1 cuquantum cuquantum 4096 Nov 10 01:54 ..
-rw-r--r-- 1 cuquantum cuquantum 2150 Nov 10 01:52 ghz.py
-rw-r--r-- 1 cuquantum cuquantum 7436 Nov 10 01:52 hidden_shift.py
-rw-r--r-- 1 cuquantum cuquantum 1396 Nov 10 01:52 qiskit_ghz.py
-rw-r--r-- 1 cuquantum cuquantum 8364 Nov 10 01:52 simon.py
Running the examples is straightforward:
#### without an interactive session:
...$ docker run --gpus all --rm nvcr.io/nvidia/cuquantum-appliance:23.10 python /home/cuquantum/examples/{example_name}.py
#### with an interactive session:
...$ docker run --gpus all --rm -it nvcr.io/nvidia/cuquantum-appliance:23.10
...
(cuquantum-23.10) cuquantum@...:~$ cd examples && python {example_name}.py
The examples all accept runtime arguments. To see what they are, pass --help
to the python + script command. Looking at two examples, ghz.py
and qiskit_ghz.py
, the help messages are as follows:
(cuquantum-23.10) cuquantum@...:~/examples$ python ghz.py --help
usage: ghz.py [-h] [--nqubits NQUBITS] [--nsamples NSAMPLES] [--ngpus NGPUS]
GHZ circuit
options:
-h, --help show this help message and exit
--nqubits NQUBITS the number of qubits in the circuit
--nsamples NSAMPLES the number of samples to take
--ngpus NGPUS the number of GPUs to use
(cuquantum-23.10) cuquantum@...:~/examples$ python qiskit_ghz.py --help
usage: qiskit_ghz.py [-h] [--nbits NBITS] [--precision {single,double}] [--disable-cusvaer]
Qiskit ghz.
options:
-h, --help show this help message and exit
--nbits NBITS the number of qubits
--precision {single,double}
numerical precision
--disable-cusvaer disable cusvaer
Importantly, ghz.py
implements the GHZ circuit using Cirq as a frontend, and qiskit_ghz.py
implements the GHZ circuit using Qiskit as a frontend. The cuQuantum Appliance modifies the backends of these frameworks, optimizing them for use with NVIDIA's platforms. Information regarding any alterations are available in the Appliance section of the NVIDIA cuQuantum documentation.
Running cd examples && python ghz.py --nqubits 30
will create and simulate a GHZ circuit running on a single GPU. To run on 4
available GPUs, use ... python ghz.py --nqubits 30 --ngpus 4
. The output will look something like this:
(cuquantum-23.10) cuquantum@...:~/examples$ python ghz.py --nqubits 30
q(0),q(1),q(2),q(3),q(4),q(5),q(6),q(7),q(8),q(9),q(10),q(11),q(12),q(13),q(14),q(15),q(16),q(17),q(18),q(19),q(20),q(21),q(22),q(23),q(24),q(25),q(26),q(27),q(28),q(29)=111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111, 111
Likewise, cd examples && python qiskit_ghz.py --nbits 30
will create and simulate a GHZ circuit running on all available GPUs. To run on 4
GPUs, you need to launch the container and explicitly enumerate the GPUs you want to use:
#### interactively:
...$ docker run --gpus '"device=0,1,2,3"' -it --rm nvcr.io/nvidia/cuquantum-appliance:23.10
(cuquantum-23.10) cuquantum@...:~$ cd examples && python qiskit_ghz.py --nbits 30
#### noninteractively:
...$ docker run --gpus '"device=0,1,2,3"' --rm nvcr.io/nvidia/cuquantum-appliance:23.10 python /home/cuquantum/examples/qiskit_ghz.py --nbits 30
The output from qiskit_ghz.py
looks like this:
(cuquantum-23.10) cuquantum@...:~$ cd examples && python qiskit_ghz.py --nbits 30
...
precision: single
{'000000000000000000000000000000': 520, '111111111111111111111111111111': 504}
More information, examples, and utilities are available in the NVIDIA cuQuantum repository on GitHub. Notably, you can find useful guides for getting started with multi-node multi-GPU simulation using the benchmarks tools.
The default container user is cuquantum
with user ID 1000
. The cuquantum
user is a member of the sudo
group. By default, executing commands with sudo
using the cuquantum
user requires a password which can be obtained by reading the file located at /home/cuquantum/.README
formatted as {user}:{password}
.
To acquire new packages, we recommend using conda install -c conda-forge ...
in the default environment (cuquantum-23.10
). You may clone this environment and change the name using conda create --name {new_name} --clone cuquantum-23.10
. This may be useful in isolating your changes from the base environment provided by default.
In the container, CUDA Toolkit 11.8 is available under /usr/local/cuda-11.8
. A symbolic directory exists at /usr/local/cuda
. This is managed by update-alternatives
. To query configuration information, use update-alternatives --config cuda
.
Finally, we provide Open MPI v4.1.4 in the container located at /usr/local/openmpi
.
For a general guide on pulling and running containers, see Pulling a Container Image and Running a Container in the NGC Container User Guide.
== 23.10
There are now 3 new image tags available:
nvcr.io/nvidia/cuquantum-appliance:23.10
nvcr.io/nvidia/cuquantum-appliance:23.10-devel-ubuntu22.04
nvcr.io/nvidia/cuquantum-appliance:23.10-devel-ubuntu20.04
Before v23.10, the operating system in the container was Ubuntu 20.04.
In v23.10, we added support for Ubuntu 22.04 without dropping support for Ubuntu 20.04.
To avoid breaking changes implied by altering the image tag, nvcr.io/nvidia/cuquantum-appliance:23.10
now points to nvcr.io/nvidia/cuquantum-appliance:23.10-devel-ubuntu22.04
.
This means that
#### this pull command
...$ docker pull nvcr.io/nvidia/cuquantum-appliance:23.10
#### is the same as this pull command
...$ docker pull nvcr.io/nvidia/cuquantum-appliance:23.10-devel-ubuntu22.04
23.10
security scanning results summaryThis section provides a summary of potential vulnerabilities that are evaluated with high severity by the CVSS v3.1 standard. To view security scanning results for the latest container image, refer to the security scanning tab near the top of this page, or follow this link.
CVE ID | SCORE | VECTOR | STATUS | DESCRIPTION | REFERENCES |
---|---|---|---|---|---|
CVE-2023-36632 | 7.5 | CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H | DISPUTED | RecursionError in email.utils.parseaddr while calling Python object |
CVE |
CVE-2018-20225 | 7.8 | CVSS:3.1/AV:L/AC:L/PR:N/UI:R/S:U/C:H/I:H/A:H | DISPUTED | remote code execution with malicious url using --extra-index-url option in pip |
CVE |
VERSION | STATUS | NOTICE |
---|---|---|
23.10 | SUPPORTED | N/A |
23.06 | SUPPORTED | EOL 24.03 |
23.03 | EOL | No new features or security remediation |
22.* | EOL | No new features or security remediation |
Note: for a version formatted as YY.*
, the notice applies to all versions with the same year.
The NVIDIA cuQuantum Appliance documentation is hosted here.
A guide for using Qiskit can be found here.
A guide and tutorials for using Cirq can be found here.
A guide to getting started with qsimcirq can be found here.
The NVIDIA cuQuantum SDK Homepage
The NVIDIA cuQuantum Python Bindings and Examples
The image is governed by the NVIDIA End User License Agreement.
By downloading the NVIDIA cuQuantum Appliance, you accept the terms and conditions of this license.
The cuQuantum Appliance End User License Agreement can be viewed here.
Since the image includes components licensed under open-source licenses, the source code for these components can be found here.