[mod_arithmetic] Organize modular addition

dev_tools/autogenerate-bloqs-notebooks-v2.py

@@ -75,6 +75,7 @@
 import qualtran.bloqs.factoring.mod_exp
 import qualtran.bloqs.hamiltonian_simulation.hamiltonian_simulation_by_gqsp
 import qualtran.bloqs.mcmt.and_bloq
+import qualtran.bloqs.mod_arithmetic.mod_addition
 import qualtran.bloqs.multiplexers.apply_gate_to_lth_target
 import qualtran.bloqs.multiplexers.select_pauli_lcu
 import qualtran.bloqs.phase_estimation.lp_resource_state
@@ -280,7 +281,6 @@
         bloq_specs=[
             qualtran.bloqs.arithmetic.addition._ADD_DOC,
             qualtran.bloqs.arithmetic.addition._ADD_OOP_DOC,
-            qualtran.bloqs.arithmetic.addition._SIMPLE_ADD_K_DOC,
             qualtran.bloqs.arithmetic.addition._ADD_K_DOC,
         ],
     ),
@@ -341,6 +341,17 @@
     ),
 ]
 
+MOD_ARITHMETIC = [
+    NotebookSpecV2(
+        title='Modular Addition',
+        module=qualtran.bloqs.mod_arithmetic.mod_addition,
+        bloq_specs=[
+            qualtran.bloqs.mod_arithmetic.mod_addition._MOD_ADD_DOC,
+            qualtran.bloqs.mod_arithmetic.mod_addition._MOD_ADD_K_DOC,
+        ],
+    )
+]
+
 
 ROT_QFT_PE = [
     # --------------------------------------------------------------------------
@@ -513,6 +524,7 @@
     ('Basic Gates', BASIC_GATES),
     ('Chemistry', CHEMISTRY),
     ('Arithmetic', ARITHMETIC),
+    ('Modular Arithmetic', MOD_ARITHMETIC),
     ('Rotations', ROT_QFT_PE),
     ('Other', OTHER),
 ]

docs/bloqs/index.rst

@@ -62,6 +62,12 @@ Bloqs Library
     factoring/mod_exp.ipynb
     factoring/mod_mul.ipynb
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Modular Arithmetic:
+
+    mod_arithmetic/mod_addition.ipynb
+
 .. toctree::
     :maxdepth: 2
     :caption: Rotations:

qualtran/bloqs/arithmetic/__init__.py

@@ -12,12 +12,7 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-from qualtran.bloqs.arithmetic.addition import (
-    Add,
-    AddConstantMod,
-    OutOfPlaceAdder,
-    SimpleAddConstant,
-)
+from qualtran.bloqs.arithmetic.addition import Add, AddK, OutOfPlaceAdder
 from qualtran.bloqs.arithmetic.comparison import (
     BiQubitsMixer,
     EqualsAConstant,

qualtran/bloqs/arithmetic/addition.ipynb

@@ -307,149 +307,19 @@
   },
   {
    "cell_type": "markdown",
-   "id": "1df2fb29",
+   "id": "2813f173",
    "metadata": {
-    "cq.autogen": "AddConstantMod.bloq_doc.md"
+    "cq.autogen": "AddK.bloq_doc.md"
    },
    "source": [
-    "## `AddConstantMod`\n",
-    "Applies U(add, M)|x> = |(x + add) % M> if x < M else |x>.\n",
-    "\n",
-    "Applies modular addition to input register `|x>` given parameters `mod` and `add_val` s.t.\n",
-    " 1. If integer `x` < `mod`: output is `|(x + add) % M>`\n",
-    " 2. If integer `x` >= `mod`: output is `|x>`.\n",
-    "\n",
-    "This condition is needed to ensure that the mapping of all input basis states (i.e. input\n",
-    "states |0>, |1>, ..., |2 ** bitsize - 1) to corresponding output states is bijective and thus\n",
-    "the gate is reversible.\n",
-    "\n",
-    "Also supports controlled version of the gate by specifying a per qubit control value as a tuple\n",
-    "of integers passed as `cvs`."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "5ef2dab4",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.bloq_doc.py"
-   },
-   "outputs": [],
-   "source": [
-    "from qualtran.bloqs.arithmetic import AddConstantMod"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "ed3f3c05",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.example_instances.md"
-   },
-   "source": [
-    "### Example Instances"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "195a8047",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.add_k_symb"
-   },
-   "outputs": [],
-   "source": [
-    "n, m, k = sympy.symbols('n m k')\n",
-    "add_k_symb = AddConstantMod(bitsize=n, mod=m, add_val=k)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "9c3f7fb3",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.add_k_small"
-   },
-   "outputs": [],
-   "source": [
-    "add_k_small = AddConstantMod(bitsize=4, mod=7, add_val=1)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "bdc82bc1",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.add_k_large"
-   },
-   "outputs": [],
-   "source": [
-    "add_k_large = AddConstantMod(bitsize=64, mod=500, add_val=23)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "b6885dbb",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.graphical_signature.md"
-   },
-   "source": [
-    "#### Graphical Signature"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "65773e01",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.graphical_signature.py"
-   },
-   "outputs": [],
-   "source": [
-    "from qualtran.drawing import show_bloqs\n",
-    "show_bloqs([add_k_symb, add_k_small, add_k_large],\n",
-    "           ['`add_k_symb`', '`add_k_small`', '`add_k_large`'])"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "1a4bf832",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.call_graph.md"
-   },
-   "source": [
-    "### Call Graph"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "61f1568e",
-   "metadata": {
-    "cq.autogen": "AddConstantMod.call_graph.py"
-   },
-   "outputs": [],
-   "source": [
-    "from qualtran.resource_counting.generalizers import ignore_split_join\n",
-    "add_k_symb_g, add_k_symb_sigma = add_k_symb.call_graph(max_depth=1, generalizer=ignore_split_join)\n",
-    "show_call_graph(add_k_symb_g)\n",
-    "show_counts_sigma(add_k_symb_sigma)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "9449e4e9",
-   "metadata": {
-    "cq.autogen": "SimpleAddConstant.bloq_doc.md"
-   },
-   "source": [
-    "## `SimpleAddConstant`\n",
+    "## `AddK`\n",
     "Takes |x> to |x + k> for a classical integer `k`.\n",
     "\n",
-    "Applies addition to input register `|x>` given classical integer 'k'.\n",
-    "\n",
-    "This is the simple version of constant addition because it involves simply converting the\n",
-    "classical integer into a quantum parameter and using quantum-quantum addition as opposed to\n",
-    "designing a bespoke circuit for constant addition based on the classical parameter.\n",
+    "This construction simply XORs the classical constant into a quantum register and\n",
+    "applies quantum-quantum addition. This is the lowest T-count algorithm at the expense\n",
+    "of $n$ auxiliary qubits. This construction also permits an inexpensive controlled version:\n",
+    "you only need to control the loading of the classical constant which can be done with\n",
+    "only clifford operations.\n",
     "\n",
     "#### Parameters\n",
     " - `bitsize`: Number of bits used to represent each integer.\n",
@@ -461,26 +331,26 @@
     " - `x`: A bitsize-sized input register (register x above). \n",
     "\n",
     "#### References\n",
-    " - [Improved quantum circuits for elliptic curve discrete logarithms](https://arxiv.org/abs/2001.09580). Fig 2a\n"
+    " - [Improved quantum circuits for elliptic curve discrete logarithms](https://arxiv.org/abs/2001.09580). Haner et. al. 2020. Section 3: Components. \"Integer addition\" and Fig 2a.\n"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "cd255bf9",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.bloq_doc.py"
+    "cq.autogen": "AddK.bloq_doc.py"
    },
    "outputs": [],
    "source": [
-    "from qualtran.bloqs.arithmetic import SimpleAddConstant"
+    "from qualtran.bloqs.arithmetic import AddK"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "7538f9a5",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.example_instances.md"
+    "cq.autogen": "AddK.example_instances.md"
    },
    "source": [
     "### Example Instances"
@@ -491,43 +361,43 @@
    "execution_count": null,
    "id": "4305289f",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.simple_add_k_symb"
+    "cq.autogen": "AddK.add_k"
    },
    "outputs": [],
    "source": [
     "n, k = sympy.symbols('n k')\n",
-    "simple_add_k_symb = SimpleAddConstant(bitsize=n, k=k)"
+    "add_k = AddK(bitsize=n, k=k)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "f6048819",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.simple_add_k_small"
+    "cq.autogen": "AddK.add_k_small"
    },
    "outputs": [],
    "source": [
-    "simple_add_k_small = SimpleAddConstant(bitsize=4, k=2, signed=False)"
+    "add_k_small = AddK(bitsize=4, k=2, signed=False)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "id": "b67fd469",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.simple_add_k_large"
+    "cq.autogen": "AddK.add_k_large"
    },
    "outputs": [],
    "source": [
-    "simple_add_k_large = SimpleAddConstant(bitsize=64, k=-23, signed=True)"
+    "add_k_large = AddK(bitsize=64, k=-23, signed=True)"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "b8b04228",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.graphical_signature.md"
+    "cq.autogen": "AddK.graphical_signature.md"
    },
    "source": [
     "#### Graphical Signature"
@@ -538,20 +408,20 @@
    "execution_count": null,
    "id": "e93e7f2e",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.graphical_signature.py"
+    "cq.autogen": "AddK.graphical_signature.py"
    },
    "outputs": [],
    "source": [
     "from qualtran.drawing import show_bloqs\n",
-    "show_bloqs([simple_add_k_small, simple_add_k_large],\n",
-    "           ['`simple_add_k_small`', '`simple_add_k_large`'])"
+    "show_bloqs([add_k, add_k_small, add_k_large],\n",
+    "           ['`add_k`', '`add_k_small`', '`add_k_large`'])"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "13552795",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.call_graph.md"
+    "cq.autogen": "AddK.call_graph.md"
    },
    "source": [
     "### Call Graph"
@@ -562,14 +432,14 @@
    "execution_count": null,
    "id": "d8d6584e",
    "metadata": {
-    "cq.autogen": "SimpleAddConstant.call_graph.py"
+    "cq.autogen": "AddK.call_graph.py"
    },
    "outputs": [],
    "source": [
     "from qualtran.resource_counting.generalizers import ignore_split_join\n",
-    "simple_add_k_small_g, simple_add_k_small_sigma = simple_add_k_small.call_graph(max_depth=1, generalizer=ignore_split_join)\n",
-    "show_call_graph(simple_add_k_small_g)\n",
-    "show_counts_sigma(simple_add_k_small_sigma)"
+    "add_k_g, add_k_sigma = add_k.call_graph(max_depth=1, generalizer=ignore_split_join)\n",
+    "show_call_graph(add_k_g)\n",
+    "show_counts_sigma(add_k_sigma)"
    ]
   },
   {