Make docs for root bloqs follow the same workflow as other bloqs

dev_tools/autogenerate-bloqs-notebooks-v2.py

@@ -68,12 +68,6 @@
 ]
 
 
-# --------------------------------------------------------------------------
-# -----   Root Bloqs   -----------------------------------------------------
-# --------------------------------------------------------------------------
-ROOT_BLOQS = ['cryptography/ecc/ecc.ipynb']
-
-
 def _all_nbspecs() -> Iterable[NotebookSpecV2]:
     for _, nbspecs in NB_BY_SECTION:
         yield from nbspecs
@@ -108,7 +102,6 @@ def write_toc():
     ]
 
     toc_lines = header + _get_toc_section_lines('Concepts', CONCEPTS, maxdepth=1)
-    toc_lines += _get_toc_section_lines('Root Bloqs', ROOT_BLOQS, maxdepth=1)
     bloqs_dir = SOURCE_DIR / 'bloqs'
     for section, nbspecs in NB_BY_SECTION:
         entries = [str(nbspec.path.relative_to(bloqs_dir)) for nbspec in nbspecs]

dev_tools/qualtran_dev_tools/notebook_specs.py

@@ -138,6 +138,19 @@
 GIT_ROOT = get_git_root()
 SOURCE_DIR = GIT_ROOT / 'qualtran/'
 
+# --------------------------------------------------------------------------
+# -----   Root Bloqs   -----------------------------------------------------
+# --------------------------------------------------------------------------
+
+ROOT_BLOQS: List[NotebookSpecV2] = [
+    NotebookSpecV2(
+        title='Elliptic Curves',
+        module=qualtran.bloqs.cryptography.ecc,
+        path_stem='ecc_root',
+        bloq_specs=[qualtran.bloqs.cryptography.ecc.find_ecc_private_key._ECC_BLOQ_DOC],
+    )
+]
+
 # --------------------------------------------------------------------------
 # -----   Basic Gates   ----------------------------------------------------
 # --------------------------------------------------------------------------
@@ -928,6 +941,7 @@
 ]
 
 NB_BY_SECTION = [
+    ('Root Bloqs', ROOT_BLOQS),
     ('Basic Gates', BASIC_GATES),
     ('Chemistry', CHEMISTRY),
     ('Arithmetic', ARITHMETIC),

docs/bloqs/index.rst

@@ -23,10 +23,10 @@ Bloqs Library
     state_preparation/state_preparation_via_rotation_tutorial.ipynb
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :caption: Root Bloqs:
 
-    cryptography/ecc/ecc.ipynb
+    cryptography/ecc/ecc_root.ipynb
 
 .. toctree::
     :maxdepth: 2

qualtran/bloqs/cryptography/ecc/ecc_root.ipynb

@@ -0,0 +1,200 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "4521a4ad",
+   "metadata": {
+    "cq.autogen": "title_cell"
+   },
+   "source": [
+    "# Elliptic Curves\n",
+    "\n",
+    "Bloqs for breaking elliptic curve cryptography systems via the discrete log.\n",
+    "\n",
+    "Elliptic curve cryptography is a form of public key cryptography based on the finite\n",
+    "field of elliptic curves. For our purposes, we will denote the group operation as addition\n",
+    "(whose definition we will explore later) $A + B$. We will denote repeated addition\n",
+    " as $[k] A = A + \\dots + A$ ($k$ times).\n",
+    "\n",
+    "Within this algebra, the cryptographic scheme relates the public and private keys via\n",
+    "$$\n",
+    "Q = [k] P\n",
+    "$$\n",
+    "for private key $k$, public key $Q$, and a choice of base point $P$. The cryptographic\n",
+    "security comes from the difficulty of inverting the multiplication. I.e. it is difficult\n",
+    "to do a discrete logarithm in this field.\n",
+    "\n",
+    "Using Shor's algorithm for the discrete logarithm, we can find $k$ in polynomial time\n",
+    "with a quantum algorithm."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c2f0f36c",
+   "metadata": {
+    "cq.autogen": "top_imports"
+   },
+   "outputs": [],
+   "source": [
+    "from qualtran import Bloq, CompositeBloq, BloqBuilder, Signature, Register\n",
+    "from qualtran import QBit, QInt, QUInt, QAny\n",
+    "from qualtran.drawing import show_bloq, show_call_graph, show_counts_sigma\n",
+    "from typing import *\n",
+    "import numpy as np\n",
+    "import sympy\n",
+    "import cirq"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "27e50393",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.bloq_doc.md"
+   },
+   "source": [
+    "## `FindECCPrivateKey`\n",
+    "Perform two phase estimations to break elliptic curve cryptography.\n",
+    "\n",
+    "This follows the strategy in Litinski 2023. We perform two phase estimations corresponding\n",
+    "to `ECCAddR(R=P)` and `ECCAddR(R=Q)` for base point $P$ and public key $Q$.\n",
+    "\n",
+    "The first phase estimation projects us into a random eigenstate of the ECCAddR(R=P) operator\n",
+    "which we index by the integer $c$. Per eq. 5 in the reference, these eigenstates take the form\n",
+    "$$\n",
+    "|\\psi_c \\rangle = \\sum_j^{r-1} \\omega^{cj}\\ | [j]P \\rangle  \\\\\n",
+    "\\omega = e^{2\\pi i / r} \\\\\n",
+    "[r] P = P\n",
+    "$$\n",
+    "\n",
+    "This state is a simultaneous eigenstate of the second operator, `ECCAddR(R=Q)`. By\n",
+    "the definition of the operator, acting it upon $|\\psi_c\\rangle$ gives:\n",
+    "$$\n",
+    "|\\psi_c \\rangle \\rightarrow \\sum_j w^{cj} | [j]P + Q \\rangle\\rangle\n",
+    "$$\n",
+    "\n",
+    "The private key $k$ that we wish to recover relates the public key to the base point\n",
+    "$$\n",
+    "Q = [k] P\n",
+    "$$\n",
+    "so our simultaneous eigenstate can be equivalently written as\n",
+    "$$\n",
+    "\\sum_j^{r-1} \\omega^{cj} | [j+k] P \\rangle \\\\\n",
+    "= \\omega^{-ck} |\\psi_c \\rangle\n",
+    "$$\n",
+    "\n",
+    "Therefore, the measured result of the second phase estimation is $ck$. Since we have\n",
+    "already measured the random index $c$, we can divide it out to recover the private key $k$.\n",
+    "\n",
+    "#### Parameters\n",
+    " - `n`: The bitsize of the elliptic curve points' x and y registers.\n",
+    " - `base_point`: The base point $P$ with unknown order $r$ such that $P = [r] P$.\n",
+    " - `public_key`: The public key $Q$ such that $Q = [k] P$ for private key $k$.\n",
+    " - `add_window_size`: The number of bits in the ECAdd window.\n",
+    " - `mul_window_size`: The number of bits in the modular multiplication window. \n",
+    "\n",
+    "#### References\n",
+    " - [How to compute a 256-bit elliptic curve private key with only 50 million Toffoli gates](https://arxiv.org/abs/2306.08585). Litinski. 2023. Figure 4 (a).\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bcb004a4",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.bloq_doc.py"
+   },
+   "outputs": [],
+   "source": [
+    "from qualtran.bloqs.cryptography.ecc import FindECCPrivateKey"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "60989597",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.example_instances.md"
+   },
+   "source": [
+    "### Example Instances"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "78630e12",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.ecc"
+   },
+   "outputs": [],
+   "source": [
+    "n, p = sympy.symbols('n p')\n",
+    "Px, Py, Qx, Qy = sympy.symbols('P_x P_y Q_x Q_y')\n",
+    "P = ECPoint(Px, Py, mod=p)\n",
+    "Q = ECPoint(Qx, Qy, mod=p)\n",
+    "ecc = FindECCPrivateKey(n=n, base_point=P, public_key=Q)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6d4cc534",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.graphical_signature.md"
+   },
+   "source": [
+    "#### Graphical Signature"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "827c4557",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.graphical_signature.py"
+   },
+   "outputs": [],
+   "source": [
+    "from qualtran.drawing import show_bloqs\n",
+    "show_bloqs([ecc],\n",
+    "           ['`ecc`'])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "272d878d",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.call_graph.md"
+   },
+   "source": [
+    "### Call Graph"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11406e9e",
+   "metadata": {
+    "cq.autogen": "FindECCPrivateKey.call_graph.py"
+   },
+   "outputs": [],
+   "source": [
+    "from qualtran.resource_counting.generalizers import ignore_split_join\n",
+    "ecc_g, ecc_sigma = ecc.call_graph(max_depth=1, generalizer=ignore_split_join)\n",
+    "show_call_graph(ecc_g)\n",
+    "show_counts_sigma(ecc_sigma)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}