Doc improvements for walk operator

dev_tools/autogenerate-bloqs-notebooks-v2.py

@@ -91,6 +91,7 @@
 import qualtran.bloqs.reflection
 import qualtran.bloqs.rotations.phasing_via_cost_function
 import qualtran.bloqs.rotations.quantum_variable_rotation
+import qualtran.bloqs.select_and_prepare
 import qualtran.bloqs.state_preparation.prepare_uniform_superposition
 import qualtran.bloqs.state_preparation.state_preparation_alias_sampling
 import qualtran.bloqs.swap_network.cswap_approx
@@ -455,7 +456,11 @@
     NotebookSpecV2(
         title='Qubitization Walk Operator',
         module=qualtran.bloqs.qubitization_walk_operator,
-        bloq_specs=[qualtran.bloqs.qubitization_walk_operator._QUBITIZATION_WALK_DOC],
+        bloq_specs=[
+            qualtran.bloqs.qubitization_walk_operator._QUBITIZATION_WALK_DOC,
+            qualtran.bloqs.select_and_prepare._SELECT_ORACLE_DOC,
+            qualtran.bloqs.select_and_prepare._PREPARE_ORACLE_DOC,
+        ],
     ),
     NotebookSpecV2(
         title='Qubitization Phase Estimation',

qualtran/bloqs/hubbard_model.ipynb

@@ -38,7 +38,7 @@
     "operations can be combined into a quantum walk, please see\n",
     "[Qubitization Walk Operator](./qubitization_walk_operator.ipynb).\n",
     "\n",
-    "In these operators, our selection register has indices\n",
+    "With these operators, our selection register has indices\n",
     "for $p$, $\\alpha$, $q$, and $\\beta$ as well as two indicator bits $U$ and $V$. There are four cases\n",
     "considered in both the PREPARE and SELECT operations corresponding to the terms in the Hamiltonian:\n",
     "\n",

qualtran/bloqs/qubitization_walk_operator.ipynb

@@ -7,7 +7,21 @@
     "cq.autogen": "title_cell"
    },
    "source": [
-    "# Qubitization Walk Operator"
+    "# Qubitization Walk Operator\n",
+    "\n",
+    "Bloqs for constructing quantum walks from Select and Prepare operators.\n",
+    "\n",
+    "The spectrum of a quantum Hamiltonian can be encoded in the spectrum of a quantum \"walk\"\n",
+    "operator. The Prepare and Select subroutines are carefully designed so that the Hamiltonian\n",
+    "$H$ is encoded as a projection of Select onto the state prepared by Prepare:\n",
+    "\n",
+    "$$\n",
+    "\\mathrm{PREPARE}|0\\rangle = |\\mathcal{L}\\rangle \\\\\n",
+    "(\\langle \\mathcal{L} | \\otimes \\mathbb{1}) \\mathrm{SELECT} (|\\mathcal{L} \\rangle \\otimes \\mathbb{1}) = H / \\lambda\n",
+    "$$.\n",
+    "\n",
+    "We first document the SelectOracle and PrepareOracle abstract base bloqs, and then show\n",
+    "how they can be combined in `QubitizationWalkOperator`."
    ]
   },
   {
@@ -28,6 +42,78 @@
     "import cirq"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "399690ef",
+   "metadata": {
+    "cq.autogen": "SelectOracle.bloq_doc.md"
+   },
+   "source": [
+    "## `SelectOracle`\n",
+    "Abstract base class that defines the interface for a SELECT Oracle.\n",
+    "\n",
+    "The action of a SELECT oracle on a selection register $|l\\rangle$ and target register\n",
+    "$|\\Psi\\rangle$ can be defined as:\n",
+    "\n",
+    "$$\n",
+    "    \\mathrm{SELECT} = \\sum_{l}|l \\rangle \\langle l| \\otimes U_l\n",
+    "$$\n",
+    "\n",
+    "In other words, the `SELECT` oracle applies $l$'th unitary $U_l$ on the target register\n",
+    "$|\\Psi\\rangle$ when the selection register stores integer $l$.\n",
+    "\n",
+    "$$\n",
+    "    \\mathrm{SELECT}|l\\rangle |\\Psi\\rangle = |l\\rangle U_{l}|\\Psi\\rangle\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b2bae756",
+   "metadata": {
+    "cq.autogen": "SelectOracle.bloq_doc.py"
+   },
+   "outputs": [],
+   "source": [
+    "from qualtran.bloqs.select_and_prepare import SelectOracle"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "774308d5",
+   "metadata": {
+    "cq.autogen": "PrepareOracle.bloq_doc.md"
+   },
+   "source": [
+    "## `PrepareOracle`\n",
+    "Abstract base class that defines the API for a PREPARE Oracle.\n",
+    "\n",
+    "Given a set of coefficients $\\{c_0, c_1, ..., c_{l - 1}\\}$, the PREPARE oracle is used to encode\n",
+    "the coefficients as amplitudes of a state $|\\Psi\\rangle = \\sum_{i=0}^{N-1} \\sqrt{\\frac{c_{i}}{\\lambda}} |i\\rangle$\n",
+    "where $\\lambda = \\sum_i |c_i|$, using a selection register $|i\\rangle$. In order to prepare such\n",
+    "a state, the PREPARE circuit is also allowed to use a junk register that is entangled with\n",
+    "selection register.\n",
+    "\n",
+    "Thus, the action of a PREPARE circuit on an input state $|0\\rangle$ can be defined as:\n",
+    "\n",
+    "$$\n",
+    "    \\mathrm{PREPARE} |0\\rangle = \\sum_{i=0}^{N-1} \\sqrt{ \\frac{c_{i}}{\\lambda} } |i\\rangle |\\mathrm{junk}_{i}\\rangle\n",
+    "$$"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bba5bab6",
+   "metadata": {
+    "cq.autogen": "PrepareOracle.bloq_doc.py"
+   },
+   "outputs": [],
+   "source": [
+    "from qualtran.bloqs.select_and_prepare import PrepareOracle"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "229ba8d6",
@@ -36,25 +122,29 @@
    },
    "source": [
     "## `QubitizationWalkOperator`\n",
-    "Constructs a Szegedy Quantum Walk operator using LCU oracles SELECT and PREPARE.\n",
+    "Construct a Szegedy Quantum Walk operator using LCU oracles SELECT and PREPARE.\n",
     "\n",
-    "For a Hamiltonian $H = \\sum_l w_l H_l$ (s.t. $w_l > 0$ and $H_l$ are unitaries),\n",
-    "Constructs a Szegedy quantum walk operator $W = R_{L} . SELECT$, which is a product of\n",
-    "two reflections $R_{L} = (2|L><L| - I)$ and $SELECT=\\sum_{l}|l><l|H_{l}$.\n",
+    "For a Hamiltonian $H = \\sum_l w_l H_l$ (where coefficients $w_l > 0$ and $H_l$ are unitaries),\n",
+    "This bloq constructs a Szegedy quantum walk operator $W = R_{L} \\cdot \\mathrm{SELECT}$,\n",
+    "which is a product of two reflections:\n",
+    " - $R_L = (2|L\\rangle\\langle L| - I)$ and\n",
+    " - $\\mathrm{SELECT}=\\sum_l |l\\rangle\\langle l|H_l$.\n",
     "\n",
     "The action of $W$ partitions the Hilbert space into a direct sum of two-dimensional irreducible\n",
-    "    vector spaces. For an arbitrary eigenstate $|k>$ of $H$ with eigenvalue $E_k$, $|\\ell>|k>$ and\n",
-    "an orthogonal state $\\phi_{k}$ span the irreducible two-dimensional space that $|\\ell>|k>$ is\n",
-    "in under the action of $W$. In this space, $W$ implements a Pauli-Y rotation by an angle of\n",
-    "$-2arccos(E_{k} / \\lambda)$ s.t. $W = e^{i arccos(E_k / \\lambda) Y}$,\n",
-    "where $\\lambda = \\sum_l w_l$.\n",
+    "vector spaces giving it the name \"qubitization\".\n",
+    "For an arbitrary eigenstate $|k\\rangle$ of $H$ with eigenvalue $E_k$,\n",
+    "the two-dimensional space is spanned by $|L\\rangle|k\\rangle$ and\n",
+    "an orthogonal state $\\phi_k$. In this space, $W$ implements a Pauli-Y rotation by an angle of\n",
+    "$-2\\arccos(E_k / \\lambda)$ where $\\lambda = \\sum_l w_l$. That is,\n",
+    "$W = e^{i \\arccos(E_k / \\lambda) Y}$.\n",
     "\n",
-    "Thus, the walk operator $W$ encodes the spectrum of $H$ as a function of eigenphases of $W$\n",
-    "s.t. $spectrum(H) = \\lambda cos(\\arg(\\mathrm{spectrum}(W)))$ where $\\arg(e^{i\\phi}) = \\phi$.\n",
+    "Thus, the walk operator $W$ encodes the spectrum of $H$ as a function of eigenphases of $W$,\n",
+    "specifically $\\mathrm{spectrum}(H) = \\lambda \\cos(\\arg(\\mathrm{spectrum}(W)))$\n",
+    "where $\\arg(e^{i\\phi}) = \\phi$.\n",
     "\n",
     "#### Parameters\n",
     " - `select`: The SELECT lcu gate implementing $\\mathrm{SELECT}=\\sum_{l}|l\\rangle\\langle l|H_{l}$.\n",
-    " - `prepare`: Then PREPARE lcu gate implementing $\\mathrm{PREPARE}|00...00\\rangle = \\sum_{l=0}^{L - 1}\\sqrt{\\frac{w_{l}}{\\lambda}} |l\\rangle = |\\ell\\rangle$\n",
+    " - `prepare`: Then PREPARE lcu gate implementing $\\mathrm{PREPARE}|0\\dots 0\\rangle = \\sum_l \\sqrt{\\frac{w_{l}}{\\lambda}} |l\\rangle = |L\\rangle$\n",
     " - `control_val`: If 0/1, a controlled version of the walk operator is constructed. Defaults to None, in which case the resulting walk operator is not controlled. \n",
     "\n",
     "#### References\n",
@@ -204,12 +294,21 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,

qualtran/bloqs/qubitization_walk_operator.py

@@ -12,6 +12,21 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+r"""Bloqs for constructing quantum walks from Select and Prepare operators.
+
+The spectrum of a quantum Hamiltonian can be encoded in the spectrum of a quantum "walk"
+operator. The Prepare and Select subroutines are carefully designed so that the Hamiltonian
+$H$ is encoded as a projection of Select onto the state prepared by Prepare:
+
+$$
+\mathrm{PREPARE}|0\rangle = |\mathcal{L}\rangle \\
+(\langle \mathcal{L} | \otimes \mathbb{1}) \mathrm{SELECT} (|\mathcal{L} \rangle \otimes \mathbb{1}) = H / \lambda
+$$.
+
+We first document the SelectOracle and PrepareOracle abstract base bloqs, and then show
+how they can be combined in `QubitizationWalkOperator`.
+"""
+
 from functools import cached_property
 from typing import Iterator, Optional, Tuple
 
@@ -34,27 +49,31 @@
 
 @attrs.frozen(cache_hash=True)
 class QubitizationWalkOperator(SpecializedSingleQubitControlledGate):
-    r"""Constructs a Szegedy Quantum Walk operator using LCU oracles SELECT and PREPARE.
+    r"""Construct a Szegedy Quantum Walk operator using LCU oracles SELECT and PREPARE.
 
-    For a Hamiltonian $H = \sum_l w_l H_l$ (s.t. $w_l > 0$ and $H_l$ are unitaries),
-    Constructs a Szegedy quantum walk operator $W = R_{L} . SELECT$, which is a product of
-    two reflections $R_{L} = (2|L><L| - I)$ and $SELECT=\sum_{l}|l><l|H_{l}$.
+    For a Hamiltonian $H = \sum_l w_l H_l$ (where coefficients $w_l > 0$ and $H_l$ are unitaries),
+    This bloq constructs a Szegedy quantum walk operator $W = R_{L} \cdot \mathrm{SELECT}$,
+    which is a product of two reflections:
+     - $R_L = (2|L\rangle\langle L| - I)$ and
+     - $\mathrm{SELECT}=\sum_l |l\rangle\langle l|H_l$.
 
     The action of $W$ partitions the Hilbert space into a direct sum of two-dimensional irreducible
-        vector spaces. For an arbitrary eigenstate $|k>$ of $H$ with eigenvalue $E_k$, $|\ell>|k>$ and
-    an orthogonal state $\phi_{k}$ span the irreducible two-dimensional space that $|\ell>|k>$ is
-    in under the action of $W$. In this space, $W$ implements a Pauli-Y rotation by an angle of
-    $-2arccos(E_{k} / \lambda)$ s.t. $W = e^{i arccos(E_k / \lambda) Y}$,
-    where $\lambda = \sum_l w_l$.
+    vector spaces giving it the name "qubitization".
+    For an arbitrary eigenstate $|k\rangle$ of $H$ with eigenvalue $E_k$,
+    the two-dimensional space is spanned by $|L\rangle|k\rangle$ and
+    an orthogonal state $\phi_k$. In this space, $W$ implements a Pauli-Y rotation by an angle of
+    $-2\arccos(E_k / \lambda)$ where $\lambda = \sum_l w_l$. That is,
+    $W = e^{i \arccos(E_k / \lambda) Y}$.
 
-    Thus, the walk operator $W$ encodes the spectrum of $H$ as a function of eigenphases of $W$
-    s.t. $spectrum(H) = \lambda cos(\arg(\mathrm{spectrum}(W)))$ where $\arg(e^{i\phi}) = \phi$.
+    Thus, the walk operator $W$ encodes the spectrum of $H$ as a function of eigenphases of $W$,
+    specifically $\mathrm{spectrum}(H) = \lambda \cos(\arg(\mathrm{spectrum}(W)))$
+    where $\arg(e^{i\phi}) = \phi$.
 
     Args:
         select: The SELECT lcu gate implementing $\mathrm{SELECT}=\sum_{l}|l\rangle\langle l|H_{l}$.
         prepare: Then PREPARE lcu gate implementing
-            $\mathrm{PREPARE}|00...00\rangle = \sum_{l=0}^{L - 1}\sqrt{\frac{w_{l}}{\lambda}}
-            |l\rangle = |\ell\rangle$
+            $\mathrm{PREPARE}|0\dots 0\rangle = \sum_l \sqrt{\frac{w_{l}}{\lambda}}
+            |l\rangle = |L\rangle$
         control_val: If 0/1, a controlled version of the walk operator is constructed. Defaults to
             None, in which case the resulting walk operator is not controlled.
 

qualtran/bloqs/select_and_prepare.py

@@ -16,14 +16,14 @@
 from functools import cached_property
 from typing import Optional, Tuple, TYPE_CHECKING
 
-from qualtran import GateWithRegisters, Register, Signature
+from qualtran import BloqDocSpec, GateWithRegisters, Register, Signature
 
 if TYPE_CHECKING:
     from qualtran.symbolics import SymbolicFloat
 
 
 class SelectOracle(GateWithRegisters):
-    r"""Abstract base class that defines the API for a SELECT Oracle.
+    r"""Abstract base class that defines the interface for a SELECT Oracle.
 
     The action of a SELECT oracle on a selection register $|l\rangle$ and target register
     $|\Psi\rangle$ can be defined as:
@@ -32,7 +32,7 @@ class SelectOracle(GateWithRegisters):
         \mathrm{SELECT} = \sum_{l}|l \rangle \langle l| \otimes U_l
     $$
 
-    In other words, the `SELECT` oracle applies $l$'th unitary $U_{l}$ on the target register
+    In other words, the `SELECT` oracle applies $l$'th unitary $U_l$ on the target register
     $|\Psi\rangle$ when the selection register stores integer $l$.
 
     $$
@@ -62,10 +62,17 @@ def signature(self) -> Signature:
         )
 
 
+_SELECT_ORACLE_DOC = BloqDocSpec(
+    bloq_cls=SelectOracle,
+    import_line='from qualtran.bloqs.select_and_prepare import SelectOracle',
+    examples=[],
+)
+
+
 class PrepareOracle(GateWithRegisters):
     r"""Abstract base class that defines the API for a PREPARE Oracle.
 
-    Given a set of coefficients $\{c_0, c_1, ..., c_{N - 1}\}, the PREPARE oracle is used to encode
+    Given a set of coefficients $\{c_0, c_1, ..., c_{l - 1}\}$, the PREPARE oracle is used to encode
     the coefficients as amplitudes of a state $|\Psi\rangle = \sum_{i=0}^{N-1} \sqrt{\frac{c_{i}}{\lambda}} |i\rangle$
     where $\lambda = \sum_i |c_i|$, using a selection register $|i\rangle$. In order to prepare such
     a state, the PREPARE circuit is also allowed to use a junk register that is entangled with
@@ -74,7 +81,7 @@ class PrepareOracle(GateWithRegisters):
     Thus, the action of a PREPARE circuit on an input state $|0\rangle$ can be defined as:
 
     $$
-        PREPARE |0\rangle = \sum_{i=0}^{N-1} \sqrt{ \frac{c_{i}}{\lambda} } |i\rangle |junk_{i}\rangle
+        \mathrm{PREPARE} |0\rangle = \sum_{i=0}^{N-1} \sqrt{ \frac{c_{i}}{\lambda} } |i\rangle |\mathrm{junk}_{i}\rangle
     $$
     """
 
@@ -98,3 +105,10 @@ def l1_norm_of_coeffs(self) -> Optional['SymbolicFloat']:
         For LCU Hamiltonians, this is usually referred to as $\lambda$ in texts.
         """
         return None
+
+
+_PREPARE_ORACLE_DOC = BloqDocSpec(
+    bloq_cls=PrepareOracle,
+    import_line='from qualtran.bloqs.select_and_prepare import PrepareOracle',
+    examples=[],
+)