Add multi-control functionality 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 93.05556% with 5 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

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

📝 Walkthrough

Summary by CodeRabbit

New Features
- Added support for multi-controlled quantum gates: phase, SWAP, rotations (RZ/RX), Pauli gates (X/Z), and double-controlled Z operations for enhanced circuit handling.

Walkthrough

Added multi-controlled gate construction routines and integrated them into operation parsing and transformability checks; expanded ZX conversion to support multi-control variants (MCX, MCZ, MCRZ, MCRX, MCRZZ, MCPhase, CCZ, CRZ, CRX, MCSWAP) and updated tests to validate equivalence via ZX reductions. (≤50 words)

Changes

Cohort / File(s)	Summary
Header Declaration `include/mqt-core/zx/FunctionalityConstruction.hpp`	Added static declarations for multi-control primitives and single-/multi-controlled RX/RZ/ZZ/Swap helpers (`addMcphase`, `addMcswap`, `addMcrzz`, `addCcz`, `addCrx`, `addMcrx`, `addCrz`, `addMcrz`, `addMcx`, `addMcz`).
Implementation `src/zx/FunctionalityConstruction.cpp`	Implemented multi-control and controlled-rotation decompositions, divide-and-conquer Mcx routing, ancilla-aware handling, and new paths for RZ/RX/RZZ/RXX/RZX multi-control variants; updated `parseOp` and `transformableToZX` to emit/use these routines and extended error/routing branches.
Tests `test/zx/test_zx_functionality.cpp`	Added `checkEquivalence` helper; replaced manual functionality checks with equivalence-based tests; added comprehensive tests for CRZ, CCZ, MCX (various sizes), MCZ, MCRZ/MCRX and updated existing gate tests to use the helper.
Build / CI `CMakeLists.txt`	Test build entries updated to include new/modified test cases.

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 strategy (0/1/2/≥3 controls)
    alt needs ancilla
        FC->>Anc: request ancilla qubits
        Anc-->>FC: provide ancilla or fail
    end
    FC->>ZX: invoke addMcx/addMcrz/addMcswap/addCcz/... to build ZX subgraph
    ZX-->>Parser: ZXDiagram updated (subgraph appended)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

Enhance ZX simplification algorithms for multi-control gate validation #1429 — Adds multi-control gate implementations and related ZX tests; overlaps this PR's additions of MCX/MCZ/MCRZ/CCZ/CRZ and test expansions.

Suggested labels

c++

Suggested reviewers

burgholzer

Poem

🐇 I hop through wires and phases bright,
I braid MCX and CCZ by night,
Ancilla crumbs beneath my paws,
Spiders spin circuits without pause,
A rabbit cheers — the diagrams light.

🚥 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' is concise and directly describes the main change—adding multi-control gate support to the ZX package.
Description check	✅ Passed	The PR description includes the required sections: a summary of changes (CRZ, MCX, MCZ, MCRZ, CCZ), the fixed issue (`#1357`), and a completed checklist. All critical sections are present.
Linked Issues check	✅ Passed	The PR fully addresses issue `#1357`'s objectives: extends transformations beyond one- and two-qubit gates, implements MCX/MCZ/CRZ/MCRZ support with proper ZX diagram representation and integration.
Out of Scope Changes check	✅ Passed	All changes directly support the PR objectives: multi-control gate implementations (MCX, MCZ, CRZ, MCRZ, CCZ, MCRx, MCRzz, MCSwap), supporting infrastructure, and comprehensive tests for the new functionality.

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

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

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)