✨ Add support for multi-controlled gates to ZX package by keefehuang · Pull Request #1380 · munich-quantum-toolkit/core

keefehuang · 2025-12-08T15:44:06Z

Description

Add CRZ, MCX, MCZ, MCRZ functionality to ZX package.
Add convenience addCCZ function as it avoids one additional Hardamard edge (optimizes it away).

Fixes #1357

Checklist:

The pull request only contains commits that are focused and relevant to this change.
I have added appropriate tests that cover the new/changed functionality.
~~I have updated the documentation to reflect these changes.~~
I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
~~I have added migration instructions to the upgrade guide (if needed).~~
The changes follow the project's style guidelines and introduce no new warnings.
The changes are fully tested and pass the CI checks.
I have reviewed my own code changes.

Add CRZ, MCX, MCZ, MCRZ functionality to ZX package.

codecov · 2025-12-08T15:47:56Z

Codecov Report

❌ Patch coverage is 89.28571% with 24 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/zx/FunctionalityConstruction.cpp	89.2%	24 Missing ⚠️

📢 Thoughts on this report? Let us know!

coderabbitai · 2025-12-08T15:59:35Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: d3660d93-4993-4fe6-b2cd-18279ec75af4

📥 Commits

Reviewing files that changed from the base of the PR and between 8031ec0 and 2966d29.

📒 Files selected for processing (1)

test/zx/test_zx_functionality.cpp

📝 Walkthrough

Summary by CodeRabbit

New Features
- Extended ZX package support for multi-controlled gates, including controlled and multi-controlled variants of phase, rotation (RX/RZ), swap, and logical operations. Enables transformation of more complex quantum circuits to and from ZX diagrams for optimization and analysis.

Walkthrough

Added protected helpers and implementations to construct controlled and multi-controlled ZX subgraphs (MCX/MCZ/MCRX/MCRZ/MCSWAP/MCRZZ/etc.), updated parser/transformability logic to dispatch these gates, expanded tests to assert equivalence for many multi-control variants, and updated the changelog. (≤50 words)

Changes

Cohort / File(s)	Summary
Header Declaration `include/mqt-core/zx/FunctionalityConstruction.hpp`	Added protected static declarations for new controlled/multi-controlled helpers (`addMcphase`, `addMcswap`, `addMcrzz`, `addCcz`, `addCrx`, `addMcrx`, `addCrz`, `addMcrz`, `addMcx`, `addMcz`) and renamed `addSwap` first parameter to `target1`.
Implementation `src/zx/FunctionalityConstruction.cpp`	Implemented multi-control decompositions and helpers (recursive/divide-and-conquer MCX, MCRZ/MCRX, MCRZZ, MCSWAP, CCZ, CRZ/CRX), updated `addSwap` param name and indexing, extended `parseOp` dispatch and `transformableToZX` rules for control/target counts, added `unconvertedPhase` passthrough, and standardized exception messages.
Tests `test/zx/test_zx_functionality.cpp`	Added `checkEquivalence` helper; refactored many tests to use it; added equivalence tests for CRZ/CCZ/MCX/MCZ/MCRZ/MCRX/MCSWAP/MCRzz/etc.; removed obsolete UnsupportedMultiControl expectation and added targeted unsupported-control tests.
Changelog `CHANGELOG.md`	Added Unreleased entry for multi-controlled gates support (PR `#1380`) and updated PR/contributor references.

Sequence Diagram(s)

sequenceDiagram
    participant Parser as parseOp
    participant FC as FunctionalityConstruction
    participant Anc as AncillaPool
    participant ZX as ZXDiagram

    Parser->>FC: receive qc::Operation (e.g., MCX / MCRZ / MCSWAP)
    FC->>FC: select decomposition by control/target counts
    alt needs ancilla
        FC->>Anc: request ancilla
        Anc-->>FC: provide ancilla
    end
    FC->>ZX: construct ZX subgraph via addMcx/addMcrz/addMcswap/addCcz/...
    ZX-->>Parser: ZXDiagram updated (subgraph appended)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

#1429 — Implements multi-controlled ZX construction routines and tests: this PR adds matching MC helper routines and test coverage.
#1650 — Requests an O(N) MCX construction: this PR implements a recursive (exponential) addMcx, so it directly relates to the performance/algorithmic improvement requested.

Suggested labels

enhancement, c++

Suggested reviewers

burgholzer

Poem

🐇 I hop through wires and phases bright,
I stitch MCX and CCZ by night,
Ancilla crumbs beneath my paws,
Spiders hum and weave the laws,
Hooray — the circuits gleam with light.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 1.45% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the primary change: adding support for multi-controlled gates to the ZX package.
Description check	✅ Passed	The description lists specific added functionality (CRZ, MCX, MCZ, MCRZ, addCCZ), references the fixed issue (`#1357`), and has a reasonably complete checklist with most items marked as done.
Linked Issues check	✅ Passed	The PR implements all requirements from issue `#1357`: multi-controlled X/Z support, CRZ/MCRZ implementations, proper ZX construction integration, and passing tests demonstrating correctness.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to multi-controlled gate support: header interface updates, implementations, tests, and changelog entries align with the stated objective.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/zx/FunctionalityConstruction.cpp (1)
872-896: Remove unreachable return statement.

The transformability checks correctly reflect the expanded multi-control support for RZ operations. However, line 896 contains an unreachable return false; statement since the preceding conditions exhaust all cases.

Apply this diff to remove the dead code:
     case qc::OpType::RZ:
       return true;
     default:
       return false;
     }
-    return false;
   }
 }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bdb2073 and 0ae2b61.

📒 Files selected for processing (3)

include/mqt-core/zx/FunctionalityConstruction.hpp (1 hunks)
src/zx/FunctionalityConstruction.cpp (5 hunks)
test/zx/test_zx_functionality.cpp (1 hunks)

🧰 Additional context used

🧠 Learnings (5)

📓 Common learnings

Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/test/Dialect/MQTOpt/Transforms/lift-measurements.mlir:269-288
Timestamp: 2025-10-09T13:20:11.483Z
Learning: In the MQT MLIR dialect, the `rz` gate should not be included in the `DIAGONAL_GATES` set for the `ReplaceBasisStateControlsWithIfPattern` because its operator matrix does not have the required shape | 1 0 | / | 0 x | for the targets-as-controls optimization. It is only included in `LiftMeasurementsAboveGatesPatterns` where the matrix structure requirement differs.

📚 Learning: 2025-10-09T13:20:11.483Z

Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/test/Dialect/MQTOpt/Transforms/lift-measurements.mlir:269-288
Timestamp: 2025-10-09T13:20:11.483Z
Learning: In the MQT MLIR dialect, the `rz` gate should not be included in the `DIAGONAL_GATES` set for the `ReplaceBasisStateControlsWithIfPattern` because its operator matrix does not have the required shape | 1 0 | / | 0 x | for the targets-as-controls optimization. It is only included in `LiftMeasurementsAboveGatesPatterns` where the matrix structure requirement differs.

Applied to files:

test/zx/test_zx_functionality.cpp
include/mqt-core/zx/FunctionalityConstruction.hpp
src/zx/FunctionalityConstruction.cpp

📚 Learning: 2025-12-08T14:55:43.880Z

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1264
File: mlir/lib/Dialect/Flux/IR/Modifiers/CtrlOp.cpp:78-100
Timestamp: 2025-12-08T14:55:43.880Z
Learning: In the Flux dialect (mlir/lib/Dialect/Flux/IR/Modifiers/CtrlOp.cpp), GPhaseOp is a zero-target operation (global phase). When a CtrlOp wraps a GPhaseOp, it only has control qubits and no targets. The CtrlInlineGPhase canonicalization pattern correctly produces outputs only for the positive controls, not targets.

Applied to files:

include/mqt-core/zx/FunctionalityConstruction.hpp
src/zx/FunctionalityConstruction.cpp

📚 Learning: 2025-10-09T13:13:51.224Z

Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/lib/Dialect/MQTOpt/Transforms/ReplaceBasisStateControlsWithIfPattern.cpp:171-180
Timestamp: 2025-10-09T13:13:51.224Z
Learning: In MQT Core MLIR, UnitaryInterface operations guarantee 1-1 correspondence between input and output qubits in the same order. When cloning or modifying unitary operations (e.g., removing controls), this correspondence is maintained by construction, so yielding getAllInQubits() in else-branches matches the result types from the operation's outputs.

Applied to files:

src/zx/FunctionalityConstruction.cpp

📚 Learning: 2025-12-08T12:44:05.874Z

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1264
File: mlir/lib/Dialect/Quartz/IR/Modifiers/CtrlOp.cpp:60-70
Timestamp: 2025-12-08T12:44:05.874Z
Learning: In the Quartz dialect (mlir/lib/Dialect/Quartz/IR/Modifiers/CtrlOp.cpp), negative controls are not supported at the current stage. The RemoveTrivialCtrl pattern correctly only checks getNumPosControls() when determining if a CtrlOp should be removed.

Applied to files:

src/zx/FunctionalityConstruction.cpp

🧬 Code graph analysis (2)

test/zx/test_zx_functionality.cpp (2)

include/mqt-core/zx/FunctionalityConstruction.hpp (2)

qc (39-39)

qc (50-50)

src/zx/FunctionalityConstruction.cpp (2)

buildFunctionality (787-804)

buildFunctionality (787-788)

src/zx/FunctionalityConstruction.cpp (2)

src/zx/Rational.cpp (1)

PiRational (21-45)

src/ir/operations/OpType.cpp (2)

toString (21-35)

toString (21-21)

🪛 GitHub Check: 🇨‌ Lint / 🚨 Lint

src/zx/FunctionalityConstruction.cpp

[warning] 388-388: src/zx/FunctionalityConstruction.cpp:388:13 [cppcoreguidelines-init-variables]
variable 'anc' is not initialized

[warning] 384-384: src/zx/FunctionalityConstruction.cpp:384:50 [clang-diagnostic-sign-conversion]
implicit conversion changes signedness: 'size_t' (aka 'unsigned long') to 'difference_type' (aka 'long')

[warning] 384-384: src/zx/FunctionalityConstruction.cpp:384:50 [bugprone-narrowing-conversions]
narrowing conversion from 'size_t' (aka 'unsigned long') to signed type 'difference_type' (aka 'long') is implementation-defined

[warning] 383-383: src/zx/FunctionalityConstruction.cpp:383:67 [clang-diagnostic-sign-conversion]
implicit conversion changes signedness: 'size_t' (aka 'unsigned long') to 'difference_type' (aka 'long')

[warning] 383-383: src/zx/FunctionalityConstruction.cpp:383:67 [bugprone-narrowing-conversions]
narrowing conversion from 'size_t' (aka 'unsigned long') to signed type 'difference_type' (aka 'long') is implementation-defined

[warning] 383-383: src/zx/FunctionalityConstruction.cpp:383:5 [misc-const-correctness]
variable 'first' of type 'std::vector' (aka 'vector') can be declared 'const'

[warning] 382-382: src/zx/FunctionalityConstruction.cpp:382:5 [misc-const-correctness]
variable 'half' of type 'size_t' (aka 'unsigned long') can be declared 'const'

[warning] 356-356: src/zx/FunctionalityConstruction.cpp:356:5 [misc-const-correctness]
variable 'nextControl' of type 'Qubit' (aka 'int') can be declared 'const'

[warning] 339-339: src/zx/FunctionalityConstruction.cpp:339:3 [readability-suspicious-call-argument]
2nd argument 'target' (passed to 'ctrl') looks like it might be swapped with the 3rd, 'control' (passed to 'target')

[warning] 336-336: src/zx/FunctionalityConstruction.cpp:336:3 [readability-suspicious-call-argument]
2nd argument 'target' (passed to 'ctrl') looks like it might be swapped with the 3rd, 'control' (passed to 'target')

⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

GitHub Check: 🐍 Test (macos-15-intel) / 🐍 macos-15-intel
GitHub Check: 🐍 Test (windows-2022) / 🐍 windows-2022

🔇 Additional comments (7)

include/mqt-core/zx/FunctionalityConstruction.hpp (1)

116-127: LGTM!

The new method declarations for multi-control gates are well-structured and follow the existing API patterns. The signatures are clear and properly typed.

test/zx/test_zx_functionality.cpp (1)

232-359: Excellent test coverage for multi-control operations.

The new tests thoroughly validate the multi-control functionality with:

CRZ decomposition equivalence

Multi-control X with varying control counts (0, 1, 3)

Multi-control RZ with phase cancellation

Edge cases for boundary conditions

All tests properly verify identity preservation, zero global phase, and connectivity after reduction.

src/zx/FunctionalityConstruction.cpp (5)

310-330: LGTM!

The addCcz implementation correctly decomposes the CCZ gate using the standard pattern with CNOTs, Z-spiders with appropriate phases, and Hadamard edges. The decomposition is consistent with ZX-calculus conventions.

332-340: LGTM!

The addCrz implementation uses the correct decomposition for controlled-RZ gates. The argument order in addCnot(diag, target, control, qubits) is intentional and follows the standard CRZ decomposition pattern where the roles are reversed.

Note: The static analysis warning about swapped arguments at lines 336 and 339 is a false positive.

680-682: LGTM!

The addition of the RZ case for single-control, single-target operations correctly routes to addCrz, expanding the supported gate set.

723-740: LGTM!

The updates to the two-control branch correctly:

Build the controls vector from the operation

Route CCZ operations to addCcz

Route multi-controlled RZ operations to addMcrz

Update error messages to reflect multi-control support

741-762: LGTM!

The new multi-control branch properly handles operations with arbitrary numbers of controls and a single target. The routing to addMcx, addMcz, and addMcrz is correct and extends the ZX functionality to support general multi-controlled gates.

coderabbitai

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/zx/FunctionalityConstruction.cpp (1)
872-896: LGTM: Extended transformableToZX for controlled RZ.

The updates correctly mark controlled-RZ operations as transformable in all control-count branches (1, 2, and N controls).

Minor cleanup - Line 896 has an unreachable return statement:
   } else if (op->getNtargets() == 1) {
     switch (op->getType()) {
     case qc::OpType::X:
     case qc::OpType::Z:
     case qc::OpType::RZ:
       return true;
     default:
       return false;
     }
-    return false;
   }
 }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bdb2073 and 0ae2b61.

📒 Files selected for processing (3)

include/mqt-core/zx/FunctionalityConstruction.hpp (1 hunks)
src/zx/FunctionalityConstruction.cpp (5 hunks)
test/zx/test_zx_functionality.cpp (1 hunks)

🧰 Additional context used

🧠 Learnings (4)

📚 Learning: 2025-10-09T13:20:11.483Z

Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/test/Dialect/MQTOpt/Transforms/lift-measurements.mlir:269-288
Timestamp: 2025-10-09T13:20:11.483Z
Learning: In the MQT MLIR dialect, the `rz` gate should not be included in the `DIAGONAL_GATES` set for the `ReplaceBasisStateControlsWithIfPattern` because its operator matrix does not have the required shape | 1 0 | / | 0 x | for the targets-as-controls optimization. It is only included in `LiftMeasurementsAboveGatesPatterns` where the matrix structure requirement differs.

Applied to files:

src/zx/FunctionalityConstruction.cpp

📚 Learning: 2025-12-08T14:55:43.880Z

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1264
File: mlir/lib/Dialect/Flux/IR/Modifiers/CtrlOp.cpp:78-100
Timestamp: 2025-12-08T14:55:43.880Z
Learning: In the Flux dialect (mlir/lib/Dialect/Flux/IR/Modifiers/CtrlOp.cpp), GPhaseOp is a zero-target operation (global phase). When a CtrlOp wraps a GPhaseOp, it only has control qubits and no targets. The CtrlInlineGPhase canonicalization pattern correctly produces outputs only for the positive controls, not targets.

Applied to files:

src/zx/FunctionalityConstruction.cpp
include/mqt-core/zx/FunctionalityConstruction.hpp

📚 Learning: 2025-10-09T13:13:51.224Z

Learnt from: DRovara
Repo: munich-quantum-toolkit/core PR: 1108
File: mlir/lib/Dialect/MQTOpt/Transforms/ReplaceBasisStateControlsWithIfPattern.cpp:171-180
Timestamp: 2025-10-09T13:13:51.224Z
Learning: In MQT Core MLIR, UnitaryInterface operations guarantee 1-1 correspondence between input and output qubits in the same order. When cloning or modifying unitary operations (e.g., removing controls), this correspondence is maintained by construction, so yielding getAllInQubits() in else-branches matches the result types from the operation's outputs.

Applied to files:

src/zx/FunctionalityConstruction.cpp

📚 Learning: 2025-12-08T12:44:05.874Z

Learnt from: denialhaag
Repo: munich-quantum-toolkit/core PR: 1264
File: mlir/lib/Dialect/Quartz/IR/Modifiers/CtrlOp.cpp:60-70
Timestamp: 2025-12-08T12:44:05.874Z
Learning: In the Quartz dialect (mlir/lib/Dialect/Quartz/IR/Modifiers/CtrlOp.cpp), negative controls are not supported at the current stage. The RemoveTrivialCtrl pattern correctly only checks getNumPosControls() when determining if a CtrlOp should be removed.

Applied to files:

src/zx/FunctionalityConstruction.cpp

🧬 Code graph analysis (1)

src/zx/FunctionalityConstruction.cpp (1)

include/mqt-core/zx/FunctionalityConstruction.hpp (18)

diag (65-68)

diag (69-72)

diag (74-76)

diag (77-78)

diag (80-82)

diag (83-85)

diag (86-87)

diag (88-89)

diag (91-93)

diag (95-97)

diag (99-101)

diag (102-103)

diag (105-108)

diag (110-113)

diag (114-115)

diag (116-117)

op (60-60)

op (135-135)