Add multi-control functionality #1380

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 97.16981% with 3 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

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

📝 Walkthrough

Summary by CodeRabbit

New Features
- Added end-user support for two- and multi-controlled Z and X gates plus controlled‑RZ rotations, with improved routing across different control counts and explicit ancilla-availability checks.
- Extended transformability to recognize and handle RZ in single-, double- and multi-control scenarios.
Tests
- Expanded test suite with many multi-controlled gate variants to validate transformations, identity preservation, and connectivity.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Added multi-control ZX-diagram construction routines (addCcz, addCrz, addMcrz, addMcx, addMcz), integrated them into operation parsing and transformability checks, and expanded tests to validate multi-control constructions and post-reduction equivalence. (≤50 words)

Changes

Cohort / File(s)	Summary
Header Declaration `include/mqt-core/zx/FunctionalityConstruction.hpp`	Added static declarations: `addCcz`, `addCrz`, `addMcrz`, `addMcx`, `addMcz`.
Implementation `src/zx/FunctionalityConstruction.cpp`	Implemented multi-control helpers (`addCcz`, `addCrz`, `addMcrz`, `addMcx`, `addMcz`); extended `parseOp` to route RZ/CZ/MCX/MCRZ paths; updated `transformableToZX` to accept `RZ` in multi-control contexts; added ancilla-aware recursive decompositions and error checks.
Tests `test/zx/test_zx_functionality.cpp`	Replaced a single unsupported-case test with a comprehensive suite covering CRZ, CCZ, MultiCZ, MultiControlX (variants), MultiControlRZ and related variants; tests assert identity, zero global phase, and preserved connectivity after reduction.
Build / CI `CMakeLists.txt`	Test/build entries updated (lines changed +327/-5).

Sequence Diagram(s)

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

    Parser->>FC: receive qc::Operation (e.g., MCX / CRZ / RZ)
    FC->>FC: select decomposition path (direct, CCZ, or multi-control)
    alt requires ancilla
        FC->>Anc: request ancilla qubits
        Anc-->>FC: provide ancilla or return error
    end
    FC->>ZX: call addCcz/addCrz/addMcrz/addMcx/addMcz(...) to build ZX subgraph
    ZX-->>Parser: updated ZXDiagram (operation represented)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐇 I hop through wires and phases bright,
I stitch CCZ and CRZ by moonlight,
Ancilla crumbs guide MCX's song,
Controls align and circuits throng,
A rabbit hums — the gates belong.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 'Add multi-control functionality' directly summarizes the main change of adding multi-controlled gate support to the ZX package.
Description check	✅ Passed	The description includes all required sections: summary of changes, linked issue reference, and completed checklist items covering commits, tests, documentation, changelog, style, and CI.
Linked Issues check	✅ Passed	The PR implements all objectives from #1357: adds MCX and MCZ support via addMcx/addMcz, adds CRZ and MCRZ via addCrz/addMcrz, adds convenience addCcz, and integrates into transformation routines.
Out of Scope Changes check	✅ Passed	All changes align with the linked issue objectives: multi-control gate support (MCX, MCZ, MCRZ, CRZ) in FunctionalityConstruction, corresponding tests, and related infrastructure updates.

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

✨ Finishing touches

📝 Generate docstrings

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.

src/zx/FunctionalityConstruction.cpp

test/zx/test_zx_functionality.cpp

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)