✨ Add bottom-up makeThreeQubitGateDD for RCCX

[simon1hofmann]

🤖 AI text below 🤖

Summary

• Add ThreeQubitGateMatrix / makeThreeQubitGateDD for direct bottom-up DD construction of three-qubit gates (same style as makeGateDD / makeTwoQubitGateDD), starting with RCCX via opToThreeQubitGateMatrix.
• Use MSB-among-operands bit order for three-qubit matrices (targets[0] = high bit), matching makeTwoQubitGateDD and QCO (embed / CtrlOp); RCCX is the 5/6/7 form (not the Qiskit little-endian 3/5/7 labeling).
• Route RCCX through the new path in getStandardOperationDD instead of the multiply-based construction.
• Share control-wrapping, range checks, and terminal materialization helpers across 1q/2q/3q gate DD builders.
• Wire QCO buildFunctionality / simulate dense path through makeThreeQubitGateDD for 3-wire unitaries (plain copy; full-width makeDDFromMatrix still remaps QCO MSB → global DD LSB).
• Consolidate RCCX DD construction tests (target permutations, overload wrappers, extra pos/neg controls) and cover partial-width 3q dense inv in QCO DD functionality tests.

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.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

❌ Patch coverage is 97.48428% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/Utils/DDFunctionality.cpp	69.2%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[simon1hofmann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Warning

Review limit reached

@simon1hofmann, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 3 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f6a81b0f-f56d-4dc8-a0b8-7fec3009fd2d

📥 Commits

Reviewing files that changed from the base of the PR and between 578ebcf and 111efdb.

📒 Files selected for processing (2)

• src/dd/Package.cpp
• test/dd/test_package.cpp

📝 Walkthrough

Walkthrough

Adds native RCCX three-qubit matrix conversion and decision-diagram construction, including controlled variants. Shared DD-building helpers replace RCCX-specific construction, with expanded QCO integration, matrix, circuit, invalid-operation, and controlled-gate tests.

Changes

RCCX decision-diagram support

Layer / File(s)	Summary
Three-qubit matrix contracts include/mqt-core/dd/*, src/dd/GateMatrixDefinitions.cpp, mlir/lib/Dialect/QCO/...	Adds the fixed-size three-qubit matrix type, RCCX matrix conversion, public makeThreeQubitGateDD overloads, and QCO handling for three-qubit unitaries.
Generic controlled DD construction src/dd/Package.cpp, src/dd/Operations.cpp	Centralizes validation, terminal construction, control wrapping, and three-qubit matrix reduction; RCCX now uses the generic path.
RCCX validation and release updates test/dd/*, mlir/unittests/..., CHANGELOG.md	Expands RCCX, invalid-operation, partial-width, matrix, and circuit coverage, updates supported-operation documentation, and adds the changelog reference.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operations
  participant Package
  participant GateMatrixDefinitions
  participant DecisionDiagram
  Operations->>Package: makeThreeQubitGateDD
  Package->>GateMatrixDefinitions: opToThreeQubitGateMatrix
  GateMatrixDefinitions-->>Package: return RCCX matrix
  Package->>DecisionDiagram: reduce matrix and wrap controls
  DecisionDiagram-->>Operations: return mEdge

Loading

Possibly related PRs

• munich-quantum-toolkit/core#1426: Relates to QCO unitary-matrix access used by RCCX handling.
• munich-quantum-toolkit/core#1886: Adds the native RCCX gate that this PR supports in DD construction.
• munich-quantum-toolkit/core#1915: Relates to QCO-to-DD functionality extended here for three-qubit unitaries.

Suggested labels: dependencies, DD, c++, Core, ZX, MLIR

Poem

I’m a rabbit with matrices bright,
Hopping through DDs day and night.
RCCX now takes flight,
Controls wrap left and right—
Three qubits bloom in quantum light!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.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 is concise and accurately highlights the main change: bottom-up makeThreeQubitGateDD support for RCCX.
Description check	✅ Passed	The description includes a clear summary, motivation, context, testing/docs checklist, and AI disclosure, matching the template well.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/dd-three-qubit-bottom-up

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[simon1hofmann]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

src/dd/Package.cpp (1)

156-174: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Reject empty packages before subtracting from nqubits.

For Package(0), nqubits - 1U underflows, so target/control 0 passes validation and construction proceeds with an out-of-range DD level. This affects all three gate builders using this helper.

Proposed fix

 [[noreturn]] void throwGateQubitOutOfRange(const std::size_t nqubits) {
+  if (nqubits == 0U) {
+    throw std::runtime_error(
+        "Cannot construct a gate in a package with zero qubits.");
+  }
   throw std::runtime_error{
       "Requested gate acting on qubit(s) with index larger than " +
       std::to_string(nqubits - 1U) +
@@
 void ensureGateQubitsInRange(const std::size_t nqubits,
                              const qc::Controls& controls,
                              const std::initializer_list<qc::Qubit> targets) {
-  const auto maxQubit = static_cast<Qubit>(nqubits - 1U);
-  if (std::ranges::any_of(
-          controls, [maxQubit](const auto& c) { return c.qubit > maxQubit; }) ||
-      std::ranges::any_of(targets,
-                          [maxQubit](const Qubit t) { return t > maxQubit; })) {
+  if (nqubits == 0U ||
+      std::ranges::any_of(controls, [nqubits](const auto& c) {
+        return static_cast<std::size_t>(c.qubit) >= nqubits;
+      }) ||
+      std::ranges::any_of(targets, [nqubits](const Qubit target) {
+        return static_cast<std::size_t>(target) >= nqubits;
+      })) {
     throwGateQubitOutOfRange(nqubits);
   }
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/dd/Package.cpp` around lines 156 - 174, Update ensureGateQubitsInRange to
reject nqubits == 0 before computing nqubits - 1U, using the existing
throwGateQubitOutOfRange error path so all gate builders receive consistent
validation. Preserve the current control and target range checks for non-empty
packages.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/dd/Package.cpp`:
- Around line 156-174: Update ensureGateQubitsInRange to reject nqubits == 0
before computing nqubits - 1U, using the existing throwGateQubitOutOfRange error
path so all gate builders receive consistent validation. Preserve the current
control and target range checks for non-empty packages.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1156ed52-c2ba-45c6-ba10-a52932b0df80

📥 Commits

Reviewing files that changed from the base of the PR and between 31d077c and d47b05b.

📒 Files selected for processing (6)

• mlir/include/mlir/Dialect/QCO/Utils/DDFunctionality.h
• mlir/lib/Dialect/QCO/IR/Operations/StandardGates/RCCXOp.cpp
• mlir/lib/Dialect/QCO/Utils/DDFunctionality.cpp
• mlir/unittests/Dialect/QCO/Utils/test_dd_functionality.cpp
• src/dd/GateMatrixDefinitions.cpp
• src/dd/Package.cpp

[simon1hofmann]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/dd/Package.cpp`:
- Around line 169-181: Extend ensureGateQubitsInRange to reject duplicate target
qubits and any control qubit that matches a target, while preserving the
existing range validation and throwing through throwGateQubitOutOfRange. Add
regression coverage for duplicate targets and control/target overlap, including
the currently skipped RCCX cases.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 12002321-85db-487c-a80b-42dab6b7e6dd

📥 Commits

Reviewing files that changed from the base of the PR and between d47b05b and 578ebcf.

📒 Files selected for processing (2)

• src/dd/Package.cpp
• test/dd/test_package.cpp

[simon1hofmann]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[burgholzer]

This feels really clean. Let's get this in 🚀