Docs preview for PR #2023.

pr-2023/_sources/api/default_ops.rst.txt

@@ -541,4 +541,95 @@ This is a non-linear transformation, and no template overloads are available.
     .. code-block:: cpp
 
         cudaq::qubit qubit;
-        my(qubit);
+        my(qubit);
+
+
+User-Defined Custom Operations
+==============================
+
+Users can define a custom quantum operation by its unitary matrix. First use 
+the API to register a custom operation, outside of a CUDA-Q kernel. Then the 
+operation can be used within a CUDA-Q kernel like any of the built-in operations
+defined above.
+Custom operations are supported on qubits only (`qudit` with `level = 2`).
+
+.. tab:: Python
+
+    The :code:`cudaq.register_operation` API accepts an identifier string for 
+    the custom operation and its unitary matrix. The matrix can be a `list` or
+    `numpy` array of complex numbers. A 1D matrix is interpreted as row-major.
+
+
+    .. code-block:: python
+
+        import cudaq
+        import numpy as np
+
+        cudaq.register_operation("custom_h", 1. / np.sqrt(2.) * np.array([1, 1, 1, -1]))
+
+        cudaq.register_operation("custom_x", np.array([0, 1, 1, 0]))
+
+        @cudaq.kernel
+        def bell():
+            qubits = cudaq.qvector(2)
+            custom_h(qubits[0])
+            custom_x.ctrl(qubits[0], qubits[1])
+
+        cudaq.sample(bell).dump()
+
+        
+.. tab:: C++
+
+    The macro :code:`CUDAQ_REGISTER_OPERATION` accepts a unique name for the 
+    operation, the number of target qubits, the number of rotation parameters 
+    (can be 0), and the unitary matrix as a 1D row-major `std::vector<complex>` 
+    representation.
+
+    .. code-block:: cpp
+
+        #include <cudaq.h>
+
+        CUDAQ_REGISTER_OPERATION(custom_h, 1, 0,
+                                {M_SQRT1_2, M_SQRT1_2, M_SQRT1_2, -M_SQRT1_2})
+
+        CUDAQ_REGISTER_OPERATION(custom_x, 1, 0, {0, 1, 1, 0})
+
+        __qpu__ void bell_pair() {
+            cudaq::qubit q, r;
+            custom_h(q);
+            custom_x<cudaq::ctrl>(q, r);
+        }
+
+        int main() {
+            auto counts = cudaq::sample(bell_pair);
+            for (auto &[bits, count] : counts) {
+                printf("%s\n", bits.data());
+            }
+        }
+
+
+For multi-qubit operations, the matrix is interpreted with MSB qubit ordering,
+i.e. big-endian convention. The following example shows two different custom
+operations, each operating on 2 qubits.
+
+
+.. tab:: Python
+
+    .. literalinclude:: ../snippets/python/using/examples/two_qubit_custom_op.py
+      :language: python
+      :start-after: [Begin Docs]
+      :end-before: [End Docs]
+
+
+.. tab:: C++
+
+    .. literalinclude:: ../snippets/cpp/using/two_qubit_custom_op.cpp
+      :language: cpp
+      :start-after: [Begin Docs]
+      :end-before: [End Docs]
+
+
+.. note:: 
+
+  Custom operations are currently supported only on :doc:`../using/backends/simulators`.
+  Attempt to use with a hardware backend will result in runtime error.

pr-2023/_sources/examples/python/tutorials/readout_error_mitigation.ipynb.txt

@@ -7,7 +7,7 @@
    "source": [
     "# Readout Error Mitigation\n",
     "\n",
-    "Readout errors are caused by imperfect qubit measurement and are a common source of error in quantum computing. Properly modelling these errors in simulation can give the user tools to understand better how these errors are and how to mitigate them when running on actual quantum devices.\n",
+    "Readout errors are caused by imperfect qubit measurement and are a common source of error in quantum computing. Properly modelling these errors in simulation can give the user tools to understand better what these errors are and how to mitigate them when running on actual quantum devices.\n",
     "\n",
     "Readout errors can be mitigated with a confusion matrix $A$. It is a square matrix of size $2^n \\times 2^n$ and tells about the probability of observing the state $|y\\rangle$ given the true state $|x\\rangle$. The confusion matrix characterizes the readout error of the device and is circuit-independent. Once $A$ is estimated, we can compute its pseudoinverse $A^+$ which can be applied to the noisy probability distribution $p_{\\text{noisy}}$ to obtain an adjusted quasi-probability distribution \n",
     "\n",
@@ -18,7 +18,7 @@
     "In this tutorial, we show how to build a confusion matrix with the following approaches.\n",
     "\n",
     "- Using a  single qubit model\n",
-    "- using $k$ local confusion matrices\n",
+    "- Using $k$ local confusion matrices\n",
     "- A full confusion matrix for each $2^n$ combination\n",
     "\n",
     "The last method works well for correcting correlated errors (which affect multiple qubits together). However, it becomes impractical for large numbers of qubits."
@@ -73,7 +73,7 @@
     "To model the readout error, we apply a bitflip channel on every qubit at the end of the circuit using an Identity gate. The probability of bitflip `probs` can be the same or different for all the qubits.\n",
     "\n",
     "<div class=\"alert alert-block alert-success\"><b>Note: </b>\n",
-    "In principle, readout error is applied to the measurement gate but we use Identity gate as adding a quantum error on the measurement gate is not yet supported. Also, the Identity gate is not present in the <kbd>add_channel</kbd> method, so we model the Identity gate using a rotation gate with an angle of 0.0.\n",
+    "In principle, readout error is applied to the measurement gate but we use the Identity gate because adding a quantum error on the measurement gate is not yet supported. Also, the Identity gate is not present in the <kbd>add_channel</kbd> method, so we model the Identity gate using a rotation gate with an angle of 0.0.\n",
     "</div>"
    ]
   },
@@ -114,7 +114,7 @@
    "id": "bb4c7a14-1c0c-4fab-a6aa-7174c23baa7f",
    "metadata": {},
    "source": [
-    "We define a cudaq kernel which will help create a set of quantum circuits to take measurements of the basis states for $n$ qubits. It takes the number of qubits and the basis state as arguments."
+    "We define a cudaq kernel which will help create a set of quantum circuits to take measurements of the basis states for $n$ qubits. The kernel takes the number of qubits and the basis state as arguments."
    ]
   },
   {
@@ -141,7 +141,7 @@
    "id": "95411463-cd1e-499f-baef-d624acc0122c",
    "metadata": {},
    "source": [
-    "For the tutorial, we will use GHZ state on three qubits for testing readout error mitigation. The GHZ state on 3 qubits is described as:\n",
+    "For the tutorial, we will use the GHZ state on three qubits to test readout error mitigation. The GHZ state on 3 qubits is described as:\n",
     "\n",
     "$$\n",
     "\\frac{|000\\rangle + |111\\rangle}{\\sqrt{2}}\n",
@@ -163,7 +163,7 @@
     "    for i in range(n_qubits - 1):\n",
     "        cx(qvector[i], qvector[i + 1])\n",
     "\n",
-    "    # Apply id gates for readout error mitigation\n",
+    "    # Apply identity gates for readout error mitigation\n",
     "    for i in range(n_qubits):\n",
     "        rx(0.0, qvector[i])\n",
     "\n",
@@ -199,7 +199,7 @@
    "id": "032f6898-c953-4d30-a2bf-e8b46ee77c62",
    "metadata": {},
    "source": [
-    "It is possible that the adjusted quasi-probability distribution $p_{\\text{mitigated}}$ obtained by application of $A^+$ to $p_{\\text{noisy}}$ can be possibly non-positive. We need to find the closest positive probability distribution in such a case.\n",
+    "It is possible that the adjusted quasi-probability distribution $p_{\\text{mitigated}}$ obtained by application of $A^+$ to $p_{\\text{noisy}}$ may be non-positive. We need to find the closest positive probability distribution in such a case.\n",
     "\n",
     " $$ p'' = \\min_{p_{\\rm positive}} \\|p_{\\rm noisy} - p_{\\rm positive}\\|_1$$\n",
     "\n",
@@ -393,7 +393,7 @@
    "source": [
     "## Inverse confusion matrix from single-qubit noise model\n",
     "\n",
-    "Here we assume that the readout error of each qubit is independent and with the same confusion probabilities. Then, the confusion matrix $A_1$ for a single qubit can be defined as\n",
+    "Here we assume that the readout error of each qubit is independent with the same confusion probabilities. Then, the confusion matrix $A_1$ for a single qubit can be defined as\n",
     "\n",
     "$$\n",
     "A_1 = \\begin{bmatrix}\n",
@@ -402,7 +402,7 @@
     "\\end{bmatrix}\n",
     "$$\n",
     "\n",
-    "where $P(y|x)$ is the probability of observing state $|y\\rangle$ when measuring true state $|x\\rangle$. Using $A_1$ the full $2^n \\times 2^n$ confusion matrix $A$ can be written as \n",
+    "where $P(y|x)$ is the probability of observing state $|y\\rangle$ when measuring the true state $|x\\rangle$. Using $A_1$, the full $2^n \\times 2^n$ confusion matrix $A$ can be written as \n",
     "\n",
     "$$\n",
     "A = A_1 \\otimes \\dots \\otimes A_1\n",
@@ -719,7 +719,7 @@
    "source": [
     "## Inverse of full confusion matrix\n",
     "\n",
-    "Here we generate a quantum circuit for each of the basis states of $n$ qubits i.e. $2^n$ combinations. This gives more accurate readout error mitigation. Since it scales exponentially with the number of qubits, it is only practical for small devices."
+    "Here we generate a quantum circuit for each of the basis states of $n$ qubits (i.e., $2^n$ combinations). This gives more accurate readout error mitigation. Since it scales exponentially with the number of qubits, it is only practical for small devices."
    ]
   },
   {