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

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

📢 Thoughts on this report? Let us know!

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

📝 Walkthrough

Summary by CodeRabbit

New Features
- Added support for controlled rotation Z (CRZ) and multi-controlled rotation Z (MCRZ) quantum gates
- Added support for doubly-controlled Z (CCZ) and multi-controlled Z (MCZ) quantum gates
- Enhanced multi-controlled X (MCX) gate decomposition with improved handling

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

Walkthrough

Added multi-control ZX-diagram construction routines (CCZ, CRZ, MCRZ, MCX, MCZ), integrated them into operation parsing and transformability checks, and expanded tests to validate multi-control constructions and reductions. (≤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` overloads to accept `RZ` in multi-control contexts; added ancilla-aware recursive decompositions and error checks.
Tests `test/zx/test_zx_functionality.cpp`	Replaced single unsupported test with a suite covering CRZ, CCZ, MultiCZ, MultiControlX (variants), MultiCRZ; tests assert identity, zero global phase, and preserved connectivity after reduction.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Inspect control ordering and indexing in MCX/MCRZ/CCZ implementations.
Verify phase handling and PiExpression usage in addCrz / addMcrz.
Review parseOp and transformableToZX branches for all control-count cases.
Check ancilla selection, allocation logic, and error/edge-case handling.
Run the expanded test suite to confirm expected reductions.

Poem

🐇 I hop through wires and phases bright,
I stitch CCZ and CRZ by night,
My paws arrange each control in line,
MCX and MCZ now shine,
Diagrams hum — a rabbit's delight!

Pre-merge checks and finishing touches

❌ 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%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title succinctly captures the primary change: adding multi-control functionality to the ZX package, which is clearly evident from the codebase additions.
Description check	✅ Passed	Description includes summary of changes, references the fixed issue (#1357), and mostly completes the checklist. However, changelog entries and CI passing confirmation are missing.
Linked Issues check	✅ Passed	PR fulfills the main objective of #1357 by implementing multi-controlled gates (MCX, MCZ, MCRZ) and controlled rotations (CRZ). All code-level requirements from the linked issue have been addressed.
Out of Scope Changes check	✅ Passed	All changes are focused on the stated objective of adding multi-control functionality. Header declarations, implementations, and comprehensive test coverage are all directly aligned with extending ZX package capabilities.

✨ 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)