Add tket transpiler

[yasuhito]

実装方針まとめ（レビュー用・詳細）

ゴール

「Qiskit と同等に tket をバックエンドとして使える」レベルを Tranqu で実現する。

• device を渡せば制約を満たす回路に変換される
• optimization_level で最適化の強さが変わる
• 変換後の回路・統計・mapping（virtual→physical）が返る

---

例（Tranqu 側の利用イメージ）

Qiskit から tket backend を使う

result = tranqu.transpile(
    program=circuit,
    program_lib="qiskit",
    transpiler_lib="tket",
    device=FakeSantiagoV2(),
    device_lib="qiskit",
    transpiler_options={"optimization_level": 1},
)

OpenQASM3 から tket を使う

result = tranqu.transpile(
    program=qasm,
    program_lib="openqasm3",
    transpiler_lib="tket",
    transpiler_options={"optimization_level": 1},
)

---

---

背景（main の現状）

• Tranqu は Qiskit / ouqu-tp の transpiler を持つが、tket は未登録
• ProgramConverter は qiskit <-> tket を既に持つ（pytket-qiskit）
• DeviceConverter は qiskit -> tket が未実装
• Tranqu の統計/マッピングは Qiskit 側と同じ形で返す仕様

---

本PRのスコープ（追加/変更）

• tket transpiler を追加（device あり/なし分岐）
• stats / mapping 取得のための helper を追加
• qiskit -> tket device conversion を追加
• mapping の index 解決（tket の list index 互換）を追加
• tket の最小限の互換性テストを追加

---

設計原則（Qiskit と差異を最小化）

1. Tranqu の使い方は共通（program_lib/transpiler_lib/device_lib の使い方は同じ）
2. device がある場合は backend の既定パスに委譲（Qiskit の preset に相当）
3. mapping を返すために CompilationUnit を使う
4. 最初は pass-through 優先（Qiskit と同様、options は基本そのまま渡す）

---

tket 側の動作仕様

1) device がある場合（推奨ルート）

採用: CompilationUnit + backend.default_compilation_pass()

• 目的: mapping を返すため
• get_compiled_circuit() は回路のみで mapping を取れないため採用しない

処理イメージ

cu = CompilationUnit(circ)
backend.default_compilation_pass(optimisation_level=1).apply(cu)
compiled = cu.circuit
final_map = cu.final_map

2) device がない場合

• optimization_level=0: no-op（回路そのまま）
• optimization_level=1: DecomposeBoxes + SynthesiseTket（デフォルト）
• optimization_level=2: DecomposeBoxes + FullPeepholeOptimise
• 目的: backend 依存の制約が無いので、最小限の変換で安定性を優先

---

optimization_level の扱い（tket）

• tket は 0..2 のみ許可
• 3 は明示的に ValueError（暫定）
• 理由: tket の公式ドキュメントで標準レベルは 0..2

---

共通オプションの扱い（v0 pass-through）

• Qiskit と同様に 基本はそのまま渡す
• tket 側は 不明キーは無視（当面は最小限の吸収のみ）
• 将来 strict_compat を導入して差異を明示化

---

統計 / mapping

• 統計は Qiskit と同じ指標を返す
  • n_qubits, n_gates, n_gates_1q, n_gates_2q, depth
• mapping は virtual → physical で統一
• mapping の出所は CompilationUnit.initial_map / final_map

---

レビュワーに確認したい設計ポイント

• device なし時の挙動: optimization_level=0 は no-op、1 は DecomposeBoxes + SynthesiseTket（デフォルト）、2 は DecomposeBoxes + FullPeepholeOptimise。この段階分けで妥当か。
• optimization_level=3: 現状は ValueError として明示的に拒否（tket 標準が 0..2 のため）。互換性の期待値として問題ないか。
• device あり時のパス: CompilationUnit + backend.default_compilation_pass() に統一し、get_compiled_circuit() は採用しない方針で問題ないか。
• coupling_map 不在時の扱い: qiskit backend に coupling_map が無い場合、full connectivity を仮定して Architecture を構築（コメントで意図を明記）。この前提は妥当か。
• mapping 解決失敗時: qubit が circuit に見つからない場合は例外で fail fast。サイレント fallback ではなく例外で良いか。

公式ドキュメント参照

• Compilation / default compilation pass / optimisation_level / CompilationUnit（mapping 追跡）
  • https://docs.quantinuum.com/tket/user-guide/manual/manual_compiler.html
• Compilation example / get_compiled_circuit
  • https://docs.quantinuum.com/tket/user-guide/examples/circuit_compilation/compilation_example.html
• Qiskit 変換（qiskit_to_tk / tk_to_qiskit, qubit ordering）
  • https://docs.quantinuum.com/tket/user-guide/

[codecov]

Codecov Report

❌ Patch coverage is 79.16667% with 40 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...evice_converter/qiskit_to_tket_device_converter.py	79.72%	15 Missing ⚠️
src/tranqu/device_converter/qiskit_device.py	0.00%	10 Missing ⚠️
src/tranqu/transpiler/tket_layout_mapper.py	75.00%	9 Missing ⚠️
...ranqu/device_converter/device_converter_manager.py	40.00%	3 Missing ⚠️
src/tranqu/transpiler/tket_transpiler.py	92.50%	3 Missing ⚠️

Files with missing lines	Coverage Δ
src/tranqu/device_converter/__init__.py	100.00% <100.00%> (ø)
...m_converter/openqasm3_to_tket_program_converter.py	100.00% <100.00%> (ø)
...gram_converter/qiskit_to_tket_program_converter.py	100.00% <100.00%> (ø)
...m_converter/tket_to_openqasm3_program_converter.py	100.00% <100.00%> (ø)
...gram_converter/tket_to_qiskit_program_converter.py	100.00% <100.00%> (ø)
src/tranqu/tranqu.py	98.41% <100.00%> (+0.05%)	⬆️
src/tranqu/transpiler/__init__.py	100.00% <100.00%> (ø)
src/tranqu/transpiler/tket_stats_extractor.py	100.00% <100.00%> (ø)
...ranqu/device_converter/device_converter_manager.py	90.62% <40.00%> (-9.38%)	⬇️
src/tranqu/transpiler/tket_transpiler.py	92.50% <92.50%> (ø)
... and 3 more

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.