✨ Preserve and control compiler qubit layouts

[simon1hofmann]

🤖 AI text below 🤖

Description

Preserve imported transpiler layouts through compiler round trips, and expose native initial-placement controls with an input-to-site mapping report. This extends the original native-layout work to fix #2070.

The shared mqt.layout module attribute records logical inputs, initial physical positions, optional routing assignments, output order, source register groups, and ancillary inputs. It stores no Python objects or SDK-specific attributes. Only the existing Qiskit 2.5 adapter reads and reconstructs SDK objects; placement, routing, validation, and layout lifetime rules use Core code. No Qiskit transpilation or synthesis algorithms are copied into Core or invoked by native compilation.

Copies, MLIR serialization, and plain QC/QCO conversions preserve imported provenance without changing instruction semantics. Resource-changing transformations and public custom pass pipelines invalidate it. SDK export rejects stale provenance, and formats that cannot retain it require explicit discard.

Dependency: stacked on #2551 (feat/target-mapping-controls). Layout compilation accepts seed, timing, statistics, mapping trials, refinement iterations, and routing lookahead only through CompilationOptions. Replace separate timing/statistics keywords with options=CompilationOptions(...). The explicit input assignment and detached mapping result retain their existing contracts.

Fixes #2070

Changelog and upgrade-guide entries are deferred to release preparation under the current project policy. Required migrations are described below.

Preserve imported layouts

from qiskit import QuantumCircuit, transpile
from mqt.core.mlir import QCProgram, QIRProfile

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit = transpile(
    circuit, coupling_map=[[0, 1], [1, 0]],
    initial_layout=[1, 0], optimization_level=0,
)
program = QCProgram.from_qiskit(circuit)
restored = program.copy().to_qco().to_qc().to_qiskit()
assert restored.layout.final_index_layout() == circuit.layout.final_index_layout()

# Accept losing provenance before conversion to a format without layouts.
program.discard_layout()
bitcode = program.to_qir(QIRProfile.BASE).to_bitcode()

C++ callers use Program::discardLayout(). The CLI equivalent is:

mqt-cc input.mlir --discard-layout --emit=qir-base -o output.ll

Control native placement

from mqt.core.mlir import (
    CompilationOptions, CompilerTarget, MappingOptions, PayloadEncoding, PayloadFormat,
    PayloadSpecification, QCProgram, TargetEnvironment,
)

target = CompilerTarget(
    3,
    connectivity=CompilerTarget.Connectivity([(0, 1), (1, 2)]),
    native_operations=CompilerTarget.NativeOperations.unrestricted(),
)
environment = TargetEnvironment(
    target,
    PayloadSpecification(
        PayloadFormat("qir", "2.1.0", "base", PayloadEncoding.BINARY),
        [], optional_capabilities_known=True,
    ),
)
program = QCProgram.from_openqasm_str('''OPENQASM 3.1;
include "stdgates.inc";
qubit[2] q;
h q[0]; cx q[0], q[1];
''').to_qco()
layout = program.compile_for_target_with_layout(
    environment, initial_layout=[0, 2], options=CompilationOptions(seed=42, mapping=MappingOptions(trials=4, iterations=2, lookahead=10)),
)
print(layout.allocation_sizes)
print(layout.initial_layout)
print(layout.final_layout)

The example's forced placement routes the two logical qubits through the three-site line. It reports allocation sizes [2] and the requested initial sites [0, 2]. A particular final assignment is not a cross-version guarantee.

Omit initial_layout or pass [] for automatic placement. Set both seed and trials to make automatic mapping independent of CPU count for a fixed build, input, and target. A supplied layout bypasses trials and refinement iterations; lookahead still controls routing. Iterations default to one and must be positive. Lookahead defaults to 20 additional two-qubit gates, and zero considers only the current gate.

Each layout entry is a target site ID, including sparse IDs. Input order is entry-block allocation order with tensor slots flattened in ascending index order. allocation_sizes retains allocation boundaries. This order is independent of which qubit is used first. Classical measurement destinations retain their semantics.

Limitations

• SDK interchange supports Qiskit 2.5 TranspileLayout: initial/final assignments, partial maps, physical gaps, loose and ancillary inputs, source-register ordering, and nontrivial output permutations. Input indices must be contiguous and physical references must exist. Partial final maps need a complete output-wire order; SDK helpers requiring total layouts can still reject partial assignments. Bare Layout values are rejected. Other SDK minor versions need their own adapter.
• Cleanup, optimization, routing, allocation changes, reuse, and public custom pass pipelines conservatively replace imported metadata with mqt.layout_invalidated. They do not compose an earlier SDK layout with a new target-compilation result. Call discard_layout() before SDK export after invalidation.
• OpenQASM, QIR/LLVM, and jeff cannot preserve this provenance and reject retained or invalidated metadata until explicitly discarded. Discarding metadata does not change operations.
• Raw IR editors and callers assembling external pass managers must preserve correspondence, update the metadata, or invalidate it before changing resource identity or order. Schema verification cannot detect every stale same-width external edit.
• Native initial_layout requires one distinct target site ID per input; partial placement constraints are not supported. This is separate from preserving partial imported metadata.
• Native placement accepts fixed-size local entry-block allocations. Dynamic, nested, and already physical inputs are rejected. Idle slots count against target capacity; inputs removed before this call cannot be recovered.
• MappingResult is a detached snapshot of one compilation and is not serialized or updated by later edits. The low-level result must outlive its pass manager and is published only on success. CLI placement input and report serialization remain outside this PR.
• Existing circuit-import, routing, synthesis, and payload limitations still apply. Program contents must not be reused after failed target compilation.

Validation

• 625 Python compiler, translation, and QDMI tests passed with the native SC-provider registry.
• 239 native compiler tests and 37 metadata tests passed, covering layout schema, serialization, discard, output guards, routing, failure publication, shared options, iteration validation, and explicit placement with zero lookahead.
• Three CLI CTests and four GoogleTest CLI checks passed, covering mapping options, seed overrides, layout export guards, explicit discard, import retention, and transformation invalidation.
• Repository lint and full changed-file C++ lint against origin/main pass; regenerated bindings include the shared options API.
• Both Python usage examples execute successfully.

The earlier native patch coverage measurement at 3178e825c was 419/438 production lines (95.7%), including 130/130 in QubitLayout.cpp. This update adds shared-options regression coverage and changes no coverage thresholds or exclusions; the new CI measurement is pending.

Codex assisted with the implementation, tests, documentation, and description. This remains a draft for human review. 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.
• 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 95.86466% with 22 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...lir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp	91.1%	16 Missing ⚠️
mlir/lib/Compiler/TargetCompilation.cpp	88.3%	5 Missing ⚠️
mlir/lib/Compiler/Pipeline.cpp	97.3%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!