Doc system notebook execution: WriteIfDifferent. Misc doc fixes (#1648)

Feature: `jupyter_autogen.py` will only re-write `*.ipynb` files if
there's been a change.
The tool to execute the notebooks is already to set up to only
re-execute notebooks if they're out of date. But every time you re-run
the first autogen script, it will re-up the modification date and
everything will always be re-evaluated, which is expensive.

Misc fixes
- Use a distinct extension for `autotoc.rst.inc`, so sphinx doesn't
treat it as a page and emit warnings about it
 - include missing TOC entries for notebooks
 - fix flaky notebook assertion by using more idiomatic sympy methods
 - grammar and arg docstring fixes in gf_poly

Author: mpharrigan

dev_tools/autogenerate-bloqs-notebooks-v2.py

@@ -65,6 +65,7 @@
     'chemistry/writing_algorithms.ipynb',
     'cryptography/rsa/factoring-via-modexp.ipynb',
     'state_preparation/state_preparation_via_rotation_tutorial.ipynb',
+    'optimization/k_xor_sat/kikuchi_guiding_state_tutorial.ipynb',
 ]
 
 

dev_tools/qualtran_dev_tools/jupyter_autogen.py

@@ -16,6 +16,7 @@
 
 import abc
 import inspect
+import io
 import re
 import textwrap
 from pathlib import Path
@@ -45,7 +46,6 @@
 show_bloq(bloq)\
 """
 
-
 _K_CQ_AUTOGEN = 'cq.autogen'
 """The jupyter metadata key we use to identify cells we've autogenerated.
 
@@ -310,6 +310,84 @@ def _init_notebook(
     return nb, nb_path
 
 
+class WriteIfDifferent:
+    """A file-like object that only writes to disk if the new content
+    differs from the existing content.
+
+    Args:
+        path: The path to write, which may already exist.
+    """
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._buffer = io.StringIO()
+
+    def write(self, s: str):
+        return self._buffer.write(s)
+
+    def writelines(self, lines):
+        for line in lines:
+            self.write(line)
+
+    def flush(self):
+        self._buffer.flush()
+
+    def close(self):
+        """Closes the adapter.
+
+        This triggers the comparison of buffered content
+        with the disk file's content and writes to disk only if different.
+        """
+        new_content = self._buffer.getvalue()
+        self._buffer.close()
+
+        existing_content = None
+        if self.path.is_file():
+            with self.path.open('r') as f_read:
+                existing_content = f_read.read()
+            if new_content == existing_content:
+                print(f"{self.path} unchanged.")
+                return
+
+        with self.path.open('w') as f_write:
+            f_write.write(new_content)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        # Do not suppress exceptions from the 'with' block body.
+        return False
+
+    @property
+    def closed(self):
+        return self._buffer.closed
+
+    def readable(self):
+        """Returns False, as this adapter is write-only like a file from `open('w')`."""
+        return False
+
+    def writable(self):
+        """Returns True if the adapter is not closed, False otherwise."""
+        return self._buffer.writable()
+
+    def seekable(self):
+        """Returns False, as this adapter is not seekable like a disk file opened in 'w' mode."""
+        return False
+
+    def tell(self):
+        """Returns the current stream position in the internal buffer."""
+        return self._buffer.tell()
+
+    def truncate(self, size=None):
+        """
+        Resizes the internal buffer to the given number of bytes.
+        If size is not specified, resizes to the current position.
+        """
+        return self._buffer.truncate(size)
+
+
 def render_notebook(nbspec: NotebookSpecV2) -> None:
     # 1. get a notebook (existing or empty)
     nb, nb_path = _init_notebook(path_stem=nbspec.path_stem, directory=nbspec.directory)
@@ -349,5 +427,5 @@ def render_notebook(nbspec: NotebookSpecV2) -> None:
         nb.cells.append(new_nbnode)
 
     # 5. Write the notebook.
-    with nb_path.open('w') as f:
-        nbformat.write(nb, f)
+    with WriteIfDifferent(nb_path) as woc:
+        nbformat.write(nb, woc)

dev_tools/qualtran_dev_tools/reference_docs.py

@@ -386,7 +386,7 @@ def generate_ref_toc(reporoot: Path):
     for path in page_paths:
         grouped_paths[path.parent].append(path)
 
-    with (output_dir / 'autotoc.rst').open('w') as f:
+    with (output_dir / 'autotoc.rst.inc').open('w') as f:
         write_ref_toc(f, grouped_paths, output_dir)
 
 

docs/.gitignore

@@ -2,7 +2,7 @@
 _build/
 
 # Generated reference toc
-reference/autotoc.rst
+reference/autotoc.rst.inc
 
 # All the generated reference pages
 **/*.md

docs/bloq_infra.rst

@@ -39,6 +39,7 @@ types (``Register``), and algorithms (``CompositeBloq``).
    cirq_interop/t_complexity.ipynb
    qref_interop/bartiq_demo.ipynb
    _infra/gate_with_registers.ipynb
+   bloqs/mcmt/specialized_ctrl.ipynb
    drawing/graphviz.ipynb
    drawing/musical_score.ipynb
    drawing/drawing_call_graph.ipynb

docs/bloqs/index.rst

@@ -21,6 +21,7 @@ Bloqs Library
     chemistry/writing_algorithms.ipynb
     cryptography/rsa/factoring-via-modexp.ipynb
     state_preparation/state_preparation_via_rotation_tutorial.ipynb
+    optimization/k_xor_sat/kikuchi_guiding_state_tutorial.ipynb
 
 .. toctree::
     :maxdepth: 1

docs/reference/index.rst

@@ -12,4 +12,4 @@ in ``qualtran``.
    qualtran.md
 
 
-.. include:: autotoc.rst
+.. include:: autotoc.rst.inc

qualtran/bloqs/chemistry/trotter/hubbard/qpe_cost_optimization.ipynb

@@ -535,9 +535,7 @@
    "source": [
     "# check the symbolic counts match the expected counts\n",
     "t_counts_orig, n_rot = t_and_rot_counts_from_bloq(trotter_step)\n",
-    "# for some reason substituting both at once leads to a precision error\n",
-    "t_counts = t_counts.evalf(subs={s_eps_r: eps_single_rot})\n",
-    "t_counts_symb = t_counts.evalf(subs={s_length: length})\n",
+    "t_counts_symb = t_counts.subs(s_length, length)\n",
     "assert t_counts_orig == t_counts_symb"
    ]
   },
@@ -573,25 +571,26 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "symb_t_count = qpe_cost_symb.evalf(\n",
-    "    subs={\n",
+    "symb_t_count = qpe_cost_symb.subs(\n",
+    "    {\n",
     "        s_length: length,\n",
     "        s_delta_ht: delta_ht,\n",
     "        s_delta_pe: delta_pe,\n",
     "        s_delta_ts: delta_ts,\n",
     "        s_xi: xi_bound,\n",
     "        s_n_rot: n_rot,\n",
-    "    }\n",
-    ")\n",
-    "symb_t_count = symb_t_count.evalf(subs={s_p: prod_ord}, maxn=500)\n",
+    "        s_p: prod_ord,\n",
+    "    }.items()\n",
+    ").n()\n",
     "tot_t_count = qpe_t_count(delta_pe, delta_ts, delta_ht, n_rot, n_t, xi_bound, prod_ord)\n",
-    "assert int(symb_t_count) == int(tot_t_count)"
+    "import math\n",
+    "assert math.ceil(symb_t_count) == math.ceil(tot_t_count)"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "qualtran",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -605,9 +604,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

qualtran/bloqs/gf_poly_arithmetic/gf_poly_split_and_join.ipynb

@@ -42,7 +42,7 @@
     "galois field GF($p^m$). Given an input quantum register representing a degree $n$ polynomial\n",
     "$f(x)$, this bloq splits it into $n + 1$ registers of type $QGF(p, m)$.\n",
     "\n",
-    "Give a polynomial\n",
+    "Given a polynomial\n",
     "$$\n",
     "    f(x) = \\sum_{i = 0}^{n} a_{i} x^{i} \\\\ \\forall a_{i} \\in GF(p^m)\n",
     "$$\n",
@@ -55,7 +55,7 @@
     "See `GFPolyJoin` for the inverse operation.\n",
     "\n",
     "#### Parameters\n",
-    " - `qgf_poly`: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined over a galois field GF($p^m$). \n",
+    " - `dtype`: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined over a galois field GF($p^m$). \n",
     "\n",
     "#### Registers\n",
     " - `reg`: The register to be split. On its left, it is of the type `qgf_poly`. On the right, it is an array of `QGF`s of shape `(qgf_poly.degree + 1,)`.\n"
@@ -136,12 +136,12 @@
     "representing coefficients of a degree $n$ polynomial $f(x)$, this bloq joins it into\n",
     "a register of type `QGFPoly`.\n",
     "\n",
-    "Give a polynomial\n",
+    "Given a polynomial\n",
     "$$\n",
     "    f(x) = \\sum_{i = 0}^{n} a_{i} x^{i} \\\\ \\forall a_{i} \\in GF(p^m)\n",
     "$$\n",
     "\n",
-    "the bloq joins register representing coefficients of the polynomial in big-endian representation\n",
+    "the bloq joins registers representing coefficients of the polynomial in big-endian representation\n",
     "such that\n",
     "$$\n",
     "    \\ket{a_{n}}\\ket{a_{n - 1}} \\cdots \\ket{a_0} \\xrightarrow{\\text{join}} \\ket{f(x)}\n",
@@ -150,11 +150,10 @@
     "See `GFPolySplit` for the inverse operation.\n",
     "\n",
     "#### Parameters\n",
-    " - `qgf_poly`: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined over a galois field GF($p^m$). \n",
+    " - `dtype`: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined over a galois field GF($p^m$). \n",
     "\n",
     "#### Registers\n",
-    " - `reg`: The register to be joined. On its left, it is an array of `QGF`s of shape\n",
-    " - ```: \n"
+    " - `reg`: The register to be joined. On its left, it is an array of `QGF`s of shape `(qgf_poly.degree + 1,)`. On the right, it is of the type `qgf_poly`.\n"
    ]
   },
   {

qualtran/bloqs/gf_poly_arithmetic/gf_poly_split_and_join.py

@@ -53,7 +53,7 @@ class GFPolySplit(_BookkeepingBloq):
     galois field GF($p^m$). Given an input quantum register representing a degree $n$ polynomial
     $f(x)$, this bloq splits it into $n + 1$ registers of type $QGF(p, m)$.
 
-    Give a polynomial
+    Given a polynomial
     $$
         f(x) = \sum_{i = 0}^{n} a_{i} x^{i} \\ \forall a_{i} \in GF(p^m)
     $$
@@ -66,7 +66,7 @@ class GFPolySplit(_BookkeepingBloq):
     See `GFPolyJoin` for the inverse operation.
 
     Args:
-        qgf_poly: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined
+        dtype: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined
             over a galois field GF($p^m$).
 
     Registers:
@@ -158,12 +158,12 @@ class GFPolyJoin(_BookkeepingBloq):
     representing coefficients of a degree $n$ polynomial $f(x)$, this bloq joins it into
     a register of type `QGFPoly`.
 
-    Give a polynomial
+    Given a polynomial
     $$
         f(x) = \sum_{i = 0}^{n} a_{i} x^{i} \\ \forall a_{i} \in GF(p^m)
     $$
 
-    the bloq joins register representing coefficients of the polynomial in big-endian representation
+    the bloq joins registers representing coefficients of the polynomial in big-endian representation
     such that
     $$
         \ket{a_{n}}\ket{a_{n - 1}} \cdots \ket{a_0} \xrightarrow{\text{join}} \ket{f(x)}
@@ -172,12 +172,12 @@ class GFPolyJoin(_BookkeepingBloq):
     See `GFPolySplit` for the inverse operation.
 
     Args:
-        qgf_poly: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined
+        dtype: An instance of `QGFPoly` type that represents a degree $n$ polynomial defined
             over a galois field GF($p^m$).
 
     Registers:
         reg: The register to be joined. On its left, it is an array of `QGF`s of shape
-        `(qgf_poly.degree + 1,)`. On the right, it is of the type `qgf_poly`.
+            `(qgf_poly.degree + 1,)`. On the right, it is of the type `qgf_poly`.
 
     """