🐛 Preserve compiler input parameter identities

[simon1hofmann]

🤖 AI text below 🤖

Description

Free parameters imported from Qiskit currently export with new UUIDs, so binding an exported circuit with the original Parameter object fails. Preserve those identities through QC/QCO conversion, optimization, and MLIR serialization using an optional, frontend-neutral mqt.input_id attribute on named function inputs.

The MQT dialect owns the opaque 128-bit identity and verifies its type, placement, and uniqueness. The existing SDK adapter converts UUIDs at the import/export boundary. No Qiskit synthesis or transpilation is used. Keep the compatibility guide focused on the binding guarantee and add development and agent guidance for concise documentation.

Changelog and upgrade-guide entries are deferred to release preparation under the policy proposed in #2556 and munich-quantum-toolkit/templates#449. Required migrations are described below.

Usage

from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
from mqt.core import mlir

angle = Parameter("angle")
circuit = QuantumCircuit(1)
circuit.rx(angle, 0)
program = mlir.from_qiskit(circuit).to_qco()
restored = mlir.QCOProgram.from_mlir_str(str(program)).to_qiskit()
bound = restored.assign_parameters({angle: 0.5})

Parameter vectors retain their root UUID, including identities of unused vector elements. Original vectors can be used for binding after export. When requiring a Core version with this fix, remove name-based rebinding workarounds. Older IR without input IDs keeps fresh scalar identity behavior; UUID-shaped vector group identities can still be restored.

Limitations

• This preserves externally bindable free input identities. Private helper and lexically bound loop parameter UUIDs are not guaranteed.
• OpenQASM and QIR do not retain this compiler metadata. Older Core versions cannot read the new dialect attribute.
• Unused named program inputs remain unsupported by the existing exporter.
• Vector element identities must share one root UUID; inconsistent metadata raises an export error.
• The existing Qiskit 2.5 adapter version constraints still apply.

Validation

The documentation and guidance update passes repository lint. Existing implementation validation remains unchanged:

• Built Python translation suite: 385 passed.
• Native MQT IR metadata tests: 33 passed.
• Native build, generated stubs, repository lint, and changed-file C++ lint: passed.
• Regressions cover original-object binding, serialization, optimized QCO, copies, sibling control flow, sparse vectors, UUID zero and maximum, and malformed metadata.

Codex assisted with the code, tests, documentation, and description. CI for the latest push is pending.

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.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[burgholzer]

This generally looks really good to me.
Just one, also rather general comment.