[jupyter_autogen] support "Registers" section (#372)

dev_tools/qualtran_dev_tools/jupyter_autogen.py

@@ -109,6 +109,10 @@ def path_stem(self):
 class _GoogleDocstringToMarkdown(GoogleDocstring):
     """Subclass of sphinx's parser to emit Markdown from Google-style docstrings."""
 
+    def _load_custom_sections(self) -> None:
+        super()._load_custom_sections()
+        self._sections['registers'] = self._parse_registers_section
+
     def _parse_parameters_section(self, section: str) -> List[str]:
         """Sphinx method to emit a 'Parameters' section."""
 
@@ -130,6 +134,17 @@ def _parse_references_section(self, section: str) -> List[str]:
             '',
         ]
 
+    def _parse_registers_section(self, section: str) -> List[str]:
+        def _template(name, desc_lines):
+            desc = ' '.join(desc_lines)
+            return f' - `{name}`: {desc}'
+
+        return [
+            '#### Registers',
+            *[_template(name, desc) for name, _type, desc in self._consume_fields()],
+            '',
+        ]
+
 
 def get_markdown_docstring_lines(cls: Type) -> List[str]:
     """From a class `cls`, return its docstring as Markdown."""

qualtran/bloqs/and_bloq.ipynb

@@ -39,9 +39,9 @@
     " - `cv1`: Whether the first bit is a positive control.\n",
     " - `cv2`: Whether the second bit is a positive control. \n",
     "\n",
-    "Registers:\n",
-    " - ctrl: A two-bit control register.\n",
-    " - (right) target: The output bit.\n",
+    "#### Registers\n",
+    " - `ctrl`: A two-bit control register.\n",
+    " - `target [right]`: The output bit. \n",
     "\n",
     "#### References\n",
     "(Encoding Electronic Spectra in Quantum Circuits with Linear T Complexity)[https://arxiv.org/abs/1805.03662]. Babbush et. al. 2018. Section III.A. and Fig. 4. (Verifying Measurement Based Uncomputation)[https://algassert.com/post/1903]. Gidney, C. 2019.\n"
@@ -126,10 +126,10 @@
     "#### Parameters\n",
     " - `cvs`: A tuple of control variable settings. Each entry specifies whether that control line is a \"positive\" control (`cv[i]=1`) or a \"negative\" control `0`. \n",
     "\n",
-    "Registers:\n",
-    " - ctrl: An n-bit control register.\n",
-    " - (right) An `n-2` bit junk register to be cleaned up by the inverse operation.\n",
-    " - (right) target: The output bit."
+    "#### Registers\n",
+    " - `ctrl`: An n-bit control register.\n",
+    " - `junk [right]`: An `n-2` bit junk register to be cleaned up by the inverse operation.\n",
+    " - `target [right]`: The output bit.\n"
    ]
   },
   {

qualtran/bloqs/and_bloq.py

@@ -38,8 +38,8 @@ class And(Bloq):
         cv2: Whether the second bit is a positive control.
 
     Registers:
-     - ctrl: A two-bit control register.
-     - (right) target: The output bit.
+        ctrl: A two-bit control register.
+        target [right]: The output bit.
 
     References:
         (Encoding Electronic Spectra in Quantum Circuits with Linear T Complexity)[https://arxiv.org/abs/1805.03662].
@@ -137,9 +137,9 @@ class MultiAnd(Bloq):
             control line is a "positive" control (`cv[i]=1`) or a "negative" control `0`.
 
     Registers:
-     - ctrl: An n-bit control register.
-     - (right) An `n-2` bit junk register to be cleaned up by the inverse operation.
-     - (right) target: The output bit.
+        ctrl: An n-bit control register.
+        junk [right]: An `n-2` bit junk register to be cleaned up by the inverse operation.
+        target [right]: The output bit.
     """
 
     cvs: Tuple[int, ...] = field(validator=lambda i, f, v: len(v) >= 3, converter=tuple)

qualtran/bloqs/arithmetic.ipynb

@@ -40,9 +40,9 @@
     "#### Parameters\n",
     " - `bitsize`: Number of bits used to represent each integer. Must be large enough to hold the result in the output register of a + b. \n",
     "\n",
-    "Registers:\n",
-    " - a: A bitsize-sized input register (register a above).\n",
-    " - b: A bitsize-sized input/output register (register b above).\n",
+    "#### Registers\n",
+    " - `a`: A bitsize-sized input register (register a above).\n",
+    " - `b`: A bitsize-sized input/output register (register b above). \n",
     "\n",
     "#### References\n",
     "[Halving the cost of quantum addition](https://arxiv.org/abs/1709.06648)\n"
@@ -80,11 +80,10 @@
     " - `a_bitsize`: Number of bits used to represent the first integer.\n",
     " - `b_bitsize`: Number of bits used to represent the second integer. \n",
     "\n",
-    "Registers:\n",
-    " - a: a_bitsize-sized input register.\n",
-    " - b: b_bitsize-sized input register.\n",
-    " - result: A 2*max(a_bitsize, b_bitsize) bit-sized output register to store\n",
-    "    the result a*b.\n",
+    "#### Registers\n",
+    " - `a`: a_bitsize-sized input register.\n",
+    " - `b`: b_bitsize-sized input register.\n",
+    " - `result`: A 2*max(a_bitsize, b_bitsize) bit-sized output register to store the result a*b. \n",
     "\n",
     "#### References\n",
     "[Fault-Tolerant Quantum Simulations of Chemistry in First Quantization](https://arxiv.org/abs/2105.12767) pg 81 gives a Toffoli complexity for multiplying two numbers.\n"
@@ -120,9 +119,9 @@
     "#### Parameters\n",
     " - `bitsize`: Number of bits used to represent the integer to be squared. The result is stored in a register of size 2*bitsize. \n",
     "\n",
-    "Registers:\n",
-    " - a: A bitsize-sized input register (register a above).\n",
-    " - result: A 2-bitsize-sized input/ouput register.\n",
+    "#### Registers\n",
+    " - `a`: A bitsize-sized input register (register a above).\n",
+    " - `result`: A 2-bitsize-sized input/output register. \n",
     "\n",
     "#### References\n",
     "[Fault-Tolerant Quantum Simulations of Chemistry in First Quantization](https://arxiv.org/abs/2105.12767). pg 76 for Toffoli complexity.\n"
@@ -161,9 +160,9 @@
     " - `bitsize`: Number of bits used to represent each of the k integers.\n",
     " - `k`: The number of integers we want to square. \n",
     "\n",
-    "Registers:\n",
-    " - input: k n-bit registers.\n",
-    " - result: 2 * bitsize + 1 sized output register.\n",
+    "#### Registers\n",
+    " - `input`: k n-bit registers.\n",
+    " - `result`: 2 * bitsize + 1 sized output register. \n",
     "\n",
     "#### References\n",
     "[Fault-Tolerant Quantum Simulations of Chemistry in First Quantization](https://arxiv.org/abs/2105.12767) pg 80 give a Toffoli complexity for squaring.\n"
@@ -201,10 +200,10 @@
     "#### Parameters\n",
     " - `bitsize`: Number of bits used to represent the two integers a and b. \n",
     "\n",
-    "Registers:\n",
-    " - a: n-bit-sized input registers.\n",
-    " - b: n-bit-sized input registers.\n",
-    " - result: A single bit output register to store the result of A > B.\n",
+    "#### Registers\n",
+    " - `a`: n-bit-sized input registers.\n",
+    " - `b`: n-bit-sized input registers.\n",
+    " - `result`: A single bit output register to store the result of A > B. \n",
     "\n",
     "#### References\n",
     "[Improved techniques for preparing eigenstates of fermionic Hamiltonians](https://www.nature.com/articles/s41534-018-0071-5#additional-information), Comparison Oracle from SI: Appendix 2B (pg 3)\n"

qualtran/bloqs/arithmetic.py

@@ -29,8 +29,8 @@ class Add(Bloq):
             enough to hold the result in the output register of a + b.
 
     Registers:
-     - a: A bitsize-sized input register (register a above).
-     - b: A bitsize-sized input/output register (register b above).
+        a: A bitsize-sized input register (register a above).
+        b: A bitsize-sized input/output register (register b above).
 
     References:
         [Halving the cost of quantum addition](https://arxiv.org/abs/1709.06648)
@@ -62,8 +62,8 @@ class Square(Bloq):
             result is stored in a register of size 2*bitsize.
 
     Registers:
-     - a: A bitsize-sized input register (register a above).
-     - result: A 2-bitsize-sized input/ouput register.
+        a: A bitsize-sized input register (register a above).
+        result: A 2-bitsize-sized input/output register.
 
     References:
         [Fault-Tolerant Quantum Simulations of Chemistry in First
@@ -100,8 +100,8 @@ class SumOfSquares(Bloq):
         k: The number of integers we want to square.
 
     Registers:
-     - input: k n-bit registers.
-     - result: 2 * bitsize + 1 sized output register.
+        input: k n-bit registers.
+        result: 2 * bitsize + 1 sized output register.
 
     References:
         [Fault-Tolerant Quantum Simulations of Chemistry in First
@@ -146,10 +146,9 @@ class Product(Bloq):
         b_bitsize: Number of bits used to represent the second integer.
 
     Registers:
-     - a: a_bitsize-sized input register.
-     - b: b_bitsize-sized input register.
-     - result: A 2*max(a_bitsize, b_bitsize) bit-sized output register to store
-        the result a*b.
+        a: a_bitsize-sized input register.
+        b: b_bitsize-sized input register.
+        result: A 2*max(a_bitsize, b_bitsize) bit-sized output register to store the result a*b.
 
     References:
         [Fault-Tolerant Quantum Simulations of Chemistry in First
@@ -189,9 +188,9 @@ class GreaterThan(Bloq):
         bitsize: Number of bits used to represent the two integers a and b.
 
     Registers:
-     - a: n-bit-sized input registers.
-     - b: n-bit-sized input registers.
-     - result: A single bit output register to store the result of A > B.
+        a: n-bit-sized input registers.
+        b: n-bit-sized input registers.
+        result: A single bit output register to store the result of A > B.
 
     References:
         [Improved techniques for preparing eigenstates of fermionic

qualtran/bloqs/basic_gates.ipynb

@@ -43,9 +43,9 @@
     "## `CNOT`\n",
     "Two-qubit controlled-NOT.\n",
     "\n",
-    "Registers:\n",
-    " - ctrl: One-bit control register.\n",
-    " - target: One-bit target register."
+    "#### Registers\n",
+    " - `ctrl`: One-bit control register.\n",
+    " - `target`: One-bit target register.\n"
    ]
   },
   {
@@ -271,8 +271,8 @@
     " - `angle`: Rotation angle.\n",
     " - `eps`: precision for implementation of rotation. \n",
     "\n",
-    "Registers:\n",
-    " - q: One-bit register.\n",
+    "#### Registers\n",
+    " - `q`: One-bit register. \n",
     "\n",
     "#### References\n",
     "[Efficient synthesis of universal Repeat-Until-Success circuits](https://arxiv.org/abs/1404.5320), which offers a small improvement [Optimal ancilla-free Clifford+T approximation of z-rotations](https://arxiv.org/pdf/1403.2975.pdf).\n"
@@ -310,8 +310,8 @@
     "makes the gateset universal. One of the most popular additions is the T gate, yielding\n",
     "the common Clifford+T gateset.\n",
     "\n",
-    "Registers:\n",
-    " - q: The qubit\n",
+    "#### Registers\n",
+    " - `q`: The qubit \n",
     "\n",
     "#### References\n",
     "[Universal Quantum Computation with ideal Clifford gates and noisy ancillas](https://arxiv.org/abs/quant-ph/0403025). Bravyi and Kitaev. 2004. [Fast and efficient exact synthesis of single qubit unitaries generated by Clifford and T gates](https://arxiv.org/abs/1206.5236). Kliuchnikov et. al. 2012. [Universal Gate Set, Magic States, and costliness of the T gate](https://quantumcomputing.stackexchange.com/a/33358). Gidney. 2023.\n"
@@ -440,8 +440,8 @@
     "H |-\\rangle = |1\\rangle\n",
     "$$\n",
     "\n",
-    "Registers:\n",
-    " - q: The qubit"
+    "#### Registers\n",
+    " - `q`: The qubit\n"
    ]
   },
   {

qualtran/bloqs/basic_gates/cnot.py

@@ -43,8 +43,8 @@ class CNOT(Bloq):
     """Two-qubit controlled-NOT.
 
     Registers:
-     - ctrl: One-bit control register.
-     - target: One-bit target register.
+        ctrl: One-bit control register.
+        target: One-bit target register.
     """
 
     @cached_property

qualtran/bloqs/basic_gates/hadamard.py

@@ -41,7 +41,7 @@ class Hadamard(Bloq):
     $$
 
     Registers:
-     - q: The qubit
+        q: The qubit
     """
 
     @cached_property

qualtran/bloqs/basic_gates/rotation.py

@@ -56,7 +56,7 @@ class Rz(RotationBloq):
         eps: precision for implementation of rotation.
 
     Registers:
-     - q: One-bit register.
+        q: One-bit register.
 
     References:
         [Efficient synthesis of universal Repeat-Until-Success

qualtran/bloqs/basic_gates/t_gate.py

@@ -39,7 +39,7 @@ class TGate(Bloq):
     the common Clifford+T gateset.
 
     Registers:
-     - q: The qubit
+        q: The qubit
 
     References:
         [Universal Quantum Computation with ideal Clifford gates and noisy ancillas](https://arxiv.org/abs/quant-ph/0403025).

qualtran/bloqs/factoring/mod_add.py

@@ -35,9 +35,9 @@ class CtrlScaleModAdd(Bloq):
         bitsize: The size of the two registers.
 
     Registers:
-     - ctrl: The control bit
-     - x: The 'source' quantum register containing the integer to be scaled and added to `y`.
-     - y: The 'destination' quantum register to which the addition will apply.
+        ctrl: The control bit
+        x: The 'source' quantum register containing the integer to be scaled and added to `y`.
+        y: The 'destination' quantum register to which the addition will apply.
     """
 
     k: Union[int, sympy.Expr]

qualtran/bloqs/factoring/mod_exp.py

@@ -42,8 +42,8 @@ class ModExp(Bloq):
         x_bitsize: The size of the `x` right-register
 
     Registers:
-     - exponent: The exponent
-     - x [right]: The output register containing the result of the exponentiation
+        exponent: The exponent
+        x [right]: The output register containing the result of the exponentiation
 
     References:
         [GE2019] How to factor 2048 bit RSA integers in 8 hours using 20 million noisy qubits.

qualtran/bloqs/factoring/mod_mul.py

@@ -36,8 +36,8 @@ class CtrlModMul(Bloq):
         bitsize: The size of the `x` register.
 
     Registers:
-     - ctrl: The control bit
-     - x: The integer being multiplied
+        ctrl: The control bit
+        x: The integer being multiplied
     """
 
     k: Union[int, sympy.Expr]

qualtran/bloqs/factoring/ref-factoring.ipynb

@@ -55,9 +55,9 @@
     " - `exp_bitsize`: The size of the `exponent` thru-register\n",
     " - `x_bitsize`: The size of the `x` right-register \n",
     "\n",
-    "Registers:\n",
-    " - exponent: The exponent\n",
-    " - x [right]: The output register containing the result of the exponentiation\n",
+    "#### Registers\n",
+    " - `exponent`: The exponent\n",
+    " - `x [right]`: The output register containing the result of the exponentiation \n",
     "\n",
     "#### References\n",
     "[GE2019] How to factor 2048 bit RSA integers in 8 hours using 20 million noisy qubits. [arxiv:1905.09749](https://arxiv.org/abs/1905.09749). Gidney and Ekerå. 2019.\n"
@@ -237,9 +237,9 @@
     " - `mod`: The integer modulus.\n",
     " - `bitsize`: The size of the `x` register. \n",
     "\n",
-    "Registers:\n",
-    " - ctrl: The control bit\n",
-    " - x: The integer being multiplied"
+    "#### Registers\n",
+    " - `ctrl`: The control bit\n",
+    " - `x`: The integer being multiplied\n"
    ]
   },
   {

qualtran/bloqs/sorting.ipynb

@@ -43,10 +43,10 @@
     "#### Parameters\n",
     " - `bitsize`: Number of bits used to represent each integer. \n",
     "\n",
-    "Registers:\n",
-    " - a: A nbit-sized input register (register a above).\n",
-    " - b: A nbit-sized input register (register b above).\n",
-    " - out: A single bit output register which will store the result of the comparator.\n",
+    "#### Registers\n",
+    " - `a`: A nbit-sized input register (register a above).\n",
+    " - `b`: A nbit-sized input register (register b above).\n",
+    " - `out`: A single bit output register which will store the result of the comparator. \n",
     "\n",
     "#### References\n",
     "[Improved techniques for preparing eigenstates of fermionic Hamiltonians](https://www.nature.com/articles/s41534-018-0071-5), Fig. 1. in main text.\n"
@@ -84,9 +84,8 @@
     " - `bitsize`: Number of bits used to represent each integer.\n",
     " - `k`: Number of integers to sort. \n",
     "\n",
-    "Registers:\n",
-    " - input: A k-nbit-sized input register (register a above). List of integers\n",
-    "    we want to sort.\n",
+    "#### Registers\n",
+    " - `input`: A k-nbit-sized input register (register a above). List of integers we want to sort. \n",
     "\n",
     "#### References\n",
     "[Improved techniques for preparing eigenstates of fermionic Hamiltonians](https://www.nature.com/articles/s41534-018-0071-5), Supporting Information Sec. II.\n"