Merge branch 'main' of https://github.com/NVIDIA/cuda-quantum into dynamics_cpp_operators

Signed-off-by: Bettina Heim <[email protected]>

Author: bettinaheim

.github/workflows/clean_up.yml

@@ -51,7 +51,7 @@ jobs:
 
     steps:
       - run: |
-          gh release list -L 100 -R ${{ github.repository }} > rels.txt
+          gh release list -L 1000 -R ${{ github.repository }} > rels.txt
           while read rel _; do 
             isDraft=`gh release view $rel -R ${{ github.repository }} --json isDraft --jq '.isDraft'`
             isPrerelease=`gh release view $rel -R ${{ github.repository }} --json isPrerelease --jq '.isPrerelease'`

.github/workflows/docker_images.yml

@@ -707,6 +707,11 @@ jobs:
           fi
 
           docker run --rm -dit --network host --name cuda-quantum-dev $cudaqdev_image
+          # Unfortunately, we need to install cuquantum for docs generation to work properly, 
+          # since using mock imports in the autodocs configuration doesn't work properly. 
+          # See also https://github.com/sphinx-doc/sphinx/issues/11211. 
+          docker exec cuda-quantum-dev bash -c "python3 -m pip install cuquantum-python-cu12~=24.11"
+          
           (docker exec cuda-quantum-dev bash -c "export $docs_version && bash scripts/build_docs.sh" && built=true) || built=false
           if $built; then docker cp cuda-quantum-dev:"/usr/local/cudaq/docs/." docs; \
           else docker cp cuda-quantum-dev:"/workspaces/cuda-quantum/build/." /tmp/build; fi

.github/workflows/python_metapackages.yml

@@ -77,7 +77,7 @@ jobs:
 
             echo "Creating README.md for cuda-quantum package"
             echo "# Welcome to the CUDA-Q Python API" > README.md
-            echo "This package is deprecated and new versions are published under the name `cudaq` instead." >> README.md
+            echo "This package is deprecated and new versions are published under the name \`cudaq\` instead." >> README.md
             echo "For more information, please see [CUDA-Q on PyPI](https://pypi.org/project/cudaq)." >> README.md
 
             echo "Building cuda-quantum metapackage ..."
@@ -195,8 +195,6 @@ jobs:
           fi
 
       - name: Test installation error
-        # FIXME: We actually don't give a proper install error if there are conflicting packages on the system...
-        if: matrix.cuda_version == ''
         run: |
           python=python${{ matrix.python_version }}
           $python -m pip install pypiserver
@@ -211,11 +209,13 @@ jobs:
               set -e && check_package=cuda-quantum
             ;; 
             12.*) 
+              test_conflicting=cuda-quantum-cu11
               $python -m pip install cuda-quantum-cu11==${{ inputs.cudaq_version }} \
                 --extra-index-url http://localhost:8080 
               set +e # continue on error
               $python -m pip install cudaq==${{ inputs.cudaq_version }} -v \
-                --extra-index-url http://localhost:8080
+                --extra-index-url http://localhost:8080 \
+              2>&1 | tee /tmp/install.out
               set -e && check_package=cudaq
             ;; 
             *) 
@@ -225,17 +225,37 @@ jobs:
               set -e
               if [ -z "$($python -m pip list | grep cuda-quantum)" ]; then 
                 # if we don't have a 0.8.0 version for this python version, test other conflict
+                test_conflicting=cuda-quantum-cu12
                 $python -m pip install cuda-quantum-cu12==${{ inputs.cudaq_version }} \
                   --extra-index-url http://localhost:8080
+              else
+                test_conflicting=cuda-quantum
               fi
               set +e # continue on error
               $python -m pip install cudaq==${{ inputs.cudaq_version }} -v \
-                --extra-index-url http://localhost:8080
+                --extra-index-url http://localhost:8080 \
+              2>&1 | tee /tmp/install.out
               set -e && check_package=cudaq
             ;; 
           esac
 
-          if [ -n "$($python -m pip list | grep ${check_package})" ]; then 
+          # The autodetection will fail if the runner does not have a GPU.
+          # In that case, we will only check if the install failed, if the
+          # package we want to test the conflict detection for is not the
+          # default package that is installed when there is no GPU.
+          if [ -f /tmp/install.out ] && [ -z "$(cat /tmp/install.out | grep -o 'Autodetection succeeded')" ]; then
+            # Autodetection failed - a default choice of the binary distribution will be installed.
+            echo "::warning::Autodetection to determine cudaq binary distribution failed."
+            # Take the first Identified best package because the logs print multiple lines.
+            # They should all be the same, if they differ in the build environment then there is probably issues.
+            installed_default=$(cat /tmp/install.out | sed -nE 's/.*Identified (\S*) as the best package.*/\1/p' | head -n 1)
+            echo "::warning::The installed default is ${installed_default}, the potential conflicting package is ${test_conflicting}"
+            if [ "$installed_default" == "$test_conflicting" ]; then
+              check_package=none
+            fi
+          fi
+
+          if [ "$check_package" != "none" ] && [ -n "$($python -m pip list | grep ${check_package})" ]; then
             echo "::error file=python_metapackages.yml::Unexpected installation of ${check_package} package."
             exit 1
           fi

docker/build/devdeps.ext.Dockerfile

@@ -59,7 +59,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends gnupg \
 
 ARG PMI_INSTALL_PREFIX=/usr/local/pmi
 ENV PMI_INSTALL_PREFIX="$PMI_INSTALL_PREFIX"
-ENV LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$PMIX_INSTALL_PREFIX/lib"
+ENV LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$PMI_INSTALL_PREFIX/lib"
 COPY --from=ompibuild "$PMI_INSTALL_PREFIX" "$PMI_INSTALL_PREFIX"
 
 # Copy over GDRCOPY and install runtime dependencies.
@@ -161,7 +161,10 @@ ENV CUDA_PATH="$CUDA_INSTALL_PREFIX"
 ENV PATH="${CUDA_INSTALL_PREFIX}/lib64/:${CUDA_INSTALL_PREFIX}/bin:${PATH}"
 
 # Install cuQuantum dependencies, including cuTensor.
-RUN python3 -m pip install cuquantum-python-cu$(echo $CUDA_VERSION | cut -d . -f1)~=24.11 && \
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip && \
+    apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* && \
+    python3 -m pip install cuquantum-python-cu$(echo $CUDA_VERSION | cut -d . -f1)~=24.11 && \
     if [ "$(python3 --version | grep -o [0-9\.]* | cut -d . -f -2)" != "3.10" ]; then \
         echo "expecting Python version 3.10"; \
     fi
@@ -173,7 +176,7 @@ ENV CUQUANTUM_PATH="$CUQUANTUM_INSTALL_PREFIX"
 ENV LD_LIBRARY_PATH="$CUQUANTUM_INSTALL_PREFIX/lib:$LD_LIBRARY_PATH"
 ENV CPATH="$CUQUANTUM_INSTALL_PREFIX/include:$CPATH"
 
-ARG CUTENSOR_INSTALL_PREFIX=/usr/local/lib/python3.10/dist-packages/cutensor/
+ARG CUTENSOR_INSTALL_PREFIX=/usr/local/lib/python3.10/dist-packages/cutensor
 ENV CUTENSOR_INSTALL_PREFIX="$CUTENSOR_INSTALL_PREFIX"
 ENV CUTENSOR_ROOT="$CUTENSOR_INSTALL_PREFIX"
 ENV LD_LIBRARY_PATH="$CUTENSOR_INSTALL_PREFIX/lib:$LD_LIBRARY_PATH"

docker/release/cudaq.Dockerfile

@@ -32,7 +32,7 @@ FROM $cudaqdev_image AS cudaqbuild
 # access to the environment variables, so that the hardcoded paths in this file don't need to 
 # match the paths in the dev image.
 RUN mkdir /usr/local/cudaq_assets && cd /usr/local/cudaq_assets && \
-    mkdir -p llvm/bin && mkdir -p llvm/lib && mkdir cuquantum && \
+    mkdir -p llvm/bin && mkdir -p llvm/lib && \
     mv "$LLVM_INSTALL_PREFIX/bin/"clang* "/usr/local/cudaq_assets/llvm/bin/" && rm -rf "/usr/local/cudaq_assets/llvm/bin/"clang-format* && \
     mv "$LLVM_INSTALL_PREFIX/lib/"clang* "/usr/local/cudaq_assets/llvm/lib/" && \
     mv "$LLVM_INSTALL_PREFIX/bin/llc" "/usr/local/cudaq_assets/llvm/bin/llc" && \
@@ -56,10 +56,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # Install CUDA-Q runtime dependencies.
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-        python3 python3-pip libstdc++-12-dev \
+        libstdc++-12-dev python3 python3-pip \
     && apt-get autoremove -y && apt-get clean && rm -rf /var/lib/apt/lists/* \
-    && python3 -m pip install --no-cache-dir \
-        numpy scipy cuquantum-python-cu$(echo ${CUDA_VERSION:-12} | cut -d . -f1)~=24.11 \
+    && python3 -m pip install --no-cache-dir numpy scipy \
     && ln -s /bin/python3 /bin/python
 RUN apt-get update && apt-get install -y --no-install-recommends gcc g++ python3-dev \
     # Ref: https://github.com/qutip/qutip/issues/2412

docs/sphinx/conf.py

@@ -179,6 +179,10 @@ def setup(app):
 
 autosummary_generate = True
 
+# This is unfortunately not sufficient for docs generation, due to the use of Union type;
+# see also https://github.com/sphinx-doc/sphinx/issues/11211. 
+# autodoc_mock_imports = ['cuquantum', 'cupy']
+
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),

docs/sphinx/targets/cpp/braket.cpp

@@ -0,0 +1,45 @@
+// Compile and run with:
+// ```
+// nvq++ --target braket braket.cpp -o out.x && ./out.x
+// ```
+// This will submit the job to the Amazon Braket state vector simulator
+// (default). Alternatively, users can choose any of the available devices by
+// specifying its `ARN` with the `--braket-machine`, e.g.,
+// ```
+// nvq++ --target braket --braket-machine \
+// "arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet" braket.cpp -o out.x
+// ./out.x
+// ```
+// Assumes a valid set of credentials have been set prior to execution.
+
+#include <cudaq.h>
+#include <fstream>
+
+// Define a simple quantum kernel to execute on Amazon Braket.
+struct ghz {
+  // Maximally entangled state between 5 qubits.
+  auto operator()() __qpu__ {
+    cudaq::qvector q(5);
+    h(q[0]);
+    for (int i = 0; i < 4; i++) {
+      x<cudaq::ctrl>(q[i], q[i + 1]);
+    }
+    auto result = mz(q);
+  }
+};
+
+int main() {
+  // Submit asynchronously (e.g., continue executing
+  // code in the file until the job has been returned).
+  auto future = cudaq::sample_async(ghz{});
+  // ... classical code to execute in the meantime ...
+
+  // Get the results of the read in future.
+  auto async_counts = future.get();
+  async_counts.dump();
+
+  // OR: Submit synchronously (e.g., wait for the job
+  // result to be returned before proceeding).
+  auto counts = cudaq::sample(ghz{});
+  counts.dump();
+}

docs/sphinx/targets/python/braket.py

@@ -0,0 +1,41 @@
+import cudaq
+
+# NOTE: Amazon Braket credentials must be set before running this program.
+# Amazon Braket costs apply.
+cudaq.set_target("braket")
+
+# The default device is SV1, state vector simulator. Users may choose any of
+# the available devices by supplying its `ARN` with the `machine` parameter.
+# For example,
+# ```
+# cudaq.set_target("braket", machine="arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet")
+# ```
+
+
+# Create the kernel we'd like to execute
+@cudaq.kernel
+def kernel():
+    qvector = cudaq.qvector(2)
+    h(qvector[0])
+    x.ctrl(qvector[0], qvector[1])
+    mz(qvector)
+
+
+# Execute and print out the results.
+
+# Option A:
+# By using the asynchronous `cudaq.sample_async`, the remaining
+# classical code will be executed while the job is being handled
+# by Amazon Braket.
+async_results = cudaq.sample_async(kernel)
+# ... more classical code to run ...
+
+async_counts = async_results.get()
+print(async_counts)
+
+# Option B:
+# By using the synchronous `cudaq.sample`, the execution of
+# any remaining classical code in the file will occur only
+# after the job has been returned from Amazon Braket.
+counts = cudaq.sample(kernel)
+print(counts)

docs/sphinx/using/backends/backends.rst

@@ -12,6 +12,7 @@ CUDA-Q Backends
 
 **The following is a comprehensive list of the available targets in CUDA-Q:**
 
+* :ref:`braket <braket-backend>`
 * :ref:`density-matrix-cpu <default-simulator>`
 * :ref:`fermioniq <fermioniq-backend>`
 * :ref:`ionq <ionq-backend>`

docs/sphinx/using/backends/hardware.rst

@@ -5,6 +5,114 @@ CUDA-Q supports submission to a set of hardware providers.
 To submit to a hardware backend, you need an account with the respective provider.
 
 
+Amazon Braket
+==================================
+
+.. _braket-backend:
+
+`Amazon Braket <https://aws.amazon.com/braket/>`__ is a fully managed AWS 
+service which provides Jupyter notebook environments, high-performance quantum 
+circuit simulators, and secure, on-demand access to various quantum computers.
+To get started users must enable Amazon Braket in their AWS account by following 
+`these instructions <https://docs.aws.amazon.com/braket/latest/developerguide/braket-enable-overview.html>`__.
+To learn more about Amazon Braket, you can view the `Amazon Braket Documentation <https://docs.aws.amazon.com/braket/>`__ 
+and `Amazon Braket Examples <https://github.com/amazon-braket/amazon-braket-examples>`__.
+A list of available devices and regions can be found `here <https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html>`__. 
+
+Users can run CUDA-Q programs on Amazon Braket with `Hybrid Job <https://docs.aws.amazon.com/braket/latest/developerguide/braket-what-is-hybrid-job.html>`__.
+See `this guide <https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-first.html>`__ to get started.
+
+Setting Credentials
+```````````````````
+
+After enabling Amazon Braket in AWS, set credentials using any of the documented `methods <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html>`__.
+One of the simplest ways is to use `AWS CLI <https://aws.amazon.com/cli/>`__.
+
+.. code:: bash
+
+    aws configure
+
+Alternatively, users can set the following environment variables.
+
+.. code:: bash
+
+  export AWS_DEFAULT_REGION="<region>"
+  export AWS_ACCESS_KEY_ID="<key_id>"
+  export AWS_SECRET_ACCESS_KEY="<access_key>"
+  export AWS_SESSION_TOKEN="<token>"
+
+Submission from C++
+`````````````````````````
+
+To target quantum kernel code for execution in Amazon Braket,
+pass the flag ``--target braket`` to the ``nvq++`` compiler.
+By default jobs are submitted to the state vector simulator, `SV1`.
+
+.. code:: bash
+
+    nvq++ --target braket src.cpp
+
+
+To execute your kernels on different device, pass the ``--braket-machine`` flag to the ``nvq++`` compiler
+to specify which machine to submit quantum kernels to:
+
+.. code:: bash
+
+    nvq++ --target braket --braket-machine "arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet" src.cpp ...
+
+where ``arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet`` refers to IQM Garnet QPU.
+
+To emulate the device locally, without submitting through the cloud,
+you can also pass the ``--emulate`` flag to ``nvq++``. 
+
+.. code:: bash
+
+    nvq++ --emulate --target braket src.cpp
+
+To see a complete example for using Amazon Braket backends, take a look at our :doc:`C++ examples <../examples/examples>`.
+
+Submission from Python
+`````````````````````````
+
+The target to which quantum kernels are submitted 
+can be controlled with the ``cudaq::set_target()`` function.
+
+.. code:: python
+
+    cudaq.set_target("braket")
+
+By default, jobs are submitted to the state vector simulator, `SV1`.
+
+To specify which Amazon Braket device to use, set the :code:`machine` parameter.
+
+.. code:: python
+
+    device_arn = "arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet"
+    cudaq.set_target("braket", machine=device_arn)
+
+where ``arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet`` refers to IQM Garnet QPU.
+
+To emulate the device locally, without submitting through the cloud,
+you can also set the ``emulate`` flag to ``True``.
+
+.. code:: python
+
+    cudaq.set_target("braket", emulate=True)
+
+The number of shots for a kernel execution can be set through the ``shots_count``
+argument to ``cudaq.sample``. By default, the ``shots_count`` is set to 1000.
+
+.. code:: python
+
+    cudaq.sample(kernel, shots_count=100)
+
+To see a complete example for using Amazon Braket backends, take a look at our :doc:`Python examples <../examples/examples>`.
+
+.. note:: 
+
+    The ``cudaq.observe`` API is not yet supported on the `braket` target.
+
+
 IonQ
 ==================================
 
@@ -314,7 +422,7 @@ Setting Credentials
 `````````````````````````
 
 In order to use the OQC devices you will need to register.
-Registration is achieved by contacting [email protected]
+Registration is achieved by contacting `[email protected]`.
 
 Once registered you will be able to authenticate with your ``email`` and ``password``