Compiling Unitaries Using Diffusion Models
◐ 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.Use a trained generative diffusion model to synthesize a gate sequence that realizes a target unitary — an AI-assisted approach to candidate-circuit generation that sits alongside analytic decomposition, search-based synthesis, and numerical optimization, rather than as a drop-in replacement for general analytic decomposition.
Today this is better viewed as a research / experimental workflow than as a mature general-purpose compiler.
The pipeline
- Encode the target unitary as the model's conditioning input.
- Sample the diffusion model to generate candidate circuits.
- Score each candidate by its fidelity to the target.
- Keep the shortest circuit that meets the fidelity threshold.
规范接口·参考实现暂未内置 — diffusion compilation
The diffusion-compile API below (the trained diffusion_model and its sampling call) is a
specification interface; the open reference build does not bundle a trained diffusion compiler yet, so
the snippet is illustrative.
Generating & scoring candidates
import qalgora
target = random_unitary(dim=4) # 4x4 unitary = 2-qubit target
candidates = diffusion_model.sample(target, n=64)
best, best_f = None, 0.0
for circuit in candidates:
u = qalgora.get_unitary(circuit) # simulate the candidate
f = qalgora.unitary_fidelity(u, target)
if f > best_f:
best, best_f = circuit, f
print("best fidelity:", best_f, "depth:", best.depth())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.Scoring unitaries
Compiling a unitary is usually scored with process fidelity / average gate fidelity / a
Hilbert–Schmidt overlap, not state fidelity, and the score should be insensitive to global phase.
When screening candidates, also check the target hardware gate set, connectivity topology, parameter
ranges, noise model, and global-phase equivalence.
Post-generation refinement
Diffusion models typically generate a gate sequence and initial parameters first, then hand off to a
local numerical optimizer that fine-tunes the continuous angles.
When to use
On structured targets covered by the training distribution (small QFT fragments, Hamiltonian-evolution
blocks, hardware-friendly templates), diffusion compilation may propose shorter or more
hardware-friendly candidate circuits — but the payoff depends on the training data, model capacity,
target size, and the downstream optimization.
用扩散模型编译幺正算符
◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。利用已训练的生成式扩散模型合成门序列，实现目标幺正算符——这是解析分解、搜索式综合和数值优化之外的一种 AI 辅助候选电路生成方法，适合作为启发式编译器或初始解生成器，而非通用解析分解的直接替代品。
目前更适合作为研究性/实验性工作流，不是成熟的通用编译器。
处理流程
- 将目标幺正算符编码为模型的条件输入。
- 对扩散模型采样，生成候选电路。
- 以各候选电路与目标的保真度进行评分。
- 保留满足保真度阈值的最短电路。
规范接口·参考实现暂未内置 — 扩散编译
下面的扩散编译接口（已训练的 diffusion_model 及其采样调用）属于规范接口；开源参考实现尚未内置已训练的扩散编译器，因此此处代码仅作示意。
生成与评分候选电路
import qalgora
target = random_unitary(dim=4) # 4x4 unitary = 2-qubit target
candidates = diffusion_model.sample(target, n=64)
best, best_f = None, 0.0
for circuit in candidates:
u = qalgora.get_unitary(circuit) # simulate the candidate
f = qalgora.unitary_fidelity(u, target)
if f > best_f:
best, best_f = circuit, f
print("best fidelity:", best_f, "depth:", best.depth())规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。如何为幺正算符评分
幺正编译通常用 process fidelity / average gate fidelity / Hilbert–Schmidt overlap，而非态保真度；评分应对全局相位不敏感。筛选时还要检查目标硬件门集、连接拓扑、参数范围、噪声模型和全局相位等价性。
生成后的微调
扩散模型通常先生成门序列/初始参数，再接局部数值优化器微调连续角度。
何时使用
在训练分布覆盖的结构化目标（小规模 QFT 片段、哈密顿量演化块、硬件友好模板）上，扩散编译可能提出更短或更硬件友好的候选电路，但效果取决于训练数据、模型容量、目标规模和后续优化。