✨ Add MQT Core compilation and QIR export

[simon1hofmann]

🤖 AI text below 🤖

Description

Add optional MQT Core compilation with compiler="mqt" or --compiler mqt, plus QIR export as LLVM text or bitcode. Qiskit remains the default compiler; both paths return QuantumCircuit. Native compilation ignores placement and uses the input circuit width. Mapped compilation enforces connectivity, ordered gate placements, and device width.

The mqt extra installs MQT Core 4.1.1 from PyPI and requires Qiskit 2.5.x. Core wheels include the compiler runtime, so wheel installations and the integration CI no longer need a separate LLVM/MLIR setup. Base Bench retains Qiskit 2.1.2 support. uv keeps both dependency selections in one lockfile; the minimums group conflicts with the mqt extra so minimum-version CI cannot silently upgrade to 2.5.

python -m pip install -e ".[mqt]"
mqt-bench --compiler mqt --algorithm ghz --num-qubits 3 \
  --level mapped --target iqm_crystal_5 --save

Core owns gate identity, native aliases, parameter constraints, and synthesis. Native compilation imports CompilerTarget.NativeOperations, retaining bounds independently of hardware placement, then uses the ordinary Core target constructor. Runtime Pauli rotations, single-controlled Pauli rotations, and controlled phase use Core's shared synthesis. IQM compilation benefits from direct two-R synthesis and Z-frame propagation through CZ, with compact symbolic angles and shared Qiskit expression conversion. Native RZ targets also merge Z frames through diagonal entanglers. Constant resynthesis shares Core's local average-fidelity floor of 1 - 1e-12; unbound angles remain exact. Unsupported constraints fail explicitly; there is no fallback transpiler or approximate Clifford+T synthesis. Multi-qubit devices require an entangling capability; one-qubit benchmarks remain supported.

Native targets

• Add ibm_nighthawk_120 and the shared CZ-based ibm_nighthawk gate set. Its 12-by-10 grid matches all 436 directed edges in IBM Runtime's FakeNighthawk snapshot. IBM's current Nighthawk has 120 programmable qubits; Heron has 156. Nighthawk fractional gates are not advertised. Test mapped compilation for Nighthawk, Heron, and fractional Heron.
• Add ibm_heron_fractional and ibm_heron_156_fractional, with arbitrary RX and bounded RZZ. Both compilers fold numeric RZZ angles into [0, pi/2] with exact local and phase corrections. Core uses two RZZ(pi/2) gates for unknown runtime angles; bind parameters before Qiskit compilation to enforce the interval. Qiskit uses its existing wrapping pass with local registry copies, preserving the global registry. Fractional models are available with Qiskit 2.2 or newer. Calibration is synthetic.
• IonQ GPI/GPI2 use radians, standard RZZ replaces the custom ZZ gate, and Forte retains arbitrary virtual RZ. Provider submission must perform any required GPI phase tracking. Core uses fixed-parameter R capabilities; no MS operation or ion-specific IR gates are needed.
• Rigetti exposes standard RX instances named rxpi, rxpidg, rxpi2, and rxpi2dg, plus RZ/CZ. IonQ and Rigetti optimize through standard Qiskit gates and lower native names with a local equivalence library. Global phase is preserved, including when results are controlled and recompiled. Alias translation preserves angle bounds on other gates; native and mapped regression tests cover bounded RZZ combined with both IonQ and Rigetti aliases.
• Replace obsolete Aria, Falcon, Eagle, Heron-133, and Braket Ankaa models. Add rigetti_cepheus_107 with explicit physical labels and aqt_ibex_12 using R/RZ/RXX. Keep Forte, Heron-156, IQM architecture models, and Quantinuum H2. Models have documented provenance and calibration limitations; benchmark generation makes no cloud queries.

Compilation and output

Core uses its fixed optimization pipeline; leave opt_level=2. Seed 10 and four mapping trials are the defaults; compiler_options=CompilationOptions(...) overrides them, including for mirror recompilation. Native results retain logical layout metadata; use Operator.from_circuit to interpret them. Mapped results use physical wires and preserve measurement destinations. Qiskit mirror recompilation preserves the original layout. Exports record compiler provenance.

The extra enables qir/llvm text and qir-bitcode output for either compiler, with Base or Adaptive profiles. Parameters must be bound. Export lowers the supplied circuit without another compilation pipeline; execution requires a compatible QIR runtime. The parameter guide, upgrade guide, and target catalogue describe options, migrations, and device evidence. Broader compiler pipeline changes remain deferred.

Validation

• Rebased on upstream main fcc5b3cb, preserving Python 3.15 support and the mirror fixes.
• Full suite with the Core 4.1.1 PyPI wheel on Python 3.14: 578 passed, including all 180 Core integration tests and QIR execution. Core adapter coverage is 100%; overall coverage is 99.5%.
• Minimum-dependency session with Qiskit 2.1.2: 377 passed, 22 skipped. All 20 fractional-angle and native-alias checks also pass on Qiskit 2.2.
• Core's released compiler API works with the existing adapter. QIR execution tests now import open_device from mqt.core.qdmi.builtin_driver.
• Repository lint, type checking, documentation with warnings treated as errors, and uv lock validation passed. The documentation Markdown build reuses executed notebooks to avoid concurrent file-writing examples. Hosted CI is reported separately.

Assisted by GPT-6 via Codex.

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

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

Files with missing lines	Patch %	Lines
src/mqt/bench/targets/gatesets/ibm.py	94.3%	3 Missing ⚠️
src/mqt/bench/targets/gatesets/_compilation.py	98.1%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[simon1hofmann]

🤖 AI text below 🤖

[P2] Preserve angle bounds when translating native aliases

In prepare_target(), the temporary target copies instructions without their angle_bounds. When alias translation is needed, this silently removes constraints on other gates and prevents the fractional-angle wrapper from being configured.

Reproduced on 2972a1e84 with Qiskit 2.5.2:

from math import pi
from qiskit import QuantumCircuit
from qiskit.circuit import Parameter
from qiskit.circuit.library import RZGate, RZZGate
from qiskit.transpiler import Target
from mqt.bench import get_benchmark_native_gates, get_benchmark_mapped
from mqt.bench.targets.gatesets.ionq import GPIGate, GPI2Gate

target = Target(num_qubits=2)
target.add_instruction(GPIGate(Parameter("gpi")))
target.add_instruction(GPI2Gate(Parameter("gpi2")))
target.add_instruction(RZGate(Parameter("rz")))
target.add_instruction(RZZGate(Parameter("zz")), angle_bounds=[(0, pi / 2)])

source = QuantumCircuit(2)
source.rzz(-0.37, 0, 1)
for compile_circuit in (get_benchmark_native_gates, get_benchmark_mapped):
    result = compile_circuit(source, None, target, compiler="qiskit")
    invalid = [
        item.operation.params
        for item in result.data
        if item.operation.name == "rzz"
        and not target.supported_angle_bound("rzz", item.operation.params)
    ]
    print(invalid)  # [[-0.37]] for both compilation levels

Both outputs preserve the unitary but violate the requested target. Core compilation handles the same input correctly.

Please preserve angle bounds when constructing the temporary target and add a regression test combining native aliases with a bounded entangler, covering both native and mapped compilation.