Bibliography updates (#1613)

* Bibliography updates

* regenerate notebooks

Author: mpharrigan

dev_tools/bibliography.ipynb

@@ -131,8 +131,9 @@
    "source": [
     "for url, clss in sorted(backrefs.items(), key=lambda x: -len(x[1])):\n",
     "    text = f'### [{titles[url]}]({url})\\n'\n",
-    "    for cls in clss:\n",
-    "        text += f' - {cls.__name__}\\n'\n",
+    "    class_names = [f'{cls._class_name_in_pkg_()}' for cls in clss]\n",
+    "    for cn in sorted(class_names):\n",
+    "        text += f' - {cn}\\n'\n",
     "\n",
     "    display(Markdown(text))"
    ]

dev_tools/qualtran_dev_tools/parse_docstrings.py

@@ -49,7 +49,7 @@ def parse_reference(ref_text: str) -> ReferenceT:
     # To match the title and accept as many printable ascii characters as possible
     # besides square brackets, I have modified the range approach from
     # https://stackoverflow.com/a/31740504.
-    link_match = re.match(r'^\[([ -Z^-~]+)]\((https?://[\w\d./?=#\-]+)\)\.?\s?(.*)$', ref_text)
+    link_match = re.match(r'^\[([ -Z^-~]+)]\((https?://[\w\d./?=#\-\(\)]+)\)\.?\s?(.*)$', ref_text)
     if link_match:
         title = link_match.group(1)
         url = link_match.group(2)

dev_tools/qualtran_dev_tools/parse_docstrings_test.py

@@ -11,7 +11,10 @@
 #  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
-from .parse_docstrings import get_markdown_docstring_lines
+import pytest
+
+from .bloq_finder import get_bloq_classes
+from .parse_docstrings import get_markdown_docstring_lines, get_references, UnparsedReference
 
 
 class ClassWithDocstrings:
@@ -40,3 +43,16 @@ def test_get_markdown_docstring_lines():
         ' - [Google](www.google.com). Brin et. al. 1999.',
         '',
     ]
+
+
+@pytest.mark.slow
+def test_parse_all_references():
+    bloq_classes = get_bloq_classes()
+    references = {bloq_cls: get_references(bloq_cls) for bloq_cls in bloq_classes}
+    for bloq_cls, refs in references.items():
+        for ref in refs:
+            if isinstance(ref, UnparsedReference):
+                raise AssertionError(
+                    f"{bloq_cls.__module__}.{bloq_cls.__qualname__} has an incorrectly "
+                    f"formatted reference:\n{ref.text}"
+                )

qualtran/_infra/bloq.py

@@ -573,3 +573,14 @@ def wire_symbol(
 
     def __str__(self):
         return self.__class__.__name__
+
+    @classmethod
+    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
+        `qualtran.bloqs.*`. Each bloq class is defined in a module (i.e. the
+        "*.py" file) and re-exported one level up.
+        """
+        pkg = '.'.join(cls.__module__.split('.')[:-1])
+        return f'{pkg}.{cls.__name__}'

qualtran/bloqs/arithmetic/comparison.ipynb

@@ -468,7 +468,7 @@
    },
    "source": [
     "## `BiQubitsMixer`\n",
-    "Implements the COMPARE2 subroutine from the reference (Fig. 1)\n",
+    "Implements the COMPARE2 subroutine from the reference.\n",
     "\n",
     "This gates mixes the values in a way that preserves the result of comparison.\n",
     "The signature being compared are 2-qubit signature where\n",
@@ -485,7 +485,7 @@
     "https://github.com/quantumlib/Qualtran/issues/389\n",
     "\n",
     "#### References\n",
-    " - [Supplementary Materials: Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://static-content.springer.com/esm/art%3A10.1038%2Fs41534-018-0071-5/MediaObjects/41534_2018_71_MOESM1_ESM.pdf).\n"
+    " - [Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://arxiv.org/abs/1711.10460). Berry et al. 2017. Appendix B. Fig 3.\n"
    ]
   },
   {
@@ -582,7 +582,7 @@
     "Applies U|a>|b>|0>|0> = |a> |a=b> |(a<b)> |(a>b)>\n",
     "\n",
     "#### References\n",
-    " - Supplementary Materials: Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians. Figure 3. https://static-content.springer.com/esm/art%3A10.1038%2Fs41534-018-0071-5/MediaObjects/41534_2018_71_MOESM1_ESM.pdf\n"
+    " - [Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://arxiv.org/abs/1711.10460). Berry et al. 2017. Appendix B. Fig 5.\n"
    ]
   },
   {
@@ -702,7 +702,7 @@
     "\n",
     "#### References\n",
     " - [Encoding Electronic Spectra in Quantum Circuits with Linear T Complexity](https://arxiv.org/abs/1805.03662). \n",
-    " - [Supplementary Materials: Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://static-content.springer.com/esm/art%3A10.1038%2Fs41534-018-0071-5/MediaObjects/41534_2018_71_MOESM1_ESM.pdf).\n"
+    " - [Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://arxiv.org/abs/1711.10460). Berry et al. 2017. Appendix B.\n"
    ]
   },
   {

qualtran/bloqs/arithmetic/comparison.py

@@ -218,7 +218,7 @@ def _lt_k_symb() -> LessThanConstant:
 
 @frozen
 class BiQubitsMixer(GateWithRegisters):
-    """Implements the COMPARE2 subroutine from the reference (Fig. 1)
+    """Implements the COMPARE2 subroutine from the reference.
 
     This gates mixes the values in a way that preserves the result of comparison.
     The signature being compared are 2-qubit signature where
@@ -235,7 +235,8 @@ class BiQubitsMixer(GateWithRegisters):
     https://github.com/quantumlib/Qualtran/issues/389
 
     References:
-        [Supplementary Materials: Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://static-content.springer.com/esm/art%3A10.1038%2Fs41534-018-0071-5/MediaObjects/41534_2018_71_MOESM1_ESM.pdf).
+        [Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://arxiv.org/abs/1711.10460).
+        Berry et al. 2017. Appendix B. Fig 3.
     """
 
     is_adjoint: bool = False
@@ -323,9 +324,8 @@ class SingleQubitCompare(GateWithRegisters):
     """Applies U|a>|b>|0>|0> = |a> |a=b> |(a<b)> |(a>b)>
 
     References:
-        Supplementary Materials: Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians.
-        Figure 3.
-        https://static-content.springer.com/esm/art%3A10.1038%2Fs41534-018-0071-5/MediaObjects/41534_2018_71_MOESM1_ESM.pdf
+        [Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://arxiv.org/abs/1711.10460).
+        Berry et al. 2017. Appendix B. Fig 5.
     """
 
     is_adjoint: bool = False
@@ -433,7 +433,8 @@ class LessThanEqual(GateWithRegisters, cirq.ArithmeticGate):  # type: ignore[mis
     References:
         [Encoding Electronic Spectra in Quantum Circuits with Linear T Complexity](https://arxiv.org/abs/1805.03662).
 
-        [Supplementary Materials: Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://static-content.springer.com/esm/art%3A10.1038%2Fs41534-018-0071-5/MediaObjects/41534_2018_71_MOESM1_ESM.pdf).
+        [Improved Techniques for Preparing Eigenstates of Fermionic Hamiltonians](https://arxiv.org/abs/1711.10460).
+        Berry et al. 2017. Appendix B.
     """
 
     x_bitsize: 'SymbolicInt'

qualtran/bloqs/basic_gates/rotation.ipynb

@@ -427,7 +427,7 @@
     "\n",
     "#### References\n",
     " - [Elementary gates for quantum computation](https://arxiv.org/abs/quant-ph/9503016). Barenco et al. 1995. Special case of Lemma 5.4.\n",
-    " - [Is Controlled(𝑅𝑧(𝜃)) more expensive than Controlled(𝑍𝑡) on the surface code?](https://quantumcomputing.stackexchange.com/a/40012). Adam Zalcman. 2024.\n"
+    " - [Is Controlled(Rz(theta)) more expensive than Controlled(Z^t) on the surface code?](https://quantumcomputing.stackexchange.com/a/40012). Adam Zalcman. 2024.\n"
    ]
   },
   {

qualtran/bloqs/basic_gates/rotation.py

@@ -514,7 +514,7 @@ class CRz(Bloq):
         [Elementary gates for quantum computation](https://arxiv.org/abs/quant-ph/9503016).
         Barenco et al. 1995. Special case of Lemma 5.4.
 
-        [Is Controlled(𝑅𝑧(𝜃)) more expensive than Controlled(𝑍𝑡) on the surface code?](https://quantumcomputing.stackexchange.com/a/40012).
+        [Is Controlled(Rz(theta)) more expensive than Controlled(Z^t) on the surface code?](https://quantumcomputing.stackexchange.com/a/40012).
         Adam Zalcman. 2024.
     """
 

qualtran/bloqs/cryptography/ecc/ec_add_r.py

@@ -70,9 +70,8 @@ class ECAddR(Bloq):
         [Quantum resource estimates for computing elliptic curve discrete logarithms](https://arxiv.org/abs/1706.06752).
         Roetteler et al. 2017. Algorithm 1 and Figure 10.
 
-        [https://github.com/microsoft/QuantumEllipticCurves/blob/dbf4836afaf7a9fab813cbc0970e65af85a6f93a/MicrosoftQuantumCrypto/EllipticCurves.qs#L456](QuantumQuantumCrypto).
-        `DistinctEllipticCurveClassicalPointAddition`.
-
+        [Microsoft Quantum Crypto (GitHub)](https://github.com/microsoft/QuantumEllipticCurves/blob/dbf4836afaf7a9fab813cbc0970e65af85a6f93a/MicrosoftQuantumCrypto/EllipticCurves.qs#L456).
+        Jaques et al. 2020. `DistinctEllipticCurveClassicalPointAddition`.
     """
 
     n: 'SymbolicInt'

qualtran/bloqs/cryptography/ecc/ecc.ipynb

@@ -357,7 +357,7 @@
     "#### 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. Section 1, eq. (3) and (4).\n",
     " - [Quantum resource estimates for computing elliptic curve discrete logarithms](https://arxiv.org/abs/1706.06752). Roetteler et al. 2017. Algorithm 1 and Figure 10.\n",
-    " - [https://github.com/microsoft/QuantumEllipticCurves/blob/dbf4836afaf7a9fab813cbc0970e65af85a6f93a/MicrosoftQuantumCrypto/EllipticCurves.qs#L456](QuantumQuantumCrypto). `DistinctEllipticCurveClassicalPointAddition`.\n"
+    " - [Microsoft Quantum Crypto (GitHub)](https://github.com/microsoft/QuantumEllipticCurves/blob/dbf4836afaf7a9fab813cbc0970e65af85a6f93a/MicrosoftQuantumCrypto/EllipticCurves.qs#L456). Jaques et al. 2020. `DistinctEllipticCurveClassicalPointAddition`.\n"
    ]
   },
   {