Add `quantum.operator` to Catalyst [Operator2 work] by dime10 · Pull Request #2883 · PennyLaneAI/catalyst

dime10 · 2026-05-27T19:05:31Z

Provides the new MLIR operation for advanced quantum operators as defined by this ADR. The following is provided in this PR:

the operation definition
op verifiers
custom assembly syntax
integration with the ParametrizedGate interface

Future PRs will tackle:

updates to existing passes (if necesary)
reference-semantic version of the op + conversion
lowering to the op from the frontend

[sc-120860]

These will be tackled in a separate PR.

github-actions · 2026-05-27T19:05:44Z

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.

codecov · 2026-05-27T19:38:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.90%. Comparing base (9798aa3) to head (5937954).
⚠️ Report is 36 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2883      +/-   ##
==========================================
- Coverage   97.01%   96.90%   -0.11%     
==========================================
  Files         167      166       -1     
  Lines       18828    19008     +180     
  Branches     1768     1760       -8     
==========================================
+ Hits        18266    18420     +154     
- Misses        417      433      +16     
- Partials      145      155      +10

☔ 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.

Similar to qubit_map, a single param arg in python can map to multiple parameter SSA values (e.g. with pytrees), so we need a list here.

mudit2812 · 2026-05-29T20:40:58Z

+          Use this when the operator acts on a statically known set of wires. Qubits are
+          threaded through the op explicitly and can carry per-control values through
+          `in_ctrl_qubits` / `in_ctrl_values` (with matching `out_ctrl_qubits`).
+          This is the natural representation for fixed-arity gates and operators.


Generally, the number of inputs a mathematical operator acts on, in this case wires. Honestly we can just remove that sentence though:

Suggested change

This is the natural representation for fixed-arity gates and operators.

mudit2812

Looks great @dime10 . My only blocking comment is about testing invalid operators with the custom format

mudit2812 · 2026-06-01T17:38:26Z

+func.func @operator_basic_qubits(%q0 : !quantum.bit, %q1 : !quantum.bit) {
+    %o0, %o1 = "quantum.operator"(%q0, %q1) <{op_name = "basic_qubits", operandSegmentSizes = array<i32: 0, 0, 2, 0, 0, 0, 0, 0, 0>, resultSegmentSizes = array<i32: 2, 0, 0>}> : (!quantum.bit, !quantum.bit) -> (!quantum.bit, !quantum.bit)
+    return
+}
+
+//////////////////////
+// quantum.operator //
+//////////////////////


Suggested change

func.func @operator_basic_qubits(%q0 : !quantum.bit, %q1 : !quantum.bit) {

%o0, %o1 = "quantum.operator"(%q0, %q1) <{op_name = "basic_qubits", operandSegmentSizes = array<i32: 0, 0, 2, 0, 0, 0, 0, 0, 0>, resultSegmentSizes = array<i32: 2, 0, 0>}> : (!quantum.bit, !quantum.bit) -> (!quantum.bit, !quantum.bit)

return

}

//////////////////////

// quantum.operator //

//////////////////////

//////////////////////

// quantum.operator //

//////////////////////

func.func @operator_basic_qubits(%q0 : !quantum.bit, %q1 : !quantum.bit) {

%o0, %o1 = "quantum.operator"(%q0, %q1) <{op_name = "basic_qubits", operandSegmentSizes = array<i32: 0, 0, 2, 0, 0, 0, 0, 0, 0>, resultSegmentSizes = array<i32: 2, 0, 0>}> : (!quantum.bit, !quantum.bit) -> (!quantum.bit, !quantum.bit)

return

}

Just swapping test and the /////// comment

mudit2812 · 2026-06-01T17:43:30Z

+    // 7. Quantum register
+    if (getInQreg()) {
+        p.printNewline();
+        p << "quregs(" << getInQreg() << ") indices(";


I've always found the inconsistency of using both qureg and qreg to be kind of weird. Though I haven't seem qureg(s) for operand/result names or in assembly formats before, so maybe this should just be qregs?

Suggested change

p << "quregs(" << getInQreg() << ") indices(";

p << "qregs(" << getInQreg() << ") indices(";

This is purely stylistic though, so it's a non-blocking comment

Yeah I share the frustration. On the one hand, "qureg" is more analogous to "qubit", on the other it is perhaps a bit more unconventional? If we look at precedent in Catalyst, the official name in the type system is QubitType and QuregType (written as quantum.bit and quantum.reg in the IR, avoiding the conundrum). qreg does appear as certain op argument/result names though, and maybe as program variables.

mudit2812 · 2026-06-01T17:46:26Z

+
+func.func @operator_custom_with_decompositions(%q : !quantum.bit) {
+    %out = quantum.operator "custom_with_decompositions"() qubits(%q)
+      decompositions = [@decomp_a, @decomp_b]


I would've expected MLIR to have automatic verification about whether symbols exist in the IR or not. Should that be included in the verifier?

Good idea! There is also a SymbolUser interface, although I'd have to check to see if it allows for optional symbols

Gemini says yes, but I always take AI answers about MLIR with a grain of salt

mudit2812 · 2026-06-01T17:49:32Z

+
+// -----
+
+func.func @operator_invalid_forward_args_without_uid(%fwd : i64, %q0 : !quantum.bit, %q1 : !quantum.bit) {


Should there be assembly format tests for this and following tests?

I don't think we gain from testing invalid states in custom assembly necessarily, unless the custom assembly enables invalid states that the generic form doesn't allow?

kipawaa · 2026-06-02T13:42:38Z

+        The `quantum.operator` is a generic representation for arbitrary quantum operations
+        that cannot be expressed by the simpler `quantum.custom` op and don't have a dedicated
+        operation.
+        It's purpose is to represent high-level operations from frontend languages such as


Suggested change

It's purpose is to represent high-level operations from frontend languages such as

Its purpose is to represent high-level operations from frontend languages such as

paul0403 · 2026-06-05T19:23:38Z

Do you mind running make dialect-docs locally and commit the built doc files (just for QuantumOps.md is fine) too? It would be much easier to look at when reviewing 😅

Non blocking if it turns out to be too much trouble

dime10 · 2026-06-05T19:28:18Z

Do you mind running make dialect-docs locally and commit the built doc files (just for QuantumOps.md is fine) too? It would be much easier to look at when reviewing 😅

Great idea, thanks!

5937954, it hadn't been updated in a while, so there are few additional changes in there.

mudit2812 and others added 19 commits April 13, 2026 16:21

Add TemplateOp to quantum dialect

db96f14

format

aa6b52c

Merge branch 'main' into operator2.0

983a848

Add ctrl/adjoint support

08fb6f3

Small change to assembly format

0164cf9

Remove callopinterface

a2edeaa

Plxpr support

076bf35

Program capture works

d00a1dd

Change template

4cfa4dd

Merge branch 'main' into operator2.0

9e5e897

Pushing changes for op as data prototyping

8b48df9

Merge branch 'main' into operator2.0

e81efc3

Merge branch 'main' into operator2-base

4fc540b

Merge branch 'main' into HEAD

b0bd2a2

revert frontend changes

ab06e1d

These will be tackled in a separate PR.

fix getParams method usage (flyby)

9574f9a

Polish base operator definition

965e37c

Add custom syntax to op

d9f3060

Add final op members

4667eca

dime10 requested review from a team and mudit2812 May 27, 2026 19:05

dime10 added the compiler Pull requests that update the compiler label May 27, 2026

Add better builders

d549c23

dime10 force-pushed the operator2-base branch from b4c67e2 to d549c23 Compare May 27, 2026 19:11

dime10 added 2 commits May 27, 2026 16:12

Make param_map hold lists as well

656acbd

Similar to qubit_map, a single param arg in python can map to multiple parameter SSA values (e.g. with pytrees), so we need a list here.

add operation docstring

76af10e

mudit2812 reviewed May 29, 2026

View reviewed changes

mudit2812 reviewed Jun 1, 2026

View reviewed changes

Comment thread mlir/lib/Quantum/IR/QuantumOps.cpp

mudit2812 reviewed Jun 1, 2026

View reviewed changes

kipawaa reviewed Jun 2, 2026

View reviewed changes

Update quantum dialect docs

5937954

	p << "quregs(" << getInQreg() << ") indices(";
	p << "qregs(" << getInQreg() << ") indices(";


		// -----

		func.func @operator_invalid_forward_args_without_uid(%fwd : i64, %q0 : !quantum.bit, %q1 : !quantum.bit) {

	It's purpose is to represent high-level operations from frontend languages such as
	Its purpose is to represent high-level operations from frontend languages such as

Conversation

dime10 commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 27, 2026

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dime10 Jun 1, 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!

mudit2812 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!

dime10 Jun 1, 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!

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!

paul0403 commented Jun 5, 2026

Uh oh!

dime10 commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dime10 commented May 27, 2026 •

edited

Loading

codecov Bot commented May 27, 2026 •

edited

Loading

dime10 Jun 1, 2026 •

edited

Loading

dime10 Jun 1, 2026 •

edited

Loading

dime10 commented Jun 5, 2026 •

edited

Loading