Update examples in docs to reflect that qreg and qspan are deprecated (…

…#1040) * Comment updates for C++ examples * Update Python examples var names: qreg --> qvec * Update specification examples to eliminate qreg * Change examples to literalinclude where possible * Add qvector and qview to Doxygen docs * Trivial updates to docs for qvector and qview * Mark qspan and qreg as deprecated in specification * Update Operations and Allocating Quantum Memory sections * Spelling updates (rst)
NVIDIA · Dec 27, 2023 · 100a24b · 100a24b
1 parent e1b8060
commit 100a24b
Show file tree

Hide file tree

Showing 25 changed files with 223 additions and 371 deletions.
diff --git a/.github/workflows/config/spelling_allowlist.txt b/.github/workflows/config/spelling_allowlist.txt
@@ -13,6 +13,7 @@ CUDA
 CuPy
 DGX
 DOI
+Deuteron
 Fourier
 GHCR
 GPU
@@ -83,6 +84,7 @@ canonicalizes
 codebase
 comparator
 comparators
+composability
 composable
 constructible
 controlled
@@ -142,6 +144,7 @@ nullary
 optimizer
 optimizers
 parallelization
+parameterization
 precompute
 precomputed
 prepend
@@ -173,6 +176,7 @@ tablegen
 templated
 toolchain
 unary
+uncompute
 unitaries
 unitary
 unoptimized

diff --git a/docs/sphinx/api/default_ops.rst b/docs/sphinx/api/default_ops.rst
@@ -14,8 +14,9 @@ Operations that implement unitary transformations of the quantum state are templ
 The template argument allows to invoke the adjoint and controlled version of the quantum transformation, see the section on `Adjoint and Controlled Operations`_.
 
 CUDA Quantum additionally provides overloads to support broadcasting of
-single-qubit operations across a register of qubits. 
-For example, :code:`x(cudaq::qreg<>&)` flips the state of each qubit in the provided :code:`cudaq::qreg`. 
+single-qubit operations across a vector of qubits.  For example,
+:code:`x(cudaq::qvector<>&)` flips the state of each qubit in the provided
+:code:`cudaq::qvector`. 
 
 
 Unitary Operations on Qubits

diff --git a/docs/sphinx/api/languages/cpp_api.rst b/docs/sphinx/api/languages/cpp_api.rst
@@ -18,9 +18,15 @@ Quantum
 .. doxygenclass:: cudaq::qreg
     :members:
 
+.. doxygenclass:: cudaq::qvector
+    :members:
+
 .. doxygenclass:: cudaq::qspan
     :members:
 
+.. doxygenclass:: cudaq::qview
+    :members:
+
 .. doxygentypedef:: cudaq::qubit
 
 Common

diff --git a/docs/sphinx/examples/cpp/algorithms/grover.cpp b/docs/sphinx/examples/cpp/algorithms/grover.cpp
@@ -9,11 +9,14 @@ __qpu__ void reflect_about_uniform(cudaq::qview<> q) {
   auto ctrlQubits = q.front(q.size() - 1);
   auto &lastQubit = q.back();
 
-  h(q);
-  x(q);
-  z<cudaq::ctrl>(ctrlQubits, lastQubit);
-  x(q);
-  h(q);
+  // Compute (U) Action (V) produces
+  // U V U::Adjoint
+  cudaq::compute_action(
+      [&]() {
+        h(q);
+        x(q);
+      },
+      [&]() { z<cudaq::ctrl>(ctrlQubits, lastQubit); });
 }
 
 struct run_grover {

diff --git a/docs/sphinx/examples/cpp/basics/cuquantum_backends.cpp b/docs/sphinx/examples/cpp/basics/cuquantum_backends.cpp
@@ -16,7 +16,7 @@
 struct ghz {
   auto operator()(const int N) __qpu__ {
 
-    // Dynamic, vector-like `qreg`
+    // Dynamically sized vector of qubits
     cudaq::qvector q(N);
     h(q[0]);
     for (int i = 0; i < N - 1; i++) {

diff --git a/docs/sphinx/examples/cpp/basics/cutensornet_backends.cpp b/docs/sphinx/examples/cpp/basics/cutensornet_backends.cpp
@@ -18,7 +18,7 @@
 struct ghz {
   auto operator()(const int N) __qpu__ {
 
-    // Dynamic, vector-like `qreg`
+    // Dynamically sized vector of qubits
     cudaq::qvector q(N);
     h(q[0]);
     for (int i = 0; i < N - 1; i++) {

diff --git a/docs/sphinx/examples/cpp/basics/static_kernel.cpp b/docs/sphinx/examples/cpp/basics/static_kernel.cpp
@@ -12,7 +12,7 @@ template <std::size_t N>
 struct ghz {
   auto operator()() __qpu__ {
 
-    // Compile-time, std::array-like `qreg`.
+    // Compile-time sized array like std::array
     cudaq::qarray<N> q;
     h(q[0]);
     for (int i = 0; i < N - 1; i++) {

diff --git a/docs/sphinx/examples/cpp/other/iterative_qpe.cpp b/docs/sphinx/examples/cpp/other/iterative_qpe.cpp
@@ -6,6 +6,7 @@
  * the terms of the Apache License 2.0 which accompanies this distribution.    *
  ******************************************************************************/
 
+// [Begin Documentation]
 // Compile and run with:
 // ```
 // nvq++ iterative_qpe.cpp -o qpe.x && ./qpe.x
@@ -72,3 +73,4 @@ int main() {
 
   return 0;
 }
+// [End Documentation]
diff --git a/docs/sphinx/examples/python/qaoa_maxcut.py b/docs/sphinx/examples/python/qaoa_maxcut.py
@@ -29,23 +29,23 @@
 def kernel_qaoa() -> cudaq.Kernel:
     """QAOA ansatz for Max-Cut"""
     kernel, thetas = cudaq.make_kernel(list)
-    qreg = kernel.qalloc(qubit_count)
+    qvec = kernel.qalloc(qubit_count)
 
     # Create superposition
-    kernel.h(qreg)
+    kernel.h(qvec)
 
     # Loop over the layers
     for i in range(layer_count):
         # Loop over the qubits
         # Problem unitary
         for j in range(qubit_count):
-            kernel.cx(qreg[j], qreg[(j + 1) % qubit_count])
-            kernel.rz(2.0 * thetas[i], qreg[(j + 1) % qubit_count])
-            kernel.cx(qreg[j], qreg[(j + 1) % qubit_count])
+            kernel.cx(qvec[j], qvec[(j + 1) % qubit_count])
+            kernel.rz(2.0 * thetas[i], qvec[(j + 1) % qubit_count])
+            kernel.cx(qvec[j], qvec[(j + 1) % qubit_count])
 
         # Mixer unitary
         for j in range(qubit_count):
-            kernel.rx(2.0 * thetas[i + layer_count], qreg[j])
+            kernel.rx(2.0 * thetas[i + layer_count], qvec[j])
 
     return kernel
 

diff --git a/docs/sphinx/snippets/python/using/cudaq/platform/observe_mqpu.py b/docs/sphinx/snippets/python/using/cudaq/platform/observe_mqpu.py
@@ -16,10 +16,10 @@
 
 # Define spin ansatz.
 kernel, theta = cudaq.make_kernel(float)
-qreg = kernel.qalloc(2)
-kernel.x(qreg[0])
-kernel.ry(theta, qreg[1])
-kernel.cx(qreg[1], qreg[0])
+qvec = kernel.qalloc(2)
+kernel.x(qvec[0])
+kernel.ry(theta, qvec[1])
+kernel.cx(qvec[1], qvec[0])
 # Define spin Hamiltonian.
 hamiltonian = 5.907 - 2.1433 * spin.x(0) * spin.x(1) - 2.1433 * spin.y(
     0) * spin.y(1) + .21829 * spin.z(0) - 6.125 * spin.z(1)

diff --git a/docs/sphinx/snippets/python/using/cudaq/platform/observe_mqpu_mpi.py b/docs/sphinx/snippets/python/using/cudaq/platform/observe_mqpu_mpi.py
@@ -14,10 +14,10 @@
 
 # Define spin ansatz.
 kernel, theta = cudaq.make_kernel(float)
-qreg = kernel.qalloc(2)
-kernel.x(qreg[0])
-kernel.ry(theta, qreg[1])
-kernel.cx(qreg[1], qreg[0])
+qvec = kernel.qalloc(2)
+kernel.x(qvec[0])
+kernel.ry(theta, qvec[1])
+kernel.cx(qvec[1], qvec[0])
 # Define spin Hamiltonian.
 hamiltonian = 5.907 - 2.1433 * spin.x(0) * spin.x(1) - 2.1433 * spin.y(
     0) * spin.y(1) + .21829 * spin.z(0) - 6.125 * spin.z(1)

diff --git a/docs/sphinx/specification/cudaq/algorithmic_primitives.rst b/docs/sphinx/specification/cudaq/algorithmic_primitives.rst
@@ -242,7 +242,7 @@ Here is an example of the utility of the :code:`cudaq::observe` function:
 
     struct ansatz {
       auto operator()(double theta) __qpu__ {
-        cudaq::qreg q(2);
+        cudaq::qarray<2> q;
         x(q[0]);
         ry(theta, q[1]);
         x<cudaq::ctrl>(q[1], q[0]);
@@ -421,7 +421,7 @@ default :code:`std::vector<double>` signature):
 .. code-block:: cpp
 
     auto deuteron_n3_ansatz = [](double x0, double x1) __qpu__ {
-      cudaq::qreg q(3);
+      cudaq::qarray<3> q;
       x(q[0]);
       ry(x0, q[1]);
       ry(x1, q[2]);