Docs preview for PR #2443.

pr-2443/CMakeLists.txt

@@ -1,5 +1,5 @@
 # ============================================================================ #
-# Copyright (c) 2022 - 2024 NVIDIA Corporation & Affiliates.                   #
+# Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                   #
 # All rights reserved.                                                         #
 #                                                                              #
 # This source code and the accompanying materials are made available under     #

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

@@ -650,7 +650,7 @@ defined by the qudit level that represents the qumode. If it is applied to a qum
 where the number of photons is already at the maximum value, the operation has no
 effect.
 
-:math:`U|0\rangle → |1\rangle, U|1\rangle → |2\rangle, U|2\rangle → |3\rangle, \cdots, U|d\rangle → |d\rangle`
+:math:`C|0\rangle → |1\rangle, C|1\rangle → |2\rangle, C|2\rangle → |3\rangle, \cdots, C|d\rangle → |d\rangle`
 where :math:`d` is the qudit level.
 
 .. tab:: Python
@@ -674,7 +674,7 @@ This operation reduces the number of photons in a qumode up to a minimum value o
 0 representing the vacuum state. If it is applied to a qumode where the number of
 photons is already at the minimum value 0, the operation has no effect.
 
-:math:`U|0\rangle → |0\rangle, U|1\rangle → |0\rangle, U|2\rangle → |1\rangle, \cdots, U|d\rangle → |d-1\rangle`
+:math:`A|0\rangle → |0\rangle, A|1\rangle → |0\rangle, A|2\rangle → |1\rangle, \cdots, A|d\rangle → |d-1\rangle`
 where :math:`d` is the qudit level.
 
 .. tab:: Python

pr-2443/_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-2443/_sources/api/languages/python_api.rst.txt

@@ -157,6 +157,8 @@ Data Types
 .. autoclass:: cudaq.operator.cudm_state.CuDensityMatState
     :members:
 
+.. autoclass:: cudaq.operator.helpers.InitialState
+
 .. autofunction:: cudaq.operator.cudm_state.to_cupy_array
 
 .. autoclass:: cudaq::SampleResult

pr-2443/_sources/applications/python/deutschs_algorithm.ipynb.txt

@@ -13,17 +13,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We have a function which takes in a bit and outputs a bit. This can be represented as $f: \\{0,1\\} \\longrightarrow \\{0,1\\}$. \n",
+    "Deutsch's Algorithm is a concise demonstration of the differences in computational complexity between classical and quantum algorithms for certain problems.  For Desutch's algorithm, we begin with a function which takes in a bit and outputs a bit. This can be represented as $f: \\{0,1\\} \\longrightarrow \\{0,1\\}$. \n",
+    "The function $f$ has the property that it either constant or balanced. The goal of Deutsch's Algorithm is to determine whether our given function is constant or whether it is balanced. \n",
     "\n",
-    "The function $f$ has a property; either it is constant or balanced. \n",
+    "A constant function is \"A balanced function is a function such that the outputs are the same regardless of the inputs, i.e., if $f(0) = 0$ then $f(1) = 1$ or if $f(0) = 1$ then $f(1) = 0$.\n\", the outputs are the same regardless of the inputs, i.e., in the case of $f: \\{0,1\\} \\longrightarrow \\{0,1\\}$, there are are two ways in which this can occur: $f(0) = f(1) = 0$ or $f(0) = f(1) = 1$.\n",
     "\n",
-    "If constant, the outputs are the same regardless of the inputs, i.e., $f(0) = f(1) = 0$ or $f(0) = f(1) = 1$.\n",
-    "\n",
-    "If balanced, the ouputs are balanced across their possibilities, i.e,  if $f(0) = 0$ then $f(1) = 1$ or if $f(0) = 1$ then $f(1) = 0$.\n",
-    "\n",
-    "The question we would like to answer is if the function is constant or balanced. \n",
+    "A balanced function is defined such that the ouputs are balanced across their possibilities, i.e., if $f(0) = 0$ then $f(1) = 1$ or if $f(0) = 1$ then $f(1) = 0$.\n",
     " \n",
-    "Classically, if we are given a function $f$, we can solve to find its property via the code below: \n"
+    "Classically, if we are given a function $f: \\{0,1\\} \\longrightarrow \\{0,1\\}$, we can determine if it is constant or balanced by evaluating the function at $0$ and at $1$.  This is carried out in the code below: \n"
    ]
   },
   {
@@ -96,11 +93,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you step through the `if` statements above, one can see that we require 2 calls to the function to determine its property. That is, we have to query $f$ twice.\n",
+    "If you step through the `if` statements above, you may notice that we require 2 calls to the function to determine its property. That is, we have to query $f$ twice.\n",
     "\n",
-    "The claim is that Deutsch's algorithm can solve for this property with 1 function evalulation, demonstrating quantum advantage. \n",
+    "The claim is that Deutsch's Algorithm can determine if a given function is constant or balanced with just 1 function evalulation, demonstrating quantum advantage. \n",
     "\n",
-    "Below we first go through the math and then the implementation in CUDA Quantum. \n",
+    "Below we first outline Deutsch's Algorithm and work through the math to verify that it does as promised. Then, we provide the implementation in CUDA-Q. \n",
     "\n"
    ]
   },
@@ -130,7 +127,7 @@
     "\n",
     "<img src=\"images/oracle.png\"  width=\"300\" height=\"150\">\n",
     "\n",
-    "Suppose we have $f(x): \\{0,1\\} \\longrightarrow \\{0,1\\}$. We can compute this function on a quantum computer using oracles which we treat as black box functions that yield the output with an appropriate sequence of logic gates. \n",
+    "Suppose we have $f(x): \\{0,1\\} \\longrightarrow \\{0,1\\}$. We can compute this function on a quantum computer using oracles which we treat as black box functions that yield the output with an appropriate sequence of logical gates. \n",
     "\n",
     "Above you see an oracle represented as $U_f$ which allows us to transform the state $\\ket{x}\\ket{y}$ into: \n",
     "\n",
@@ -140,7 +137,7 @@
     "\\end{aligned}\n",
     "$$\n",
     "\n",
-    "If $y = 0$, then $U_f\\ket{x}\\ket{y} = U_f\\ket{x}\\ket{0}  =   \\ket{x}\\ket{0 \\oplus f(x)} =  \\ket{x}\\ket{f(x)}$ since $f(x)$ can either be $0/1$ and $0 \\oplus 0 = 0$ and $0 \\oplus 1 = 1$.\n",
+    "If $y = 0$, then $U_f\\ket{x}\\ket{y} = U_f\\ket{x}\\ket{0}  =   \\ket{x}\\ket{0 \\oplus f(x)} =  \\ket{x}\\ket{f(x)}$, since $f(x)$ can either be $0$ or $1$ and $0 \\oplus 0 = 0$ and $0 \\oplus 1 = 1$.\n",
     "\n",
     "This is remarkable because by setting $\\ket{y} = \\ket{0}$, we can extract the value of $f(x)$ by measuring the value of the second qubit. \n",
     " \n",
@@ -213,7 +210,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Deutschs' Algorithm: \n",
+    "## Deutsch's Algorithm: \n",
     "\n",
     "Our aim is to find out if $f: \\{0,1\\} \\longrightarrow \\{0,1\\}$ is a constant or a balanced function? If constant, $f(0) = f(1)$, and if balanced, $f(0) \\neq f(1)$.\n",
     "\n",
@@ -296,18 +293,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/usr/local/lib/python3.10/dist-packages/qutip/__init__.py:66: UserWarning: The new version of Cython, (>= 3.0.0) is not supported.\n",
-      "  warnings.warn(\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "# Import the CUDA-Q package and set the target to run on NVIDIA GPUs.\n",
     "\n",
@@ -391,6 +379,17 @@
     "elif np.array(result)[0] == '1':\n",
     "    print('f(x) is a balanced function')"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This algorithm can be generalized to determine if a $n$-bit function $f:{0,1}^n\\longrightarrow {0,1}$ is constant or a balanced with only $\\frac{n}{2}$ function evaluations, for $n$ even.  A function if balanced if half of the inputs map to $0$ and half map to $1$.  \n",
+    "\n",
+    "Here we must assume that the function that we are given is either constant or balanced since there are $n$-bit functions that are neither constant, nor balanced.  For instance the $2$-bit function $f(b_0,b_1) = \\max(b_0,b_1)$ is neither balanced, nor constant.\n",
+    "\n",
+    "A hint on how you might approach this problem is to first solve the problem for $n=2$ and see if you can then use that approach to handle $n$-bit functions for larger values of $n$."
+   ]
   }
  ],
  "metadata": {

pr-2443/_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."
    ]
   },
   {