Release Notes
*************

cuQuantum Appliance 22.02-Cirq
==============================

The container image for NVIDIA cuQuantum Appliance 22.02 Cirq is available on `NGC <https://catalog.ngc.nvidia.com/orgs/nvidia/containers/cuquantum-appliance>`_.

* A new multi-GPU simulator backend optimized for NVIDIA DGX A100 with the following features:

  * Sampling the state vector
  * Performing a measurement on the state vector
  * Full state vector simulation

Contents of the cuQuantum Appliance 22.02-Cirq container
--------------------------------------------------------

This container contains a modified version of Google's qsim. It is pre-built and install in the default conda environment at the following location in the container:

.. code-block:: bash

  /opt/conda/lib/python3.8/site-packages/qsimcirq

The container also includes the following:

* `Cirq 0.13.1 <https://github.com/quantumlib/Cirq/releases/tag/v0.13.1>`_
* `Numpy 1.22 <https://numpy.org/doc/stable/release.html>`_
* `Ubuntu 20.04 <http://releases.ubuntu.com/20.04/>`_ including `Python 3.8 <https://www.python.org/downloads/release/python-3812/>`_
* `NVIDIA CUDA 11.5.1 <https://docs.nvidia.com/cuda/archive/11.5.1/>`_
* :ref:`NVIDIA cuQuantum SDK 0.1.1 <cuquantum_sdk_release_notes:cuQuantum SDK v0.1.1>`

Driver requirements
-------------------

This cuQuantum Appliance 22.02-Cirq container release is based on NVIDIA CUDA 11.5.1, which requires `NVIDIA Driver <https://www.nvidia.com/Download/index.aspx?lang=en-us>`_ release 450 or later.

GPU Requirements
----------------

This cuQuantum Appliance 22.02-Cirq container release supports CUDA compute capability 7.0 and higher.
This corresponds to GPUs in the NVIDIA Volta, Turing, and Ampere GPU architecture families.
For a list of CUDA GPUs and their compute capabilities, please refer to `this page <https://developer.nvidia.com/cuda-gpus#compute>`_.
When using the multi-GPU backend, all GPUs involved must be mutually peer-accessible.

Known Limitations
-----------------

When using the multi-GPU backend:

* Results from the multi-GPU backend may be aggregated in Python using a single thread. In some cases, this leads to longer-than-expected runtimes.
* The largest gate or observable in a quantum circuit must not exceed the size of the smallest state-vector partition (e.g.) a 3-qubit circuit with a 3-qubit gate where :code:`n_subsvs > 1` will produce an error.
* Noisy elements of a quantum circuit are ignored. The corresponding noiseless circuit is passed to the simulator backend.
* Hybrid simulation is disabled.

The NVIDIA cuQuantum Appliance is based on the NVIDIA CUDA base container, and the NVIDIA container relies on `constraints <https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/user-guide.html#constraints>`_
using the :code:`NVIDIA_REQUIRE_*` to support `CUDA compatibility <https://docs.nvidia.com/deploy/cuda-compatibility/#cuda-intro>`_ checks.
There is a known issue with how the variable is defined in CUDA 11.5 and users may encounter the following error:

.. code-block:: bash

  nvidia-container-cli: requirement error: unsatisfied condition: cuda>=11.5, please update your driver to a newer version ...

* The suggested workaround is to disable the constraint checks either by defining the following environment variable:

  * :code:`NVIDIA_DISABLE_REQUIRE=1`

* or by using an additional option to Docker's CLI when running the container:

  * :code:`--env NVIDIA_DISABLE_REQUIRE=1`