Merge branch 'main' into patch-1

Author: mpharrigan

.gemini/config.yaml

@@ -0,0 +1,28 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+# Summary: configure Gemini Code Assist (https://codeassist.google/).
+# See https://github.com/marketplace/gemini-code-assist for more info.
+
+have_fun: false
+code_review:
+  disable: false
+  comment_severity_threshold: HIGH
+  max_review_comments: -1
+  pull_request_opened:
+    help: false
+    summary: false
+    code_review: true
+    include_drafts: false
+ignore_patterns: []

check/format-incremental

@@ -95,13 +95,13 @@ if (( ${#format_files[@]} == 0 )); then
     exit 0
 fi
 
-flynt_args=("--quiet" "-f")
-if (( only_print == 1 )); then
-    flynt_args+=("--dry-run")
-fi
-
-flynt "${format_files[@]}" "${flynt_args[@]}"
-FLYNTSTATUS=$?
+#flynt_args=("--quiet" "-f")
+#if (( only_print == 1 )); then
+#    flynt_args+=("--dry-run")
+#fi
+#
+#flynt "${format_files[@]}" "${flynt_args[@]}"
+FLYNTSTATUS=0
 
 isort_args=()
 if (( only_print == 1 )); then

dev_tools/dump-bloq-manifest.py

@@ -0,0 +1,173 @@
+#  Copyright 2025 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  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.
+
+"""
+Script to dump a manifest of all bloq classes and bloq examples.
+
+This script finds all Bloq classes and examples in the library, serializes the examples
+to their objectstring representation, and writes the list of class names and
+example objectstrings to `qualtran/bloqs/manifest.py`.
+
+See `qualtran.l1.load_objectstring()` to load bloq objects from these strings.
+"""
+
+from functools import cached_property
+from typing import List, Tuple
+
+from attrs import frozen
+from qualtran_dev_tools.bloq_finder import get_bloq_classes, get_bloq_examples
+from qualtran_dev_tools.git_tools import get_git_root
+
+from qualtran import Bloq
+from qualtran.l1 import eval_cvalue_node, parse_objectstring, to_cobject_node
+from qualtran.l1.nodes import CArgNode, CObjectNode, LiteralNode
+
+MAXLEN = 300
+"""If the objectstring is too long, we make the executive decision to truncate it."""
+
+COPYRIGHT_NOTICE = """#  Copyright 2026 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  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."""
+
+
+@frozen
+class BloqExampleListItem:
+    """Formatting a bloq example and its serialized form.
+
+    Attributes:
+        bloq: The bloq instance from the example.
+        bloq_example_name: The name of the bloq example.
+        cobject_node: The CObjectNode representing the serialized bloq.
+    """
+
+    bloq: Bloq
+    bloq_example_name: str
+    cobject_node: CObjectNode
+
+    @cached_property
+    def objectstring(self) -> str:
+        """Returns the canonical string representation of the CObjectNode."""
+        return self.cobject_node.canonical_str()
+
+    def maybe_commented_out(self, be_column_width: int = 30) -> Tuple[str, str, str]:
+        """Generates a string representation for the manifest, potentially commented out.
+
+        This method checks if the object string is too long, unparsable, unloadable, or
+        if the re-loaded bloq is unequal to the original. If any of these conditions are met,
+        it returns a commented-out string with a reason. Otherwise, it returns the
+        executable string representation.
+
+        Args:
+            be_column_width: The width of the column for the bloq example name for nicer formatting.
+
+        Returns:
+            manifest_entry_str: The string to be written to the manifest (possibly commented out).
+            reason: A reason string if it was commented out (empty otherwise).
+            reason_details: Detailed error message if applicable (empty otherwise).
+        """
+        quoted_be = f"'{self.bloq_example_name}',"
+        be = f'{quoted_be:{be_column_width}}'
+        be2 = f'{quoted_be:{be_column_width+2}}'
+
+        if len(self.objectstring) > MAXLEN:
+            trunc = repr(self.objectstring)[:120] + '...'
+            return f'# ({be}{trunc}', 'too long', ''
+
+        try:
+            node = parse_objectstring(self.objectstring)
+        except Exception as e:  # pylint: disable=broad-except
+            return f'# ({be}{self.objectstring!r}),', 'unparsable', str(e)
+
+        try:
+            bloq = eval_cvalue_node(node, safe=False)
+        except Exception as e:  # pylint: disable=broad-except
+            return f'# ({be}{self.objectstring!r}),', 'unloadable', str(e)
+
+        if bloq != self.bloq:
+            return f'# ({be}{self.objectstring!r}),', 'unequal', ''
+
+        return f'({be2}{self.objectstring!r}),', '', ''
+
+
+def main():
+    """Main entry point for the script.
+
+    Finds all bloq classes and examples, processes them, and writes the
+    `BLOQ_CLASS_NAMES` and `BLOQ_EXAMPLE_OBJECTSTRINGS` lists to
+    `qualtran/bloqs/manifest.py`.
+    """
+    bcs = get_bloq_classes()
+    names = sorted(bc._class_name_in_pkg_() for bc in bcs)
+
+    bes = get_bloq_examples()
+    items: List[BloqExampleListItem] = []
+    for be in bes:
+        bloq = be.make()
+        try:
+            cobject_node = to_cobject_node(bloq)
+            assert isinstance(cobject_node, CObjectNode)
+        except Exception as e:  # pylint: disable=broad-except
+            cobject_node = CObjectNode(
+                name=bloq._class_name_in_pkg_(), cargs=[CArgNode(None, LiteralNode(str(e)))]
+            )
+        items.append(
+            BloqExampleListItem(bloq=bloq, bloq_example_name=be.name, cobject_node=cobject_node)
+        )
+
+    items = sorted(items, key=lambda x: x.objectstring)
+    include_commented_out = True
+    be_objectstrings = []
+    for item in items:
+        serstr, reason, details = item.maybe_commented_out()
+
+        if (not reason) or include_commented_out:
+            be_objectstrings.append(serstr)
+
+        if reason:
+            reason = f'({reason})'
+            print(f"Skipping {reason:20s} {serstr}")
+
+        if details:
+            print(f'         {"":20s} ->', details)
+
+    reporoot = get_git_root()
+    with (reporoot / 'qualtran/bloqs/manifest.py').open('w') as f:
+        f.write(COPYRIGHT_NOTICE)
+        f.write('\n\n')
+        f.write('# This file is autogenerated\n')
+        f.write('# See dev_tools/dump-bloq-manifest.py\n')
+        f.write('# fmt: off\n\n')
+        f.write('BLOQ_CLASS_NAMES = [\n')
+        f.write('\n'.join([f'    "{name}",' for name in names]))
+        f.write('\n]\n')
+
+        f.write('\n')
+
+        f.write('BLOQ_EXAMPLE_OBJECTSTRINGS = [\n')
+        f.write('\n'.join([f'    {objstr}' for objstr in be_objectstrings]))
+        f.write('\n]\n')
+
+
+if __name__ == '__main__':
+    main()

dev_tools/qualtran_dev_tools/all_call_graph.py

@@ -13,6 +13,7 @@
 #  limitations under the License.
 
 """Generate the library-wide call graph from all bloq examples."""
+
 import logging
 import warnings
 from typing import Iterable

dev_tools/qualtran_dev_tools/make_reference_docs/_components/render_docstring.py

@@ -167,7 +167,7 @@ def _write_yields(f, part: DocstringSectionYields, level: int):
         f.write('\n')
 
     else:
-        subpart: DocstringYield
+        param: DocstringYield
         for param in part.value:
             pname = param.name if param.name else 'yld'
             f.write(f'{pname}\n')

dev_tools/qualtran_dev_tools/make_reference_docs/_make.py

@@ -11,6 +11,8 @@
 #  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.
+
+# ruff: noqa: E402
 import ast
 import warnings
 from collections import defaultdict
@@ -76,7 +78,12 @@
 ]
 MINIMAL = True
 
-DEFINED_IN_CONTAINER_EXCEPTIONS = ['qualtran.dtype', 'qualtran.exception', 'qualtran.cirq_interop']
+DEFINED_IN_CONTAINER_EXCEPTIONS = [
+    'qualtran.dtype',
+    'qualtran.exception',
+    'qualtran.cirq_interop',
+    'qualtran.l1.nodes',
+]
 
 
 def _get_all_aliases(obj: Union[griffe.Object, griffe.Alias]) -> Set[str]:

dev_tools/qualtran_dev_tools/notebook_execution.py

@@ -215,7 +215,7 @@ def __call__(self, nb_rel_path: Path, sourceroot: Path) -> _NotebookRunResult:
         start = time.time()
         err = execute_and_export_notebook(paths)
         end = time.time()
-        print(f"Exported {nb_rel_path} in {end-start:.2f} seconds.")
+        print(f"Exported {nb_rel_path} in {end - start:.2f} seconds.")
         return _NotebookRunResult(paths.nb_in, err, duration_s=end - start)
 
 

dev_tools/qualtran_dev_tools/shell_tools.py

@@ -91,7 +91,9 @@ def run(
         if abbreviate_non_option_arguments:
             cmd_desc = abbreviate_command_arguments_after_switches(cmd_desc)
         print("run:", cmd_desc, file=sys.stderr)
-    return subprocess.run(args, **subprocess_run_kwargs)  # pylint: disable=subprocess-run-check
+    return subprocess.run(  # pylint: disable=subprocess-run-check # noqa: PLW1510
+        args, **subprocess_run_kwargs
+    )
 
 
 def output_of(args: Union[str, List[str]], **kwargs) -> str:

docs/bloq_infra.rst

@@ -55,4 +55,5 @@ types (``Register``), and algorithms (``CompositeBloq``).
    drawing/musical_score.ipynb
    drawing/drawing_call_graph.ipynb
    simulation/xcheck_classical_quimb.ipynb
+   l1/L1-Objectstring.ipynb
    Autodoc.ipynb

pyproject.toml

@@ -93,7 +93,8 @@ typing = [
 ]
 
 lint = [
-   "pylint~=3.3.1",
+    "pylint~=3.3.1",
+    "ruff~=0.15.0",
 
     # for checking _test.py files
     "pytest",
@@ -111,6 +112,7 @@ format = [
     "flynt~=0.60",
     "black~=24.8.0",
     "isort~=5.10.1",
+    "ruff~=0.15.0",
 ]
 
 doc = [
@@ -131,6 +133,72 @@ skip-string-normalization = true
 skip-magic-trailing-comma = true
 exclude = "qualtran/protos/*"
 
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+exclude = [
+    "qualtran/protos/*",
+    "*_pb2.py",
+    "*.ipynb",
+]
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle
+    "F", # pyflakes
+    # "I", # isort (disabled until we switch formatters)
+    "W", # pycodestyle warnings
+    "PL", # pylint
+]
+ignore = [
+    # From the default ruleset:
+    "E741", # ambiguous variable name 'l', 'O', or 'I'
+    "E743", # ambiguous function definition
+    "E731", # assigning a lambda expression to a variable
+
+    # Handled by the formatter
+    "E501", # line too long (let ruff format handle this)
+    "W291", # trailing whitespace
+    "W293", # blank line contains whitespace
+
+    # We productively use these
+    "PLC0415", # import outside top-level
+    "PLW2901", # loop variable overwritten
+    "PLC0206", # Extracting value from dictionary without calling .items()
+    "PLW0406", # Module import itself
+
+    # Pylint 'refactor' rules
+    "PLR0913", # Too many arguments
+    "PLR0912", # Too many branches
+    "PLR0915", # Too many statements
+    "PLR0914", # Too many local variables
+    "PLR2004", # Magic value used in comparison
+    "PLR0911", # Too many return statements
+    "PLR1704", # Redefining argument with the local name
+    "PLR1714", # Consider merging multiple comparisons
+    "PLR1730", # replace if with min, max. Can be enabled.
+
+    # Might be enabled at some point
+    "PLR0402" # Prevalent in the rotation_synthesis submodule.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    # Ruff wants us to redundantly re-export symbols in __init__.py files, but the
+    # automated fix isn't in the stable release yet.
+    "F401", # Unused import
+]
+
+
+[tool.ruff.lint.isort]
+order-by-type = false
+force-to-top = []
+split-on-trailing-comma = false
+
+[tool.ruff.format]
+quote-style = "preserve"
+skip-magic-trailing-comma = true
+
 [tool.isort]
 profile = 'black'
 order_by_type = false