Skip to content

✨ Add Qiskit compiler target conversion - #2655

Merged
burgholzer merged 7 commits into
mainfrom
codex/qiskit-compiler-target
Oct 1, 2026
Merged

burgholzer merged 7 commits into
mainfrom
codex/qiskit-compiler-target

Conversation

@simon1hofmann

@simon1hofmann simon1hofmann commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

🤖 AI text below 🤖

Description

Add CompilerTarget.from_qiskit() in mqt.core.mlir to snapshot a Qiskit
Target or BackendV2 directly in the native adapter. A backend supplies the
default target name; name can override it. The Python forwarding wrapper is
removed.

The snapshot retains supported standard gates, measurement, reset, ordered
operation sites, and undirected routing connectivity. Parameter slots must be
unrestricted. Unrepresentable gates warn and are omitted by default; an
explicit operation_names selection rejects them. Instructions without native
gate applicability are skipped by default. Calibration, timing, and scheduling
data are not copied. The target needs a known positive qubit count and connected
topology.

Target-aware to_qiskit() selects applicable standard gate names, including
legacy u1 and u3, while preserving ordered gate placements. The docs explain
the structural snapshot, synthesis limits, export checks, and its interaction
with the layout metadata added by #2553. Successful export does not establish
device execution support.

No new dependencies are required.

Validation

  • Rebased on c4fb54f4f (main, including ✨ Retain compiler layout metadata #2553).
  • 462 focused Qiskit target and translation tests passed locally.
  • Generated stubs, repository lint, C++ lint, strict documentation build, and
    documentation link checks passed locally. The documentation build suppressed
    existing notebook lexer warnings.

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.

Codex assisted with implementation, tests, validation, review, and this description.

@codecov

codecov Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@simon1hofmann
simon1hofmann force-pushed the codex/qiskit-compiler-target branch from 90a9aad to 48cff49 Compare September 30, 2026 13:52
@simon1hofmann simon1hofmann self-assigned this Sep 30, 2026
@simon1hofmann simon1hofmann added feature New feature or request python Anything related to Python code MLIR Anything related to MLIR labels Sep 30, 2026
@simon1hofmann
simon1hofmann marked this pull request as draft September 30, 2026 15:28
@simon1hofmann

Copy link
Copy Markdown
Contributor Author

@coderabbitai full review

@coderabbitai

coderabbitai Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor
⚠️ Action not completed

Review rate limited.


Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 6 minutes.

@coderabbitai

coderabbitai Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 9ebcd258-689f-4f6b-838c-9f588bba71fd

📥 Commits

Reviewing files that changed from the base of the PR and between 19bc11e and a98ec0b.

📒 Files selected for processing (13)
  • bindings/mlir/qiskit/Qiskit.h
  • bindings/mlir/qiskit/Qiskit2_5.cpp
  • bindings/mlir/qiskit/QiskitExport.cpp
  • bindings/mlir/qiskit/QiskitTranslation.h
  • bindings/mlir/qiskit/QiskitVersion.cpp
  • bindings/mlir/register_mlir.cpp
  • docs/mlir/qiskit.md
  • mlir/lib/Compiler/Target.cpp
  • mlir/unittests/Compiler/test_compiler_target.cpp
  • python/mqt/core/mlir.pyi
  • python/mqt/core/plugins/qiskit/__init__.py
  • python/mqt/core/plugins/qiskit/compiler.py
  • test/python/test_mlir_qiskit_target.py

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.


📝 Summary

Summary by CodeRabbit

  • New Features
    • Added conversion of Qiskit targets and backends into compiler targets, including supported operations and connectivity.
    • Target-aware Qiskit export now selects standard gate names that match the target’s operation and site constraints. Export does not validate the circuit against the target or guarantee device execution support.
  • Documentation
    • Added guidance on converting Qiskit targets and exporting compiled programs, including limitations and validation considerations.
  • Bug Fixes
    • Canonicalized the legacy u1 gate name to p.

Walkthrough

Qiskit targets and backends can now be converted to CompilerTarget objects. Target-aware Qiskit export selects supported standard gate names using operation and site data. The changes also add u1 canonicalization, native gate recognition, tests, and documentation.

Changes

Qiskit Target Conversion

Layer / File(s) Summary
Convert Qiskit targets
python/mqt/core/plugins/qiskit/*, test/python/test_mlir_qiskit_target.py, docs/mlir/qiskit.md
Adds and exports compiler_target_from_qiskit. The conversion validates source and qubit count, filters representable operations, derives connectivity, and has tests for supported and rejected target features. The documentation describes conversion and its constraints.
Select target-matched Qiskit gates
bindings/mlir/qiskit/*, bindings/mlir/register_mlir.cpp, mlir/lib/Compiler/Target.cpp, mlir/unittests/Compiler/test_compiler_target.cpp, python/mqt/core/mlir.pyi, test/python/test_mlir_qiskit_target.py
Passes an optional target through circuit creation and writer construction. Gate selection checks translation, arity, parameter count, and site tuples. Adds native gate-name recognition, u1 to p canonicalization, and export tests for aliases, control flow, and backend bases.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CompilerTarget
  participant exportCircuit
  participant NativeTranslation
  participant NativeCircuitWriter
  CompilerTarget->>exportCircuit: target argument
  exportCircuit->>NativeTranslation: createCircuit with target
  NativeTranslation->>NativeCircuitWriter: construct writer with target
  NativeCircuitWriter->>NativeCircuitWriter: match gate using target operation and qubit sites
Loading

Suggested reviewers: burgholzer

Merge Risk: ⚪ Minimal · up to a98ec

No concrete merge-blocking issue is established. The conversion and target-aware export changes appear mergeable subject to normal checks; successful export does not guarantee device execution support.

Security Architecture Review

Security architecture risk: 🔵 Low · up to a98ec

The examined conversion and export paths retain structural validation and select only known gate implementations. No introduced security issue was demonstrated. Concurrent modification during conversion and security boundaries of applications embedding these APIs remain unestablished.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The demonstrated exposure is caller-supplied Python target inspection and in-process circuit construction. The examined path does not establish a remote entrypoint, tenant boundary or hardware-execution authority; deployment exposure remains unknown.

Trust Boundaries and Controls

  • observed — Target-derived names and placements cross into validated CompilerTarget storage. At emission, names select known gate entries, ordered placements constrain alias selection, and native arity and parameter checks precede gate construction. Target strings do not become native call targets or import paths.
  • inferred — Accepting Python Target or BackendV2 objects permits their methods and properties to run during inspection. This API is not a sandbox for hostile Python objects; no additional privilege grant or security isolation contract was established.

Resilience and Maintainability Implications

  • observed — Export normalizes a cloned program and validates supported forms before constructing the returned circuit. This contains translation failures without modifying the caller's source program.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 12 files. (1 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly and concisely identifies the main change: adding Qiskit compiler target conversion.
Description check ✅ Passed The description is detailed and covers the change, motivation, behavior, dependencies, validation, documentation, and AI disclosures. Two checklist items remain unchecked, but the description is other…
Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 42 functions across 12 files. (1 skipped: 1 unsupported.)

  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit checks the gate names bright,
Then hops through sites in ordered flight.
A target settles into view,
While u1 wears p anew.
The moon nods: export tests pass tonight.

Comment @coderabbitai help to get the list of available commands.

@simon1hofmann

Copy link
Copy Markdown
Contributor Author

@coderabbitai full review

@coderabbitai

coderabbitai Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor
✅ Action performed

Full review finished.

@simon1hofmann
simon1hofmann marked this pull request as ready for review October 1, 2026 07:50

@denialhaag denialhaag left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This already looks pretty good to me! Thanks, @simon1hofmann! 🙂

I only have one comment that I would be curious to hear your opinion on:

Comment thread python/mqt/core/plugins/qiskit/compiler.py Outdated

@denialhaag denialhaag left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM now! I'll leave the final approval to @burgholzer! 😎

(You may ignore and resolve the nitpick below. 🤠)

Comment thread bindings/mlir/register_mlir.cpp Outdated
@burgholzer

Copy link
Copy Markdown
Member

Let me try to get a quick review in here. Don't want to be the blocker here.

simon1hofmann and others added 7 commits October 1, 2026 22:27
🤖 *AI text below* 🤖

Centralize structural Target and BackendV2 snapshots while preserving
ordered operation applicability and rejecting unrepresentable constraints.
Document compiled-output export as the capability check for consumers.

Assisted-by: Codex
🤖 *AI text below* 🤖

Reuse native gate recognition and retain backend aliases through target
serialization and Qiskit export. Omit unsupported extras by default while
keeping explicit operation selection strict.

Move target regressions to the MLIR tests and fix the API documentation
reference.

Assisted-by: Codex
🤖 *AI text below* 🤖

Pass the optional canonical name by const reference through both target
constructors and their bindings. Normalize the selected string directly
without making an extra value_or copy.

Assisted-by: Codex
Use Qiskit target matching for unrestricted parameters and reject explicit selections without native applicability. Exclude controlled import mappings that the compiler cannot retain as native operations.

Keep legacy standard gate export without custom instruction wrappers or canonical-name schema overrides.

Validated 579 Python, 55 native, and 104 downstream integration tests, stub generation, repository lint, whole-file C++ lint, and the full documentation build with link checks.

Assisted-by: Codex
🤖 *AI text below* 🤖

Return an owned CompilerTarget from the versioned Qiskit adapter and keep gate recognition private. Retain the public Python wrapper for backend normalization and default naming, and reuse existing target validation.

Preserve selection, warnings, parameter constraints, and target snapshots. Add direct binding and warning regressions and regenerate the stubs.

Validated 581 Python tests, repository lint, full-file C++ lint, stub generation, and the full executable documentation build with local link checks. The two Garnet tests passed when rerun with the existing local device library.

Assisted-by: Codex
🤖 *AI text below* 🤖

Separate the summary from the details with a blank line in the native
binding and regenerate the Python stub.

Validated stub generation, the runtime docstring, repository lint,
full-file C++ lint, and the full docs build with local link checks.

Assisted-by: Codex
🤖 *AI text below* 🤖

Accept Target and BackendV2 directly in the native adapter and expose
CompilerTarget.from_qiskit. Remove the Python forwarding wrapper.

Document operation selection, target mapping, and layout behavior. Simplify
the Qiskit guide and avoid alias scans for unrelated gates.

Preserve the layout metadata contract from merged PR #2553.

Assisted-by: Codex
@burgholzer
burgholzer force-pushed the codex/qiskit-compiler-target branch from 09ff676 to 80a54e8 Compare October 1, 2026 22:56
@burgholzer burgholzer self-assigned this Oct 1, 2026

@burgholzer burgholzer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright. This is looking pretty good now as well. I folded the layout changes into here. I'll merge once CI passes to also get the other PR along 🚀

@burgholzer
burgholzer enabled auto-merge (squash) October 1, 2026 23:08
@burgholzer
burgholzer merged commit a202c7a into main Oct 1, 2026
26 checks passed
@burgholzer
burgholzer deleted the codex/qiskit-compiler-target branch October 1, 2026 23:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

feature New feature or request MLIR Anything related to MLIR python Anything related to Python code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants