✨ Expose native target mapping controls

[simon1hofmann]

🤖 AI text below 🤖

Description

Add shared CompilationOptions for timing, statistics, a compilation-wide seed,
and native mapping trials, refinement iterations, and routing lookahead. C++,
Python, and mqt-cc use the same controls through target compilation, synthesis,
custom pass pipelines, and QDMI source submission.
Compiler settings are accepted only through CompilationOptions; separate
timing/statistics arguments are removed.

An explicit seed controls Core's mapper, Pauli twirling, and numerical synthesis
retries. It overrides pass-local seeds, including nested pipelines. The scoped
seed is captured in MLIR crash reproducers and restored after success or failure.
The new CLI tests use GoogleTest and check both exit status and diagnostics.

Usage

from mqt.core.mlir import CompilationOptions, MappingOptions, compile_program

options = CompilationOptions(
    seed=7,
    enable_timing=True,
    enable_statistics=True,
    mapping=MappingOptions(trials=4, iterations=2, lookahead=10),
)
compiled = compile_program(source, target=device, options=options)
# The same options work with submit_program(source, target=device, options=options).

Typed programs accept options on compile_for_target, synthesize_for_target,
and run_pass_pipeline. C++ compiler entry points accept a final
const CompilationOptions&. Low-level target pipeline builders accept
MappingOptions; execute their pass managers with runWithCompilationOptions
to apply the seed and instrumentation with the same precedence as the compiler API.

mqt-cc input.qasm --qdmi-device mqt.sc.iqm.garnet \
  '--payload-spec=#mqt.payload_spec<format = <id = "qir", version = "2.1.0", profile = "base", encoding = text>, capabilities = [], optional_capabilities_known = false>' \
  --seed 7 --mapping-trials 4 --mapping-iterations 2 --mapping-lookahead 10

--seed also works without a device and with custom or isolated pass pipelines.

Limitations

• seed=None preserves each pass's default or explicit seed. Execution sampling has a separate seed.
• Omitted trials use the available logical CPU count. Set seed and trials for repeatable mapping with a fixed build, input, and target; layouts may change between releases.
• Trials and iterations must be positive. Iterations default to one forward/backward refinement round. Lookahead defaults to 20 additional two-qubit gates; zero considers only the current gate. Lookahead storage follows actual gates, including when the ceiling is SIZE_MAX. All-to-all placement ignores valid mapping controls. The mapper may also consider deterministic candidates.
• Target compilation still requires structured QCO/SCF input and the existing native-synthesis input subset. These controls do not prescribe a layout; ✨ Preserve and control compiler qubit layouts #2553 adds layout selection and reporting.
• Compilation options do not apply to an already compiled payload. Source submission accepts options=None to mean no supplied compiler settings; other compiler entry points take CompilationOptions directly.

Breaking API change

Replace Python enable_timing=True, enable_statistics=True keywords with
options=CompilationOptions(enable_timing=True, enable_statistics=True).
In C++, replace trailing timing/statistics booleans with
CompilationOptions{.enableTiming = true, .enableStatistics = true}.
For source submitProgram, the options object follows the custom job parameters.
Omit options when defaults are sufficient; for compilation and typed methods,
replace explicit options=None with omission or CompilationOptions().

Validation

• 158 Python compiler/QDMI tests pass, including exact mapping diagnostics through every public target entry point.
• 228 native compiler, 115 mapping, and 61 target-synthesis tests pass, including stored-seed precedence and restoration and maximum-lookahead compilation.
• Three CLI CTests pass; the documented target command also succeeds with normal and SIZE_MAX lookahead.
• Stub generation, repository lint, and full-file C++ lint pass.

CI for the latest push is pending.

Release documentation follows the current release-preparation policy. This PR adds no changelog or upgrade-guide entry.

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 96.40288% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Compiler/TargetCompilation.cpp	72.2%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

I have a couple of broader questions on the design here.
I believe we should spend a bit of effort to come up with a good system for these options.
The general addition here makes sense to me.

[burgholzer]

I pushed a couple of changes and simplifications here. These look pretty decent to me 🙌🏼
I'll quickly explore one last thing, then I'll likely merge this!