Docs preview for PR #2466.

pr-2466/_sources/api/languages/cpp_api.rst.txt

@@ -35,6 +35,14 @@ Common
 .. doxygenclass:: cudaq::observe_result
     :members:
 
+.. doxygenstruct:: cudaq::observe_options
+    :members:
+
+.. doxygenfunction:: cudaq::observe(const observe_options &options, QuantumKernel &&kernel, spin_op H, Args &&...args)
+.. doxygenfunction:: cudaq::observe(std::size_t shots, QuantumKernel &&kernel, spin_op H, Args &&...args)
+.. doxygenfunction:: cudaq::observe(QuantumKernel &&kernel, spin_op H, Args &&...args)
+.. doxygenfunction:: cudaq::observe(QuantumKernel &&kernel, const SpinOpContainer &termList, Args &&...args)
+
 .. doxygenclass:: cudaq::ExecutionContext
     :members:
 
@@ -53,6 +61,13 @@ Common
 .. doxygenclass:: cudaq::sample_result
     :members:
 
+.. doxygenstruct:: cudaq::sample_options
+    :members:
+
+.. doxygenfunction:: cudaq::sample(const sample_options &options, QuantumKernel &&kernel, Args &&...args)
+.. doxygenfunction:: cudaq::sample(std::size_t shots, QuantumKernel &&kernel, Args &&...args)
+.. doxygenfunction:: cudaq::sample(QuantumKernel &&kernel, Args&&... args)
+
 .. doxygenclass:: cudaq::SimulationState
 
 .. doxygenstruct:: cudaq::SimulationState::Tensor
@@ -89,6 +104,8 @@ Common
 
 .. doxygenfunction:: cudaq::draw(QuantumKernel &&kernel, Args&&... args)
 
+.. doxygenfunction:: cudaq::get_state(QuantumKernel &&kernel, Args&&... args)
+
 .. doxygenclass:: cudaq::Resources
 
 .. doxygentypedef:: cudaq::complex_matrix::value_type

pr-2466/_sources/applications/python/digitized_counterdiabatic_qaoa.ipynb.txt

@@ -8,7 +8,7 @@
     "\n",
     "Drugs often work by binding to an active site of a protein, inhibiting or activating its function for some therapeutic purpose. Finding new candidate drugs is extremely difficult. The study of molecular docking helps guide this search and involves the prediction of how strongly a certain ligand (drug) will bind to its target (usually a protein).  \n",
     "\n",
-    "One of the primary challenges to molecular docking arises from the many geometric degrees of freedom present in proteins and ligands, making it difficult to predict the optimal orientation and assess if the drug is a good candidate or not. One solution is to formulate the problem as a mathematical optimization problem where the optimal solution corresponds to the most likely ligand-protein configuration. This optimization problem can be solved on a quantum computer using methods like the Quantum Approximate Optimization Algorithm (QAOA). This tutorial demonstrates how this [paper](https://arxiv.org/pdf/2308.04098) used digitized-counteradiabatic (DC) QAOA to study molecular docking.  This tutorial assumes you have an understanding of QAOA, if not, please see the CUDA-Q MaxCut tutorial found [here](https://nvidia.github.io/cuda-quantum/latest/examples/python/tutorials/qaoa.html)\n",
+    "One of the primary challenges to molecular docking arises from the many geometric degrees of freedom present in proteins and ligands, making it difficult to predict the optimal orientation and assess if the drug is a good candidate or not. One solution is to formulate the problem as a mathematical optimization problem where the optimal solution corresponds to the most likely ligand-protein configuration. This optimization problem can be solved on a quantum computer using methods like the Quantum Approximate Optimization Algorithm (QAOA). This tutorial demonstrates how this [paper](https://arxiv.org/pdf/2308.04098) used digitized-counteradiabatic (DC) QAOA to study molecular docking.  This tutorial assumes you have an understanding of QAOA, if not, please see the CUDA-Q MaxCut tutorial found [here](https://nvidia.github.io/cuda-quantum/latest/applications/python/qaoa.html).\n",
     "\n",
     "The next section provides more detail on the problem setup followed by CUDA-Q implementations below."
    ]
@@ -25,10 +25,10 @@
     "\n",
     "\n",
     "There are 6 key steps:\n",
-    "1.  The experimental protein and ligand structures are determined and used to select pharmacores, or an important chemical group that will govern the chemical interactions,\n",
-    "2. T wo labeled distance graphs (LAGs) of size $N$ and $M$ represent the protein and the ligand, respectively. Each node corresponds to a pharmacore and each edge weight corresponds to the distance between pharmacores.\n",
+    "1.  The experimental protein and ligand structures are determined and used to select pharmacores, or an important chemical group that will govern the chemical interactions.\n",
+    "2. Two labeled distance graphs (LAGs) of size $N$ and $M$ represent the protein and the ligand, respectively. Each node corresponds to a pharmacore and each edge weight corresponds to the distance between pharmacores.\n",
     "3.  A $M*N$ node binding interaction graph (BIG) is created from the LAGs. Each node in the BIG graph corresponds to a pair of pharmacores, one from the ligand and the other from the protein. The existence of edges between nodes in the BIG graph are determined from the LAGs and correspond to interactions that can feesibly coexist. Therefore, cliques in the graph correspond to mutually possible interactions. \n",
-    "4. The problem is mapped to a QAOA circuit and corresponding Hamiltonian, and the ground state solution is determined.\n",
+    "4. The problem is mapped to a QAOA circuit and corresponding Hamiltonian. From there, the ground state solution is determined.\n",
     "5.  The ground state will produce the maximum weighted clique which corresponds to the best (most strongly bound) orientation of the ligand and protein.\n",
     "6.  The predicted docking structure is interpreted from the QAOA result and is used for further analysis.\n"
    ]
@@ -50,16 +50,14 @@
    "source": [
     "import cudaq\n",
     "from cudaq import spin\n",
-    "import numpy as np\n",
-    "\n",
-    "# cudaq.set_target('nvidia')"
+    "import numpy as np\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The block below defines two of the BIG data sets from the paper. The first is a smaller example, but it can be swapped with the commented out example below at your discretion. The weights are specified for each node based on the nature of the ligand and protein pharmacores represented by the node"
+    "The block below defines two of the BIG data sets from the paper. The first is a smaller example, but it can be swapped with the commented out example below at your discretion. The weights are specified for each node based on the nature of the ligand and protein pharmacores represented by the node."
    ]
   },
   {
@@ -77,7 +75,7 @@
     }
    ],
    "source": [
-    "# The two graphs input from the paper\n",
+    "# The two graph inputs from the paper\n",
     "\n",
     "# BIG 1\n",
     "\n",
@@ -113,12 +111,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Next, the Hamiltonian is constructed. \n",
+    "Next, the Hamiltonian is constructed: \n",
     "\n",
     "$$H = \\frac{1}{2}\\sum_{i \\in V}w_i(\\sigma^z_i - 1) + \\frac{P}{4} \\sum_{(i,j) \\notin E, i \\neq j} (\\sigma^z_i -1)(\\sigma^z_j - 1) $$\n",
     "\n",
     "\n",
-    "The first term concerns the vertices and the weights of the given pharmacores.  The second term is a penalty term that penalizes edges of the graph with no interactions.  The penalty $P$ is set by the user and is defined as 6 in the cell above. The function below returns the Hamiltonina as a CUDA-Q `spin_op` object.\n",
+    "The first term concerns the vertices and the weights of the given pharmacores.  The second term is a penalty term that penalizes edges of the graph with no interactions.  The penalty $P$ is set by the user and is defined as 6 in the cell above. The function below returns the Hamiltonian as a CUDA-Q `spin_op` object.\n",
     "\n"
    ]
   },
@@ -208,7 +206,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The kernel below defines a DC-QAOA circuit.  What makes the approach \"DC\" is the inclusion of additional counteradiabatic terms to better drive the optimization to the ground state. These terms are digitized and applied as additional operations following each QAOA layer.  The increase in parameters is hopefully offset by requiring fewer layers. In this example, the DC terms are additional parameterized $Y$ operations applied to each qubit. These can be commented out to run conventional QAOA."
+    "The kernel below defines a DC-QAOA circuit.  What makes the approach \"DC\" is the inclusion of additional counteradiabatic terms to better drive the optimization to the ground state. These terms are digitized and applied as additional operations following each QAOA layer.  The increase in parameters is hopefully offset by requiring fewer layers. In this example, the DC terms are the additional parameterized $Y$ operations applied to each qubit. These can be commented out to run conventional QAOA."
    ]
   },
   {
@@ -246,7 +244,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The classical optimizer for the QAOA procedure can be specified as one of the build in CUDA-Q optimizers, in this case Nelder Mead. The parameter count is defined for DC-QAOA, but can be swapped with the commented line below for conventional QAOA."
+    "The classical optimizer for the QAOA procedure can be specified as one of the built-in CUDA-Q optimizers, in this case Nelder Mead. The parameter count is defined for DC-QAOA, but can be swapped with the commented line below for conventional QAOA."
    ]
   },
   {

pr-2466/_sources/applications/python/hadamard_test.ipynb.txt

@@ -6,14 +6,14 @@
    "source": [
     "# Using the Hadamard Test to Determine Quantum Krylov Subspace Decomposition Matrix Elements\n",
     "\n",
-    "The Hadamard test, is a quantum algorithm for estimating the expectation values and is  a useful subroutine for a number of quantum applications ranging from estimation of molecular ground state energies to quantum semidefinite programming. This tutorial will briefly introduce the Hadamard test, and demonstrate how it can be implemented in CUDA-Q and then parallelized for a Quantum Krylov Subspace Diagonalization application.\n",
+    "The Hadamard test is a quantum algorithm for estimating expectation values and is a useful subroutine for a number of quantum applications ranging from estimation of molecular ground state energies to quantum semidefinite programming. This tutorial will briefly introduce the Hadamard test, demonstrate how it can be implemented in CUDA-Q, and then parallelized for a Quantum Krylov Subspace Diagonalization application.\n",
     "\n",
     "The Hadamard test is performed using a register with an ancilla qubit in the $\\ket{0}$ state and a prepared quantum state $\\ket{\\psi}$, the following circuit can be used to extract the expectation value from measurement of the ancilla.\n",
     "\n",
     "\n",
     "![Htest](./images/htest.png)\n",
     "\n",
-    "The key insight is to note that $$P(0) = \\frac{1}{2} \\left[ I + Re \\bra{\\psi} O \\ket{\\phi} \\right]$$ and $$P(1) = \\frac{1}{2} \\left[ I - Re \\bra{\\psi} O \\ket{\\phi} \\right]$$ so their difference is equal to $$P(0)-P(1) = Re \\bra{\\psi} O \\ket{\\phi}$$\n",
+    "The key insight is that $$P(0) = \\frac{1}{2} \\left[ I + Re \\bra{\\psi} O \\ket{\\phi} \\right]$$ and $$P(1) = \\frac{1}{2} \\left[ I - Re \\bra{\\psi} O \\ket{\\phi} \\right]$$ so their difference is equal to $$P(0)-P(1) = Re \\bra{\\psi} O \\ket{\\phi}.$$\n",
     "\n",
     "\n",
     "More details and a short derivation can be found [here](https://en.wikipedia.org/wiki/Hadamard_test)."
@@ -26,17 +26,17 @@
     "What if you want to perform the Hadamard test to compute an expectation value like $\\bra{\\psi} O \\ket{\\phi}$, where $\\ket{\\psi}$ and $\\ket{\\phi}$ are different states and $O$ is a Pauli Operator? This is a common subroutine for the QKSD, where matrix elements are determined by computing expectation values between different states.\n",
     "\n",
     "Defining $O$ as \n",
-    "$$O = X_1X_2$$\n",
+    "$$O = X_1X_2,$$\n",
     "\n",
     "and given the fact that\n",
-    "$$\\ket{\\psi} = U_{\\psi}\\ket{0} \\qquad \\ket{\\phi} = U_{\\phi}\\ket{0}$$\n",
+    "$$\\ket{\\psi} = U_{\\psi}\\ket{0} \\qquad \\ket{\\phi} = U_{\\phi}\\ket{0},$$\n",
     "\n",
-    "We can combine the state preparation steps into the operator resulting in\n",
-    "$$\\bra{\\psi}O\\ket{\\phi} = \\bra{0}U_\\psi^\\dagger O U_\\phi\\ket{0}$$\n",
-    "Which corresponds to the following circuit\n",
+    "we can combine the state preparation steps into the operator resulting in\n",
+    "$$\\bra{\\psi}O\\ket{\\phi} = \\bra{0}U_\\psi^\\dagger O U_\\phi\\ket{0},$$\n",
+    "which corresponds to the following circuit.\n",
     "![Htest2](./images/htestfactored.png)\n",
     "\n",
-    "By preparing this circuit, and repeatedly measuring the ancilla qubit, allows for estimation of the expectation value as $$P(0)-P(1) = Re \\bra{\\psi} O \\ket{\\phi}$$\n",
+    "By preparing this circuit, and repeatedly measuring the ancilla qubit, we estimate the expectation value as $$P(0)-P(1) = Re \\bra{\\psi} O \\ket{\\phi}.$$\n",
     "\n",
     "\n",
     "The following sections demonstrate how this can be performed in CUDA-Q."
@@ -53,7 +53,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Before performing the Hadamard test, lets determine the exact expectation value by performing the matrix multiplications explicitly. The code below builds two CUDA-Q kernels corresponding to $\\ket{\\psi} = \\frac{1}{\\sqrt{2}}\\begin{pmatrix}1 \\\\ 0 \\\\ 1 \\\\ 0\\end{pmatrix}$ and $\\ket{\\phi} = \\begin{pmatrix}0 \\\\ 1 \\\\ 0 \\\\ 0\\end{pmatrix}$"
+    "Before performing the Hadamard test, let's determine the exact expectation value by performing the matrix multiplications explicitly. The code below builds two CUDA-Q kernels corresponding to $\\ket{\\psi} = \\frac{1}{\\sqrt{2}}\\begin{pmatrix}1 \\\\ 0 \\\\ 1 \\\\ 0\\end{pmatrix}$ and $\\ket{\\phi} = \\begin{pmatrix}0 \\\\ 1 \\\\ 0 \\\\ 0\\end{pmatrix}.$"
    ]
   },
   {
@@ -87,7 +87,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The state vectors can be accessed using the `get_state` command and printed as numpy arrays"
+    "The state vectors can be accessed using the `get_state` command and printed as numpy arrays:"
    ]
   },
   {
@@ -118,7 +118,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The Hamiltonian operator ($O$ in the derivation above) is defined as a CUDA-Q spin operator and converted to a matrix withe the `to_matrix`. The following line of code performs the explicit matrix multiplications to produce the exact expectation value."
+    "The Hamiltonian operator ($O$ in the derivation above) is defined as a CUDA-Q spin operator and converted to a matrix with `to_matrix`. The following line of code performs the explicit matrix multiplications to produce the exact expectation value."
    ]
   },
   {
@@ -208,7 +208,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The CUDA-Q Sample method computes 100000 sample ancilla measurements and uses them to estimate the expectation value. The standard error is provided as well. Try increasing the sample size and note the convergence of the expectation value and the standard error towards the numerical result."
+    "The CUDA-Q `sample` method computes 100000 sample ancilla measurements, and from them we can estimate the expectation value. The standard error is provided as well. Try increasing the sample size and note the convergence of the expectation value and the standard error towards the numerical result."
    ]
   },
   {
@@ -249,9 +249,9 @@
     "\n",
     "![Htest3](./images/QKSD.png)\n",
     "\n",
-    "This method can be easily parallelized and multiple QPUs, if available could compute the matrix elements asynchronously.  The CUDA-Q `mqpu` backend allows you to simulate a computation across multiple simulated QPUs. The code below demonstrates how.\n",
+    "This method can be easily parallelized, and multiple QPUs, if available, could compute the matrix elements asynchronously.  The CUDA-Q `mqpu` backend allows you to simulate a computation across multiple simulated QPUs. The code below demonstrates how.\n",
     "\n",
-    "First, the Hadamard test circuit is defined, but this time the $\\ket{\\psi}$ and $\\ket{\\phi}$ states contain parameterized rotations so that multiple states can be quickly generated for the sake of example."
+    "First, the Hadamard test circuit is defined, but this time the $\\ket{\\psi}$ and $\\ket{\\phi}$ states contain parameterized rotations so that multiple states can be quickly generated, for the sake of example."
    ]
   },
   {
@@ -302,7 +302,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "metadata": {},
    "outputs": [
     {
@@ -314,7 +314,7 @@
     }
    ],
    "source": [
-    "cudaq.set_target(\"nvidia-mqpu\")\n",
+    "cudaq.set_target(\"nvidia\", option=\"mqpu\")\n",
     "\n",
     "target = cudaq.get_target()\n",
     "qpu_count = target.num_qpus()\n",
@@ -354,7 +354,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The four matrix elements are shown below and now be classically processed to produce the eigenvalues."
+    "The four matrix elements are shown below and can be classically processed to produce the eigenvalues."
    ]
   },
   {