✨ Implement controlled unitary embedding

[simon1hofmann]

Description

Fixes incorrect controlled-gate unitary matrices in QCO and unifies matrix wire indexing on the QuantumComputation convention.

Problem: CtrlOp::getUnitaryMatrix() embedded the inner unitary via DynamicMatrix::setBottomRightCorner (I_{2^c} ⊗ U), which is only correct when controls sit on the most significant wires. For general wire placement (e.g. cx(q[0], q[1])), the result did not match QuantumComputation.

Solution:

• Add embedControlledUnitary() to place a multi-controlled unitary using actual control/target register indices (QC little-endian: qubit i = bit i).
• Resolve compile-time wire indices in CtrlOp from qco.static and constant qtensor.extract operands.
• Unify embedInNqubit, kron, and related helpers on the same bit ordering (replacing the old MSB-first embedding).
• Remove unused DynamicMatrix::setBottomRightCorner API.

Fixes #1821

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:

• I have disclosed the use of AI tools in the PR description as per our AI Usage Guidelines.
• 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.

[github-actions]

Cpp-Linter Report ⚠️

Some files did not pass the configured checks!

clang-tidy (v22.1.8) reports: 6 concern(s)

• mlir/lib/Dialect/QCO/IR/Modifiers/CtrlOp.cpp:49:42: warning: [llvm-prefer-static-over-anonymous-namespace]

  function 'programQubitIndex' is declared in an anonymous namespace; prefer using 'static' for restricting visibility

     49 | [[nodiscard]] std::optional<std::size_t> programQubitIndex(const Value qubit) {
        |                                          ^

• mlir/lib/Dialect/QCO/IR/Modifiers/CtrlOp.cpp:83:1: warning: [llvm-prefer-static-over-anonymous-namespace]

  function 'resolveQubitIndices' is declared in an anonymous namespace; prefer using 'static' for restricting visibility

     83 | resolveQubitIndices(const ValueRange qubits) {
        | ^

• mlir/lib/Dialect/QCO/IR/Modifiers/CtrlOp.cpp:384:42: warning: [misc-include-cleaner]

  no header providing "std::max" is directly included

     34 |   const std::size_t numQubits = 1 + std::max(*llvm::max_element(*controlQubits),
        |                                          ^

• mlir/unittests/Dialect/QCO/IR/test_qco_ir_matrix.cpp:101:27: warning: [misc-include-cleaner]

  no header providing "std::optional" is directly included

     37 | [[nodiscard]] static std::optional<DynamicMatrix>
        |                           ^

• mlir/unittests/Dialect/QCO/IR/test_qco_ir_matrix.cpp:103:31: warning: [misc-include-cleaner]

  no header providing "llvm::function_ref" is directly included

     27 |                         llvm::function_ref<void(QCOProgramBuilder&)> build) {
        |                               ^

• mlir/unittests/Dialect/QCO/IR/test_qco_ir_matrix.cpp:106:17: warning: [misc-include-cleaner]

  no header providing "std::nullopt" is directly included

    106 |     return std::nullopt;
        |                 ^

Have any feedback or feature suggestions? Share it here.

[codecov]

Codecov Report

❌ Patch coverage is 90.36145% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/IR/Modifiers/CtrlOp.cpp	80.4%	8 Missing ⚠️

📢 Thoughts on this report? Let us know!