🐛 Import array-valued Qiskit gate parameters

[simon1hofmann]

🤖 AI text below 🤖

Description

Importing a PermutationGate or a custom instruction with array-valued parameters currently reaches Qiskit's scalar C API and can abort Python. Read custom operation operands through the adapter, validate permutation patterns, and lower permutations to reusable SWAP functions in Core. Preserve modifiers on the complete permutation. Other custom operations use their supplied circuit definitions; unsupported opaque operations raise a Python exception.

The implementation does not call Qiskit synthesis or transpilation. Qiskit is used only by the existing import/export adapter to read and construct SDK objects. Core owns permutation lowering and the compilation pipeline.

This removes an upstream cause of the compatibility normalization in munich-quantum-toolkit/bench#1027. Bench should retain its workaround until a Core release includes this fix.

Usage

from qiskit import QuantumCircuit
from qiskit.circuit.library import PermutationGate
from mqt.core.mlir import QCProgram

circuit = QuantumCircuit(3)
circuit.append(PermutationGate([2, 0, 1]), range(3))
program = QCProgram.from_qiskit(circuit)
restored = program.to_qiskit()

Limitations

• Direct Qiskit translation still requires the supported Qiskit 2.5 adapter.
• Permutations lower to native SWAP functions; their original Python class and parameter array are not reproduced on export.
• Other custom operations still require supported finite, acyclic circuit definitions. Existing nesting, arity, and expression limits apply.
• This does not add a general high-level synthesis framework or change parameter identity, layout, or mapping-control APIs.

Changelog and upgrade-guide entries are deferred to release preparation under the policy proposed in #2556 and munich-quantum-toolkit/templates#449. This PR has no entries in either file.

Validation

• Native build and uvx nox -s stubs.
• Qiskit translation suite: 409 tests passed, including nested, controlled, and annotated permutations, all four-qubit patterns, invalid patterns, custom classical operands, and opaque array-valued operations.
• Repository lint and full changed-file C++ lint against origin/main.

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).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[burgholzer]

This feels pretty reasonable. I just have a general observation on the changelog that may be worth thinking about. Let's resolve that and then get this merged.