Polish and document convenience features for bloqify, BloqBuilder

docs/bloq_infra.rst

@@ -45,6 +45,8 @@ types (``Register``), and algorithms (``CompositeBloq``).
    :maxdepth: 1
    :caption: Advanced Topics:
 
+   bloqify_syntax/bloqify-syntactic-sugar.ipynb
+   bloqify_syntax/bloq-builder-gate-helpers.ipynb
    _infra/Bloqs-Tutorial.ipynb
    _infra/composite_bloq.ipynb
    cirq_interop/cirq_interop.ipynb

qualtran/__init__.py

@@ -85,7 +85,7 @@
 # Internal imports: none
 # External:
 #  - numpy: multiplying bitsizes, making cirq quregs
-from ._infra.registers import Register, Signature, Side
+from ._infra.registers import Register, Signature, Side, qsig
 
 # Internal imports: none
 # External imports: none
@@ -105,6 +105,8 @@
 
 from ._infra.bloq_example import BloqExample, bloq_example, BloqDocSpec
 
+from .drawing._show_funcs import show_bloq
+
 from .bloqify_syntax import bloqify
 
 # --------------------------------------------------------------------------------------------------

qualtran/_infra/bloq.py

@@ -65,7 +65,9 @@
 def _decompose_from_build_composite_bloq(bloq: 'Bloq') -> 'CompositeBloq':
     from qualtran import BloqBuilder
 
-    bb, initial_soqs = BloqBuilder.from_signature(bloq.signature, add_registers_allowed=False)
+    bb, initial_soqs = BloqBuilder.from_signature(
+        bloq.signature, add_registers_allowed=False, bloq_key=bloq.__class__.__name__
+    )
     out_soqs = bloq.build_composite_bloq(bb=bb, **initial_soqs)
     if not isinstance(out_soqs, dict):
         raise ValueError(
@@ -692,6 +694,11 @@ def wire_symbol(
 
         return directional_text_box(text=pretty_str, side=reg.side)
 
+    def draw(self, type: str = 'graph'):  # pylint: disable=redefined-builtin
+        from qualtran.drawing import show_bloq
+
+        return show_bloq(self, type=type)
+
     def __str__(self):
         return self.__class__.__name__
 
@@ -703,7 +710,7 @@ def _pkg_(cls) -> str:
     def _class_name_in_pkg_(cls) -> str:
         """The bloq class's name with its package.
 
-        The Qualtran standard library contains a heirarchy of packages under
+        The Qualtran standard library contains a hierarchy of packages under
         `qualtran.bloqs.*`. Each bloq class is defined in a module (i.e. the
         "*.py" file) and re-exported one level up.
         """

qualtran/_infra/quantum_graph.py

@@ -174,6 +174,11 @@ def reg(self) -> 'Register':
     def __hash__(self):
         raise TypeError("QVar objects during bloq building are *not* hashable.")
 
+    def __str__(self) -> str:
+        if self.ssa_name is not None:
+            return self.ssa_name
+        return str(self.soquet)
+
     def __getitem__(self, item):
         if self._split_components is None:
             self._split_components = self.bb.split(self)

qualtran/_infra/registers.py

@@ -113,7 +113,9 @@ def shape_symbolic(self) -> Tuple[SymbolicInt, ...]:
     @property
     def shape(self) -> Tuple[int, ...]:
         if is_symbolic(*self._shape):
-            raise ValueError(f"{self} is symbolic. Cannot get real-valued shape.")
+            raise ValueError(
+                f"{self.name}'s shape {self._shape} is symbolic. Cannot get real-valued shape."
+            )
         return cast(Tuple[int, ...], self._shape)
 
     @property
@@ -452,3 +454,7 @@ def __hash__(self):
 
     def __eq__(self, other) -> bool:
         return self._registers == other._registers
+
+
+def qsig(*args, **kwargs) -> Signature:
+    return Signature.build(*args, **kwargs)

qualtran/bloqify_syntax/_infra_test.py

@@ -17,6 +17,7 @@
 import pytest
 
 import qualtran as qlt
+import qualtran.testing as qlt_testing
 from qualtran import BloqBuilder, QVar
 
 
@@ -113,3 +114,13 @@ def test_bloqify_missing_bb():
         @qlt.bloqify  # type: ignore[arg-type]
         def no_bb_func(x: 'QVar'):
             return {'x': x}
+
+
+@pytest.mark.notebook
+def test_bloqify_notebook():
+    qlt_testing.execute_notebook('bloqify-syntactic-sugar')
+
+
+@pytest.mark.notebook
+def test_bb_helper_notebook():
+    qlt_testing.execute_notebook('bloq-builder-gate-helpers')

qualtran/bloqify_syntax/bloq-builder-gate-helpers.ipynb

@@ -0,0 +1,251 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "5b8c9ba4-3032-4984-8a34-750a7ccac823",
+   "metadata": {},
+   "source": [
+    "# BloqBuilder Gate Helper Methods\n",
+    "\n",
+    "For convenience, `qualtran.BloqBuilder` has methods for adding (\"calling\") common basic gates to your program. Each method maps 1-to-1 to a bloq class, particularly the `.qcall(...)` class method. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "551dfef2-3cb0-4db1-bc03-57e97bb2c609",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Top-level qualtran imports\n",
+    "import qualtran as qlt\n",
+    "import qualtran.dtype as qdt"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6877a5ac-3fc9-4f5f-8738-1afaf689a6fb",
+   "metadata": {},
+   "source": [
+    "### Single qubit gates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "77f77416-0a1a-478f-9ab2-b5c2b90cb9fb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "q = bb.in_register('q', qdt.QBit())\n",
+    "\n",
+    "q = bb.X(q)\n",
+    "q = bb.Y(q)\n",
+    "q = bb.Z(q)\n",
+    "q = bb.H(q)\n",
+    "q = bb.T(q)\n",
+    "q = bb.T(q, is_adjoint=True)\n",
+    "q = bb.S(q)\n",
+    "q = bb.S(q, is_adjoint=True)\n",
+    "q = bb.identity(q)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize(q=q))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bf7ffb5a-d0fb-499d-acd0-f5008a56dc75",
+   "metadata": {},
+   "source": [
+    "### Two qubit gates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1d295b5d-a2cd-47bd-92b6-6afb6ad72563",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "q1 = bb.in_register('q1', qdt.QBit())\n",
+    "q2 = bb.in_register('q2', qdt.QBit())\n",
+    "\n",
+    "q1, q2 = bb.CNOT(q1, q2)\n",
+    "q1, q2 = bb.CZ(q1, q2)\n",
+    "q1, q2 = bb.CY(q1, q2)\n",
+    "q1, q2 = bb.CH(q1, q2)\n",
+    "q1, q2 = bb.swap(q1, q2)\n",
+    "[q1, q2], anc = bb.And([q1, q2])\n",
+    "[q1, q2] = bb.UnAnd([q1, q2], anc)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize(q1=q1, q2=q2))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "71f7f4e1-5f30-43ce-ad77-51c405cc5692",
+   "metadata": {},
+   "source": [
+    "### Three qubit gates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2773c4fd-a65b-4ccb-9005-247db189e81e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "q1 = bb.in_register('q1', qdt.QBit())\n",
+    "q2 = bb.in_register('q2', qdt.QBit())\n",
+    "q3 = bb.in_register('q3', qdt.QBit())\n",
+    "\n",
+    "q1, q2, q3 = bb.Toffoli(q1, q2, q3)\n",
+    "q1, q2, q3 = bb.cswap(q1, q2, q3)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize(q1=q1, q2=q2, q3=q3))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aec6346b-5241-4850-940f-7aa15c7a5cea",
+   "metadata": {},
+   "source": [
+    "### Rotations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "309bf03a-e83c-476a-9778-0149b9d7a481",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "q1 = bb.in_register('q1', qdt.QBit())\n",
+    "q2 = bb.in_register('q2', qdt.QBit())\n",
+    "\n",
+    "q1 = bb.rx(q1, 0.1)\n",
+    "q1 = bb.ry(q1, 0.2)\n",
+    "q1 = bb.rz(q1, 0.3)\n",
+    "q1, q2 = bb.cry(q1, q2, 0.4)\n",
+    "q1, q2 = bb.crz(q1, q2, 0.5)\n",
+    "q1 = bb.su2_rotation(q1, theta=0.1, phi=0.2, lambd=0.3)\n",
+    "q1 = bb.z_pow(q1, exponent=0.6)\n",
+    "q1, q2 = bb.cz_pow(q1, q2, exponent=0.7)\n",
+    "q1 = bb.x_pow(q1, exponent=0.8)\n",
+    "q1 = bb.y_pow(q1, exponent=0.9)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize(q1=q1, q2=q2))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6eb498c3-474d-444f-9b7c-118c1c7ffb19",
+   "metadata": {},
+   "source": [
+    "### Measurement and discard"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "96d6094f-9bc5-49ce-8862-db4b657ec1b0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "q1 = bb.in_register('q1', qdt.QBit())\n",
+    "q2 = bb.in_register('q2', qdt.QBit())\n",
+    "\n",
+    "c1 = bb.measure_x(q1)\n",
+    "c2 = bb.measure_z(q2)\n",
+    "\n",
+    "bb.discard(c1)\n",
+    "bb.discard(c2)\n",
+    "\n",
+    "q3 = bb.alloc_qbit()\n",
+    "bb.discard_q(q3)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7b45cbe0-3cba-4fd5-8978-87b7caddf456",
+   "metadata": {},
+   "source": [
+    "### Allocations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0709526a-d696-41ee-b52c-cf7a580891bd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "\n",
+    "q = bb.alloc_qbit(0)\n",
+    "bb.free_qbit(q, 0)\n",
+    "\n",
+    "x = bb.alloc_qint(55, bitsize=8)\n",
+    "bb.free(x)\n",
+    "\n",
+    "y = bb.allocate(3)\n",
+    "bb.free(y)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "45faf54e-cf0b-458e-9073-f6938b888de9",
+   "metadata": {},
+   "source": [
+    "### Bookkeeping"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "32a49f87-a497-45c7-8e2a-9aac55d28f97",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bb = qlt.BloqBuilder()\n",
+    "x = bb.in_register('x', qdt.QAny(3))\n",
+    "\n",
+    "xs = bb.split(x)\n",
+    "x = bb.join(xs)\n",
+    "\n",
+    "qlt.show_bloq(bb.finalize(x=x))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}