Graph decompose frontend by kipawaa · Pull Request #2568 · PennyLaneAI/catalyst

kipawaa · 2026-03-10T20:39:30Z

Context:

Description of the Change:
Provides the interface for the graph-decompose pass.

Benefits:
graph decomposition occurs in C++ at runtime, using precompiled builtin rules and jit compiled user rules.

Possible Drawbacks:
N/A

Related GitHub Issues:

[sc-113641]
[sc-101036]

…neAI/catalyst into graph-decompose-frontend

maliasadi

Thanks @kipawaa!

maliasadi · 2026-03-16T18:39:25Z

 from catalyst.compiler import _options_to_cli_flags, _quantum_opt
 from catalyst.passes.pass_api import PassPipelineWrapper
 from catalyst.utils.exceptions import CompileError
+from catalyst.utils.precompile_decomposition_rules import BYTECODE_FILE_NAME, DEFAULT_RULE_DIR


could we create and import BYTECODE_FILE_PATH instead of BYTECODE_FILE_NAME, DEFAULT_RULE_DIR?

This is more related to this PR, but I'll implement it there so that we can sync it up the branches. I think it makes sense to do this after merging this branch though, to reduce the amount of syncing required.

maliasadi · 2026-03-16T18:42:27Z

+    gate_set: Iterable,
+    fixed_decomps: dict | None = None,
+    alt_decomps: dict | None = None,
+    rule_path: Path = DEFAULT_RULE_DIR / BYTECODE_FILE_NAME,


Probably add builtin, standard or something else to the name of this optional kwarg to better convey the use case:

Suggested change

rule_path: Path = DEFAULT_RULE_DIR / BYTECODE_FILE_NAME,

builtin_rule_path: Path = DEFAULT_RULE_DIR / BYTECODE_FILE_NAME,

This is also a dev utility and it's not supposed to be used by users.

I changed the name to _builtin_rule_path here - I think having this parameter around for a bit longer to allow different rule caches in development and testing might be useful, but I'm open to removing it if you think it should not be exposed at all.

maliasadi · 2026-03-16T18:49:06Z

+        )
+
+    if not isinstance(gate_set, dict):
+        gate_set = {op.__name__: 1.0 for op in gate_set}


Need to update the logic to support string gates too. From PL, users can provide a mix of PL Op types and Op strings: https://github.com/PennyLaneAI/pennylane/blob/494cd943c4ce675f8c392a9b8fb98626d1b78c02/pennylane/decomposition/gate_set.py#L24

updated to use the to_name utility from PL, so we should have near-identical support. I've also added some tests for this.

github-actions · 2026-03-16T19:10:18Z

Hello. You may have forgotten to update the changelog!
Please edit doc/releases/changelog-dev.md on your branch with:

A one-to-two sentence description of the change. You may include a small working example for new features.
A link back to this PR.
Your name (or GitHub username) in the contributors section.

maliasadi · 2026-03-16T19:18:11Z

+def graph_decomposition(
+    qnode=None,
+    *,
+    gate_set: Iterable,


valid types for gate_set for the reference: https://github.com/PennyLaneAI/pennylane/blob/494cd943c4ce675f8c392a9b8fb98626d1b78c02/pennylane/transforms/decompose.py#L378

long-term, we need compatibility with Gateset.

I updated the types here, not sure about supporting Gateset at the moment but it looks as though adding a __dict__ method to gateset that we can use internally here would be quite reasonable.

kipawaa · 2026-03-16T20:46:26Z

Note that CI won't pass here since it's currently broken in mlirbc-decomp-rules, which is upstream of this branch.

maliasadi

Happy to approve! We can address the remaining updates in the pass PR.

dime10 · 2026-03-17T17:44:35Z

        with pytest.raises(check=ValueError, match="Requested specs levels 2, 3"):
            qml.specs(no_passes, level=[2, 3])()

+    @pytest.mark.xfail(reason="pending on specs fix")


It's good practice to provide a pr, issue, or ticket reference so that anyone can check later whether the referenced fix has been completed or not

dime10 · 2026-03-17T17:45:53Z

The plan is to check the file into the git tree now?

dime10 · 2026-03-17T17:48:43Z

+    _builtin_rule_path: Path = DEFAULT_RULE_DIR / BYTECODE_FILE_NAME,
+):
+    R"""
+    Specify that the ``-graph-decomposition`` MLIR compiler pass for applying optimal gate


Optimality is a strong claim, imo we should be careful with such language. Maybe "optimal gate decompositions" could be interpreted in different ways, but I don't think our rules themselves are necessary optimal, the only thing we can guarantee is that we choose the optimal path from the given set of rules.

dime10 · 2026-03-17T17:52:44Z

+        To instead view the optimized circuit, the MLIR must be viewed
+        after the ``"QuantumCompilationStage"`` stage via the
+        :func:`~.get_compilation_stage` function.


We have inspection tools now beyond just looking at the MLIR, including qml.specs and catalyst.draw_graph

**Context:** The objective is to develop a high-performance, hybrid decomposition framework that further migrates the graph-decomposition logic from Python to the native MLIR compiler. The new framework needs to adhere to four pillars: 1. We will migrate the `GraphDecomposition` build and solver logic from Python into C++ #2578. By co-locating the solver with the decomposition-rule rewrite MLIR pass into a `graph-decomposition` system at MLIR, we enable late-stage circuit rewrites and multi-pass optimization cycles that were previously inaccessible in the frontend-only framework. 2. To minimize runtime latency, PL’s standard and built-in decomposition rules will be precompiled for release, and lazily re-compiled if necessary on import #2531 #2539. By treating built-in rules as static compiler assets rather than dynamic JIT targets, we try to eliminate the redundant capture and compilation overhead typically incurred during every workflow execution. 2. To maintain the flexibility of PL, the system will need to still support JIT compilation of rules. While standard rules are handled by the AOT backend, custom user-defined device rules will be resolved via a JIT fallback mechanism #2568. This is to ensure that researcher-defined gatesets and rules remain fully supported without requiring a full compiler re-build. 4. Short-term, a "PLxPR Guard" stage will handle edge cases before MLIR lowering, acting as a fallback until the C++ system offers full support. Compiler-incompatible operators and complex high-level templates (e.g., Subroutine/Template work) will continue to be handled/decomposed at the PLxPR level; so that the backend receives a valid, lowerable MLIR representation while deferring hardware-specific passes to MLIR/C++. This step is temporary and will be revisited aligned with the updates in the Operator class and the program capture mechanism for Symbolic Ops. **Benefits:** - Enable "late-stage" and iterative decomposition passes at MLIR with a C++ decomposition graph - Eliminate redundant compilation overhead of built-in decomposition rules during JIT compilation of workflows **Possible Drawbacks:** **Related GitHub Issues:** [sc-113535] [sc-113537] [sc-115445] --------- Co-authored-by: River McCubbin <river.mccubbin@xanadu.ai> Co-authored-by: Hong-Sheng Zheng <mathan0203@gmail.com> Co-authored-by: David Ittah <dime10@users.noreply.github.com>

maliasadi and others added 5 commits March 10, 2026 16:18

Update frontend

b53a2b9

initial implementation

2e060c0

kwargs to attr handling

b6c1e90

Merge branch 'graph-decompose-frontend' of https://github.com/PennyLa…

d900a88

…neAI/catalyst into graph-decompose-frontend

Fix the mssing OpBase in QecDialect

0b06097

kipawaa changed the base branch from main to graph-decompose-pass March 10, 2026 20:51

maliasadi and others added 11 commits March 10, 2026 16:56

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

6d7b4cc

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

bada998

pass options

06ed82a

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

386ce39

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

dfd602e

gate_set as dict

830a2f3

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

6845591

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

93a3ff8

Merge branch 'graph-decompose-pass' into graph-decompose-frontend

f6fb68d

add rules file option

08dcc69

test graph_decomposition lowering

2824f3a

maliasadi reviewed Mar 16, 2026

View reviewed changes

Comment thread frontend/test/lit/test_decomposition.py

maliasadi reviewed Mar 16, 2026

View reviewed changes

kipawaa marked this pull request as ready for review March 16, 2026 19:19

maliasadi reviewed Mar 16, 2026

View reviewed changes

Comment thread frontend/catalyst/passes/builtin_passes.py

maliasadi reviewed Mar 16, 2026

View reviewed changes

Comment thread frontend/catalyst/passes/builtin_passes.py

kipawaa added 6 commits March 16, 2026 15:58

rename bytecode dir param

ffac7d7

improve docstring

91a3fd5

handle string params

c488b72

match mlir casing

6539b14

test empty-dict

82c0343

missed to_name

6fbc066

added tests for string ops

c2be377

maliasadi approved these changes Mar 16, 2026

View reviewed changes

kipawaa merged commit 4ad39c7 into graph-decompose-pass Mar 16, 2026
38 of 40 checks passed

kipawaa deleted the graph-decompose-frontend branch March 16, 2026 21:55

maliasadi added this to the delightning milestone Mar 17, 2026

dime10 reviewed Mar 17, 2026

View reviewed changes

maliasadi mentioned this pull request Mar 17, 2026

[Base] The native-MLIR graph decomposition #2552

Merged

	rule_path: Path = DEFAULT_RULE_DIR / BYTECODE_FILE_NAME,
	builtin_rule_path: Path = DEFAULT_RULE_DIR / BYTECODE_FILE_NAME,

Conversation

kipawaa commented Mar 10, 2026 • edited by dime10 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maliasadi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Mar 16, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kipawaa Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kipawaa commented Mar 16, 2026

Uh oh!

maliasadi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kipawaa commented Mar 10, 2026 •

edited by dime10

Loading

kipawaa Mar 16, 2026 •

edited

Loading