Decomp/qref decomposable interface by yde773786 · Pull Request #3161 · PennyLaneAI/catalyst

yde773786 · 2026-08-28T14:42:41Z

Context:

The DecomposableGate Interface was introduced to provide a generic interface for decomposition of quantum gates. We want to migrate the graph-decomposition and decompose-lowering passes to reference semantics, but this will require the DecomposableGate interface be implemented for reference semantics gates

Description of the Change:

The DecomposableGate Interface is added for the Qref dialect, and the decomposable gates inherit this interface appropriately. The format used is identical to how the interface is defined and used in the Quantum dialect.

gtest for this interface addition added.

Using MLIR types in the GOID as defined here is used.
A corresponding test that should fail with the previous (python style types in GOID) is also added to the Qref dialect's DecomposableGate Interface gtests.

Benefits:

Unblocks implementation of graph-decomposition and decompose-lowering passes in reference semantics.

Possible Drawbacks:

Code duplication exists with the Quantum dialect's implementation of DecomposableGate. Modifications need to be applied in both places.

Related GitHub Issues:

[sc-128397]

codecov · 2026-08-28T15:42:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.65%. Comparing base (9d2bd1d) to head (bffe31d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3161   +/-   ##
=======================================
  Coverage   95.65%   95.65%           
=======================================
  Files         177      177           
  Lines       21011    21011           
  Branches     2117     2117           
=======================================
  Hits        20098    20098           
  Misses        725      725           
  Partials      188      188

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

dime10 · 2026-08-28T15:54:06Z

We want to migrate the graph-decomposition and decompose-lowering passes to reference semantics

@kipawaa Could you provide more info on this?

paul0403 · 2026-08-28T16:11:06Z

We want to migrate the graph-decomposition and decompose-lowering passes to reference semantics

@kipawaa Could you provide more info on this?

There's at least two points in the current graph decomp pass that's very inefficient.

It is performing the infamous "value semantics walk back" to determine what qubits have what extract indices when inlining the rules back into the actual program's gates.
The rules are littered with stablehlo ops everywhere. It is because in the rules' arguments, we are manually taking in extract indices packed in a tensor argument, and then in the rules' bodies stablehlo.extract these qubit extract indices and quantum.extract. Linking the whole file: a bit hard to isolate a single line to link to

Issue 1 I'm very confident is non existent if the pass were in reference semantics. So at least there's that. We have too many separate implementations of the walkback, and each of these must be maintained separately (e.g. bug found in #3156 ). Any pass that is walking back should just be in reference semantics since the "walkback" in the semantics conversion pass is the most tested!

Issue 2 might be more tricky. The rules are generated from the frontend as quantum subroutines, which takes in wires as (a tensor of) integers (aka "extract indices). I would really love it if the frontend can generate rules that act on qref.bit directly instead of extract indices. That is its own problem; but in a world where we have support for that in the frontend, the decompose lowering pass would need to be in reference semantics to enjoy the benefit. The inlining of the rules back into the user circuit would not need to worry about any qubit dataflow: just grab the qref.bit SSA value on the user program's gate, replace some uses and we're done! This might also be possible in value semantics but it will be more involved.

kipawaa · 2026-08-28T16:18:04Z

We want to migrate the graph-decomposition and decompose-lowering passes to reference semantics

@kipawaa Could you provide more info on this?

@paul0403 Made the major points above, but to add to this is that the on-demand rules (and truly all rules) are initially lowered in reference semantics and then have to be converted to value semantics for compatibility with the passes. I think it would be nice to migrate the entire graph-decomps system to reference semantics for all of these reasons. We could then place the rules in their own module separate from the user circuit, and this way they can be isolated from the user program and remain in reference semantics throughout their lifetime.

kipawaa · 2026-08-31T13:14:31Z

Nice work @yde773786! Sorry to spring this on you right after you finished the work, but could you update to accommodate controls that were introduced in #3127?

yde773786 · 2026-08-31T15:49:54Z

@kipawaa

Added the tests. I found no need to make any changes, so ported identical functionality/tests from quantum to qref for the above.

Did want to bring attention to this test again, though (since it's a test that is not present in the quantum dialect). It's for testing the N types to 1 GOID bug that 3158 fixes and could be added to the Quantum dialect as well.

kipawaa

Great work, thanks @yde773786!

dime10 · 2026-09-09T21:08:07Z

+}
+
+template <typename T, typename PrintFunc>
+void printSortedMap(const llvm::StringMap<T> &map, llvm::raw_string_ostream &ss,


wrapModifiers, printSortedMap, printDynamicShape and printWireLens are all copies that are not specific to the either dialect, and should be factored out

I think this applies here as well.

Since it's tracked, let's tackle it in a follow up PR.

I don't think an interface is necessary here, this is just about factoring out duplicate helper functions. But please do tackle this in a follow up!

I think the idea is to put the interface itself in the Catalyst dialect, which means all these helpers would exist just once in Catalyst dialect too.

Although I don't necessarily agree with putting quantum things in Catalyst, I can't really think of a better place 😅

Yeah Catalyst doesn't sound like the right place for a quantum related interface, it should just go into quantum. Regarding the helpers, if they are moved to the interface that's fine too, I'm just saying all that was necessary here was moving them to a header from which they can be imported into both dialects.

paul0403 · 2026-09-14T19:30:33Z

I am branching off this PR to migrate --decompose-lowering to reference semantics.

maliasadi

Looks good! Thanks @yde773786

… for gates that can be decomposable. Ensure closely followed implementation as in Quantum dialect

… decomposableGateInterface in Quantum dialect

… GOID mapping

…lemented

Changelog generalized to include all PRs that implement DecomposableGateInterface across dialects Co-authored-by: Ali Asadi <10773383+maliasadi@users.noreply.github.com>

…ate required in all corresponding DecompGate Interfaces

…es for 1 param

… GOID, into QRef. Update tests as well.

Co-authored-by: Ali Asadi <10773383+maliasadi@users.noreply.github.com>

yde773786 requested review from a team and kipawaa August 28, 2026 14:47

yde773786 marked this pull request as ready for review August 28, 2026 14:47

yde773786 force-pushed the decomp/qref-decomposable-interface branch 2 times, most recently from 8af2e84 to ebf9f03 Compare August 31, 2026 15:52

kipawaa approved these changes Sep 4, 2026

View reviewed changes

Comment thread mlir/unittests/QRef/TestDecomposableGateInterface.cpp

Comment thread mlir/unittests/QRef/TestDecomposableGateInterface.cpp Outdated

yde773786 force-pushed the decomp/qref-decomposable-interface branch from ebf9f03 to 3fd9dd7 Compare September 9, 2026 18:40

dime10 reviewed Sep 10, 2026

View reviewed changes

maliasadi reviewed Sep 10, 2026

View reviewed changes

Comment thread doc/releases/changelog-dev.md Outdated

Comment thread mlir/lib/QRef/IR/QRefInterfaces.cpp

Comment thread mlir/lib/QRef/IR/QRefInterfaces.cpp

Comment thread mlir/unittests/QRef/TestDecomposableGateInterface.cpp

Comment thread mlir/unittests/QRef/TestDecomposableGateInterface.cpp

yde773786 force-pushed the decomp/qref-decomposable-interface branch from 16f4b7b to 1427346 Compare September 14, 2026 19:59

yde773786 mentioned this pull request Sep 14, 2026

Create a common DecomposableGateInterface across dialects. #3223

Open

yde773786 requested a review from paul0403 September 14, 2026 21:46

kipawaa requested a review from maliasadi September 15, 2026 19:29

maliasadi reviewed Sep 15, 2026

View reviewed changes

Comment thread doc/releases/changelog-dev.md Outdated

maliasadi approved these changes Sep 15, 2026

View reviewed changes

yde773786 added 7 commits September 16, 2026 10:35

Add the DecomposableGate interface for Qref, and extend the interface…

ec0e635

… for gates that can be decomposable. Ensure closely followed implementation as in Quantum dialect

added tests for qref decomposable gate interface. 1:1 testing as with…

b19dbd4

… decomposableGateInterface in Quantum dialect

Add failing test where type mismatch still maps to same GOID

ffa9703

Applied fix to printType to use MLIR types in GOID and prevent N to 1…

c300daa

… GOID mapping

formatting changes

20313c6

Append changelog under locations where DecomposableInterface is imp…

80ca8e4

…lemented

Added control and adjoint uniquification in GOID

a06a861

yde773786 and others added 8 commits September 16, 2026 10:35

remove unneeded comment

47d0201

Apply suggestion from @maliasadi

072ef12

Changelog generalized to include all PRs that implement DecomposableGateInterface across dialects Co-authored-by: Ali Asadi <10773383+maliasadi@users.noreply.github.com>

Update docstring in GOID computing class on frontend to notify of upd…

4e8ba10

…ate required in all corresponding DecompGate Interfaces

getDynamicShape/printDynamicShape tested scenario with multiple index…

3665e5b

…es for 1 param

Use new format of goid with static data's dictattr being printed into…

4eecd82

… GOID, into QRef. Update tests as well.

format

797ca55

Update doc/releases/changelog-dev.md

daaad19

Co-authored-by: Ali Asadi <10773383+maliasadi@users.noreply.github.com>

updated changelog back to correct formatting and remove redundancies

bffe31d

yde773786 force-pushed the decomp/qref-decomposable-interface branch from ecf06c6 to bffe31d Compare September 16, 2026 14:38

paul0403 approved these changes Sep 16, 2026

View reviewed changes

paul0403 merged commit 3f3e648 into main Sep 16, 2026
38 checks passed

paul0403 deleted the decomp/qref-decomposable-interface branch September 16, 2026 15:02

yde773786 mentioned this pull request Sep 18, 2026

Making DecomposableGate interface a common interface across dialects #3247

Open

Conversation

yde773786 commented Aug 28, 2026

Uh oh!

codecov Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

dime10 commented Aug 28, 2026

Uh oh!

paul0403 commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

kipawaa commented Aug 31, 2026

Uh oh!

yde773786 commented Aug 31, 2026

Uh oh!

kipawaa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dime10 Sep 9, 2026

Choose a reason for hiding this comment

Uh oh!

yde773786 Sep 14, 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!

paul0403 Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

dime10 Sep 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!

paul0403 Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

paul0403 Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

dime10 Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

paul0403 commented Sep 14, 2026

Uh oh!

Uh oh!

maliasadi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codecov Bot commented Aug 28, 2026 •

edited

Loading

paul0403 commented Aug 28, 2026 •

edited

Loading

kipawaa commented Aug 28, 2026 •

edited

Loading

yde773786 Sep 14, 2026 •

edited

Loading

dime10 Sep 16, 2026 •

edited

Loading