Transpilation & Optimization
◐ Design-level API
This page documents qalgora-Q API design, architecture, or adaptation workflows. Code examples illustrate intended usage and are not guaranteed to run in the current reference implementation.Before a kernel runs on hardware it is transpiled: rewritten into the device's native gate set and qubit connectivity, then optimized to reduce depth and error.
Why transpile?
- Every QPU has a limited native gate set — arbitrary gates must be decomposed.
- Qubits have a fixed coupling map — two-qubit gates need routing and SWAPs.
- Shorter circuits accumulate less noise, so optimization directly improves fidelity.
Transpiling a kernel
import qalgora
qalgora.set_target("ibm", machine="<backend_name>")
compiled = qalgora.transpile(my_kernel, optimization_level=3)
print("depth:", compiled.depth(), " 2q-gates:", compiled.num_two_qubit_gates())Specification API — not in the open reference build yet
This example shows a qalgora-Q specification API (or a third-party library) that the open reference build does not bundle today. It documents the intended interface; to run code now, use the reference build’s supported core API.Specification API — not implemented yet
Real-hardware execution on a vendor backend requires the corresponding SDK, account credentials, and backend access permissions.Optimization levels
| Level | Behavior |
|---|---|
| 0 | Map to the device only — no optimization |
| 1 | Light optimization (default) |
| 2 | Medium — gate cancellation and commutation |
| 3 | Heavy — best depth, longest compile |
Custom passes
Transpilation is a pipeline of IR passes. Write your own with the
MLIR pass API and slot it into the pipeline.
The MLIR pass API is a planned / specification interface — not implemented in the open reference build yet.
转译与优化
◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。内核在硬件上运行之前，会经历转译过程：将其改写为设备的原生门集合和量子比特连接拓扑，并通过优化降低深度和误差。
为何需要转译
- 每台 QPU 都有有限的原生门集合——任意门必须被分解。
- 量子比特具有固定的耦合图——双量子比特门需要布线和 SWAP。
- 较短的线路积累的噪声更少，因此优化可直接提升保真度。
对内核进行转译
import qalgora
qalgora.set_target("ibm", machine="<backend_name>")
compiled = qalgora.transpile(my_kernel, optimization_level=3)
print("depth:", compiled.depth(), " 2q-gates:", compiled.num_two_qubit_gates())规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。规范接口·暂未实现
厂商真机执行需相应 SDK、账号凭证与后端权限。优化等级
| 等级 | 行为 |
|---|---|
| 0 | 仅映射到设备，不进行优化 |
| 1 | 轻度优化（默认） |
| 2 | 中度优化——门消去与对易 |
| 3 | 重度优化——最佳深度，编译耗时最长 |
自定义 pass
转译是一条由 IR pass 组成的流水线。通过
MLIR pass API 编写自定义 pass 并将其插入流水线。
MLIR pass API 为规划接口·暂未实现，开放参考实现尚未提供。