✨ Support fixed-parameter compiler targets

[simon1hofmann]

🤖 AI text below 🤖

Description

Targets can now restrict individual gate parameters to fixed values. Matching, serialized target attributes, synthesis-basis selection, final verification, and target compatibility checks enforce the same restrictions. This lets downstream adapters describe native fixed-angle pulses without pretending that arbitrary rotations are available.

Single-qubit synthesis derives a pulse sequence from the declared angle and axes: one arbitrary RX/RY/RZ rotation plus a fixed rotation about a different axis. This covers all six axis pairs, both pulse signs, fractional turns, and non-Clifford angles, including fixed RZ. Numerical and symbolic synthesis preserve global phase and emit the declared pulse angle. The pulse sequence is computed once per target; there is no extra compiler pass or numerical search. Unrestricted capabilities use the existing pipeline; parameter values are inspected only for constrained capabilities.

Numeric and symbolic emitters share one pulse recipe. Python exposes target capabilities and basis kinds; the computed pulse plan stays internal.

Usage

from math import pi
from mqt.core.mlir import CompilerTarget

pulse = CompilerTarget.OperationCapability(
    "rz", 1, 1, fixed_parameters=[pi / 4]
)
free_rotation = CompilerTarget.OperationCapability("rx", 1, 1)
target = CompilerTarget(
    num_sites=2,
    connectivity=CompilerTarget.Connectivity.all_to_all(),
    native_operations=CompilerTarget.NativeOperations(
        [free_rotation, pulse, CompilerTarget.OperationCapability("cz", 2, 0)]
    ),
)

fixed_parameters has one entry per parameter: a finite value fixes that parameter, and None leaves it unrestricted. Omit the list for unrestricted parameters. Multiple capabilities describe alternative values or ordered placements. supports_operation(..., parameters=[...]) checks concrete values.

Limitations

• Fixed values use the existing absolute tolerance of 1e-15; angles are not reduced modulo a period because that can change phase.
• Symbolic or unknown values do not satisfy fixed constraints.
• The same arbitrary rotation and fixed pulse must be available on every site. Single-axis targets and integer-π fixed pulses do not supply this universal basis.
• The construction bounds circuit expansion to 64 fixed pulses per effective quarter turn; angles requiring more are not selected for synthesis. Matching native operations remains available for every finite fixed value.
• Available native half turns shorten suitable decompositions. The construction does not promise globally minimal pulse counts.
• This does not add parameter ranges or relations between parameters.
• Symbolic gate-sequence fusion has a separate existing export limitation tracked by 🐛 Preserve symbolic Euler chains in target synthesis #2559; this PR does not resolve it.
• Direct GPI/GPI2, MS, and ZZ synthesis is added by the stacked PR ✨ Add native trapped-ion compiler targets #2578.

Validation

• 235 compiler tests and 64 native-synthesis tests passed. The synthesis suite includes 1,944 full-matrix cases across all six axis pairs, pulse signs, fractional and non-Clifford angles, optional half turns, and numeric or symbolic parameters.
• 386 Python target tests passed, including 360 numerical and symbolic fixed-pulse cases. QDMI fixture tests were excluded from this Python selection; the native compiler suite covers QDMI.
• Generated stubs, repository lint, and full changed-file C++ lint passed.

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.
• 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 92.01183% with 27 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...lib/Dialect/QCO/Transforms/Decomposition/Euler.cpp	82.1%	13 Missing ⚠️
mlir/include/mqt/Compiler/Target.h	0.0%	7 Missing ⚠️
mlir/lib/Dialect/MQT/IR/MQTDialect.cpp	60.0%	4 Missing ⚠️
mlir/lib/Compiler/Target.cpp	98.0%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!