Merge branch 'main' into 2025/03/26-ctrl-ham-sim

Author: anurudhp

CITATION.cff

@@ -1,42 +1,54 @@
 # Citation information for this repository.                         -*- yaml -*-
 #
-# CITATION.cff files provide human- & machine-readable citation information for
-# software and datasets. GitHub, Zenodo, and the Zotero browser plugin all use
-# CFF files automatically if provided. https://citation-file-format.github.io/.
-#
-# Tools exist to generate CITATION.cff files from other formats such as BibTeX.
+# CITATION.cff provide human- & machine-readable citation info for software and
+# datasets. GitHub, Zenodo, and the Zotero browser plugin all use CFF files
+# automatically. Tools exist to generate CITATION.cff files from other formats
+# such as BibTeX. For more info, visit https://citation-file-format.github.io/.
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 cff-version: 1.2.0
-message: If you use this software, please cite it using this metadata.
+message: >-
+  Please cite your use of Qualtran using the reference metadata provided here.
 
-# CITATION.cff files describe how to cite software or datasets, with the goal of
-# making software and data be citable in their own right. However, sometimes
-# projects want citations to go to a paper instead. 'Preferred-citation' serves
-# to communicate that. The distinction matters in different situations. If this
-# field is present, GitHub uses the value for the "cite this repository" button
-# and ignores the rest of this file; conversely, the Zenodo-GitHub integration
-# ignores this field when creating an entry for a new software release (because
-# the Zenodo entry is specifically about the software in this repository).
+# If preferred-citation is present, GitHub uses its value for the "cite this
+# repository" button and ignores the rest of this file; conversely, the Zenodo-
+# GitHub integration ignores this field when archiving a new software release
+# and uses the metadata in the rest of this file.
 preferred-citation:
   type: misc
-  authors:
+  authors: &authors
     - family-names: Harrigan
       given-names: Matthew P.
+      affiliation: Google LLC
+      orcid: https://orcid.org/0000-0001-9412-0553
     - family-names: Khattar
       given-names: Tanuj
+      affiliation: Google LLC
+      orcid: https://orcid.org/0009-0003-5545-3066
     - family-names: Yuan
       given-names: Charles
+      affiliation: Massachusetts Institute of Technology
+      orcid: https://orcid.org/0000-0002-4918-4467
     - family-names: Peduri
       given-names: Anurudh
+      affiliation: Ruhr University Bochum
+      orcid: https://orcid.org/0000-0002-6523-7098
     - family-names: Yosri
       given-names: Noureldin
+      affiliation: Google LLC
+      orcid: https://orcid.org/0000-0003-4169-5745
     - family-names: Malone
       given-names: Fionn D.
+      affiliation: Google LLC
+      orcid: https://orcid.org/0000-0001-9239-0162
     - family-names: Babbush
       given-names: Ryan
+      affiliation: Google LLC
+      orcid: https://orcid.org/0000-0001-6979-9533
     - family-names: Rubin
       given-names: Nicholas C.
+      affiliation: Google LLC
+      orcid: https://orcid.org/0000-0003-3963-1830
   title: Expressing and Analyzing Quantum Algorithms with Qualtran
   year: 2024
   doi: 10.48550/arXiv.2409.04643
@@ -51,29 +63,13 @@ preferred-citation:
 # The remaining metadata in this file describes the current software release.
 
 title: Qualtran
-authors:
-  - family-names: Harrigan
-    given-names: Matt P.
-  - family-names: Khattar
-    given-names: Tanuj
-  - family-names: Yuan
-    given-names: Charles
-  - family-names: Peduri
-    given-names: Anurudh
-  - family-names: Yosri
-    given-names: Noureldin
-  - family-names: Malone
-    given-names: Fionn D.
-  - family-names: Babbush
-    given-names: Ryan
-  - family-names: Rubin
-    given-names: Nicholas C.
+authors: *authors
 abstract: >-
-  Qualtran (quantum algorithms translator) is a set of abstractions for
-  representing quantum programs, and a library of quantum algorithms expressed
-  in that language to support quantum algorithms research.
-version: 0.5.0
-date-released: 2024-09-10
+  Qualtran is a set of abstractions for representing quantum programs, and a
+  library of quantum algorithms expressed in that language to support quantum
+  algorithms research.
+version: 0.6.0
+date-released: 2025-04-01
 url: https://github.com/quantumlib/Qualtran
 repository-code: https://github.com/quantumlib/Qualtran
 license: Apache-2.0

README.md

@@ -1,59 +1,156 @@
-# Qᴜᴀʟᴛʀᴀɴ
+<!-- # Qualtran (title omitted because our logo acts as the title) -->
 
-Qᴜᴀʟᴛʀᴀɴ (quantum algorithms translator) is a set of abstractions for representing quantum 
-programs and a library of quantum algorithms expressed in that language to support quantum 
-algorithms research.
+<div align="center">
+<img alt="Qualtran logo" width="340px" src="https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/qualtran-logo-mode-sensitive.svg">
+<br>
 
-**Note:** Qualtran is an experimental preview release. We provide no backwards compatibility 
-guarantees. Some algorithms or library functionality may be incomplete or contain inaccuracies. 
-Open issues or contact the authors with bug reports or feedback.
+Python package for fault-tolerant quantum algorithms research.
 
-Subscribe to [qualtran-announce@googlegroups.com](https://groups.google.com/g/qualtran-announce)
-to receive the latest news and updates!
+[![Licensed under the Apache 2.0 open-source license](https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative\&logoColor=white\&style=flat-square)](https://github.com/quantumlib/qualtran/blob/main/LICENSE)
+[![Compatible with Python versions 3.10 and higher](https://img.shields.io/badge/Python-3.10+-6828b2.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Qualtran project on PyPI](https://img.shields.io/pypi/v/qualtran.svg?logo=python&logoColor=white&label=PyPI&style=flat-square&color=9d3bb8)](https://pypi.org/project/qualtran)
 
-## Documentation
+[Installation](#installation) &ndash;
+[Usage](#usage) &ndash;
+[Documentation](#documentation) &ndash;
+[Community](#community) &ndash;
+[Citation](#citation) &ndash;
+[Contact](#contact)
+
+</div>
 
-Documentation is available at https://qualtran.readthedocs.io/
+Qualtran is a set of abstractions for representing quantum programs and a library of quantum
+algorithms expressed in that language to support quantum algorithms research.
 
 ## Installation
 
-Qualtran is being actively developed. We recommend installing from source:
+Qualtran is being actively developed. We recommend installing from the source code.
 
-For a local editable copy:
+The following commands will clone a copy of the repository, then install the Qualtran package in
+your local Python environment as a local editable copy:
 
-    git clone https://github.com/quantumlib/Qualtran.git
-    cd Qualtran/
-    pip install -e .
+```shell
+git clone https://github.com/quantumlib/Qualtran.git
+cd Qualtran/
+pip install -e .
+```
 
 You can also install the latest tagged release using `pip`:
 
-    pip install qualtran
+```shell
+pip install qualtran
+```
+
+You can also install the latest version of the main branch on GitHub:
+
+```shell
+pip install git+https://github.com/quantumlib/Qualtran
+```
+
+## Usage
+
+> [!WARNING]
+> Qualtran is an experimental preview release. We provide no backwards compatibility guarantees.
+> Some algorithms or library functionality may be incomplete or contain inaccuracies. Open issues or
+> contact the authors with bug reports or feedback.
+
+You should be able to import the `qualtran` package into your interactive Python environment as
+as well as your programs:
+
+```shell
+import qualtran
+```
+
+If this is successful, you can move on to learning how to
+[write bloqs](https://qualtran.readthedocs.io/en/latest/_infra/Bloqs-Tutorial.html) or investigate
+the [bloqs library](https://qualtran.readthedocs.io/en/latest/bloqs/index.html#bloqs-library).
+
+## Documentation
+
+Documentation is available at https://qualtran.readthedocs.io/.
 
-You can also install the latest state of the main branch:
+## Community
 
-    pip install git+https://github.com/quantumlib/Qualtran
+Qualtran's community is growing rapidly, and if you'd like to join the [many open-source
+contributors] to the Qualtran project, we welcome your participation! We are dedicated to
+cultivating an open and inclusive community, and have a [code of conduct].
 
-## Physical Resource Estimation GUI
+[many open-source contributors]: https://github.com/quantumlib/Qualtran/graphs/contributors
+[code of conduct]: https://github.com/quantumlib/Qualtran/blob/main/CODE_OF_CONDUCT.md
 
-Qualtran provides a GUI for estimating the physical resources (qubits, magic states, runtime, ..etc) needed to run a quantum algorithm. The GUI can be run locally by running:
+### Announcements
 
-    cd $QUALTRAN_HOME
-    python -m qualtran.surface_code.ui
+You can stay on top of Qualtran news using the approach that best suits your needs:
 
-## Citation
+*   For releases and major announcements: join the low-volume mailing list [`qualtran-announce`].
+*   For releases only:
+    *   *Via GitHub notifications*: configure [repository notifications] for Qualtran.
+    *   *Via RSS from GitHub*: subscribe to the GitHub [Qualtran releases feed].
+    *   *Via RSS from PyPI*: subscribe to the [PyPI releases feed] for Qualtran.
 
-When publishing articles or otherwise writing about Qualtran, please cite the
-following:
+[`qualtran-announce`]: https://groups.google.com/g/qualtran-announce
+[repository notifications]: https://docs.github.com/github/managing-subscriptions-and-notifications-on-github/configuring-notifications
+[Qualtran releases feed]: https://github.com/quantumlib/Qualtran/releases.atom
+[PyPI releases feed]: https://pypi.org/rss/project/qualtran/releases.xml
 
-```latex
+### Questions and Discussions
+
+*   If you'd like to ask questions and participate in discussions, join the [`qualtran-dev`]
+    group/mailing list. By joining [`qualtran-dev`], you will also get automated invites to the
+    biweekly _Qualtran Sync_ meeting (below).
+
+*   Would you like to get more involved in Qualtran development? The biweekly _Qualtran Sync_
+    is a virtual face-to-face meeting of contributors to discuss everything from issues to
+    ongoing efforts, as well as to ask questions. Become a member of [`qualtran-dev`] to get
+    an automatic meeting invitation!
+
+[`qualtran-dev`]: https://groups.google.com/g/qualtran-dev
+
+### Issues and Pull Requests
+
+*   Do you have a feature request or want to report a bug? [Open an issue on
+    GitHub] to report it!
+*   Do you have a code contribution? Read our [contribution guidelines], then
+    open a [pull request]!
+
+[Open an issue on GitHub]: https://github.com/quantumlib/Qualtran/issues/new/choose
+[contribution guidelines]: https://github.com/quantumlib/Qualtran/blob/main/CONTRIBUTING.md
+[pull request]: https://help.github.com/articles/about-pull-requests
+
+## Citation<a name="how-to-cite"></a>
+
+When publishing articles or otherwise writing about Qualtran, please cite the following:
+
+```bibtex
 @misc{harrigan2024qualtran,
     title={Expressing and Analyzing Quantum Algorithms with Qualtran},
     author={Matthew P. Harrigan and Tanuj Khattar
         and Charles Yuan and Anurudh Peduri and Noureldin Yosri
         and Fionn D. Malone and Ryan Babbush and Nicholas C. Rubin},
     year={2024},
     eprint={2409.04643},
+    archivePrefix={arXiv},
+    primaryClass={quant-ph},
     doi={10.48550/arXiv.2409.04643},
     url={https://arxiv.org/abs/2409.04643},
 }
 ```
+
+## Contact
+
+For any questions or concerns not addressed here, please email quantum-oss-maintainers@google.com.
+
+## Disclaimer
+
+This is not an officially supported Google product.
+This project is not eligible for the [Google Open Source Software Vulnerability Rewards
+Program](https://bughunters.google.com/open-source-security).
+
+Copyright 2025 Google LLC.
+
+<div align="center">
+  <a href="https://quantumai.google">
+    <img width="15%" alt="Google Quantum AI"
+         src="https://raw.githubusercontent.com/quantumlib/Qualtran/refs/heads/main/docs/_static/quantum-ai-vertical.svg">
+  </a>
+</div>

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/notebook_specs.py

@@ -92,6 +92,9 @@
 import qualtran.bloqs.gf_arithmetic.gf2_inverse
 import qualtran.bloqs.gf_arithmetic.gf2_multiplication
 import qualtran.bloqs.gf_arithmetic.gf2_square
+import qualtran.bloqs.gf_poly_arithmetic.gf2_poly_add
+import qualtran.bloqs.gf_poly_arithmetic.gf2_poly_add_k
+import qualtran.bloqs.gf_poly_arithmetic.gf_poly_split_and_join
 import qualtran.bloqs.hamiltonian_simulation.hamiltonian_simulation_by_gqsp
 import qualtran.bloqs.mcmt.and_bloq
 import qualtran.bloqs.mcmt.controlled_via_and
@@ -578,6 +581,8 @@
             qualtran.bloqs.gf_arithmetic.gf2_multiplication._MULTIPLY_BY_CONSTANT_MOD_DOC,
             qualtran.bloqs.gf_arithmetic.gf2_multiplication._MULTIPLY_POLY_BY_ONE_PLUS_XK_DOC,
             qualtran.bloqs.gf_arithmetic.gf2_multiplication._BINARY_POLYNOMIAL_MULTIPLICATION_DOC,
+            qualtran.bloqs.gf_arithmetic.gf2_multiplication._GF2_SHIFT_RIGHT_MOD_DOC,
+            qualtran.bloqs.gf_arithmetic.gf2_multiplication._GF2_MUL_DOC,
         ],
     ),
     NotebookSpecV2(
@@ -602,6 +607,29 @@
     ),
 ]
 
+GF_POLY_ARITHMETIC = [
+    # --------------------------------------------------------------------------
+    # -----   Polynomials defined over Galois Fields (GF) Arithmetic    --------
+    # --------------------------------------------------------------------------
+    NotebookSpecV2(
+        title='Polynomials over GF($p^m$) - Split and Join',
+        module=qualtran.bloqs.gf_poly_arithmetic.gf_poly_split_and_join,
+        bloq_specs=[
+            qualtran.bloqs.gf_poly_arithmetic.gf_poly_split_and_join._GF_POLY_SPLIT_DOC,
+            qualtran.bloqs.gf_poly_arithmetic.gf_poly_split_and_join._GF_POLY_JOIN_DOC,
+        ],
+    ),
+    NotebookSpecV2(
+        title='Polynomials over GF($2^m$) - Add Constant',
+        module=qualtran.bloqs.gf_poly_arithmetic.gf2_poly_add_k,
+        bloq_specs=[qualtran.bloqs.gf_poly_arithmetic.gf2_poly_add_k._GF2_POLY_ADD_K_DOC],
+    ),
+    NotebookSpecV2(
+        title='Polynomials over GF($2^m$) - Addition',
+        module=qualtran.bloqs.gf_poly_arithmetic.gf2_poly_add,
+        bloq_specs=[qualtran.bloqs.gf_poly_arithmetic.gf2_poly_add._GF2_POLY_ADD_DOC],
+    ),
+]
 
 ROT_QFT_PE = [
     # --------------------------------------------------------------------------
@@ -933,6 +961,7 @@
     ('Arithmetic', ARITHMETIC),
     ('Modular Arithmetic', MOD_ARITHMETIC),
     ('GF Arithmetic', GF_ARITHMETIC),
+    ('Polynomials over Galois Fields', GF_POLY_ARITHMETIC),
     ('Rotations', ROT_QFT_PE),
     ('Block Encoding', BLOCK_ENCODING),
     ('Optimization', OPTIMIZATION),

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}"
+                )