qalgora-Q Docs Hub量子文档 ✦ Ask AI✦ 问问文档
/

Working with qalgora IR

◐ 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.

Inspect and transform the intermediate representation a kernel lowers to — useful for debugging, custom passes, and hardware mapping.

Spec API — not in the reference build yet
get_ir, the qalgora-opt pass driver, and the .qke file format are documented specification interfaces (规范接口·参考实现暂未包含); the open reference build does not bundle them yet.

Dumping the IR

import qalgora

@qalgora.kernel
def bell():
    q = qalgora.qvector(2)
    h(q[0]); x.ctrl(q[0], q[1]); mz(q)

print(qalgora.get_ir(bell))      # textual qalgora IR (MLIR dialect)
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.

The dump is text in the qalgora IR dialect. For the kernel above it looks roughly like:

func.func @bell() {
  %q = quantum.alloc : !quantum.veq<2>
  %q0 = quantum.extract %q[0] : !quantum.ref
  %q1 = quantum.extract %q[1] : !quantum.ref
  quantum.h %q0 : !quantum.ref
  quantum.x [%q0] %q1 : !quantum.ref          // brackets = control list; %q1 is the target
  %bits = quantum.mz %q : !quantum.veq<2> -> !quantum.bits<2>
  quantum.dealloc %q : !quantum.veq<2>
  return
}
Illustrative format
This snippet is an illustrative textual form of qalgora IR; the op names, result bindings, memory deallocation, and dialect naming follow the actual compiler version.

Running optimization passes

# apply the standard optimization pipeline to a .qke file
qalgora-opt bell.qke --canonicalize --gate-fusion -o bell_opt.qke
Round-trip
IR is text — dump it, transform it with your own tool, and feed it back in. The compiler re-verifies every program before execution.

使用 qalgora IR

◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。

查看并变换内核降级后生成的中间表示——适用于调试、自定义 pass 以及硬件映射。

导出 IR

import qalgora

@qalgora.kernel
def bell():
    q = qalgora.qvector(2)
    h(q[0]); x.ctrl(q[0], q[1]); mz(q)

print(qalgora.get_ir(bell))      # textual qalgora IR (MLIR dialect)
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

上面的内核导出的是 qalgora IR 方言文本，大致如下：

func.func @bell() {
  %q = quantum.alloc : !quantum.veq<2>
  %q0 = quantum.extract %q[0] : !quantum.ref
  %q1 = quantum.extract %q[1] : !quantum.ref
  quantum.h %q0 : !quantum.ref
  quantum.x [%q0] %q1 : !quantum.ref          // 方括号为控制位列表；%q1 为目标位
  %bits = quantum.mz %q : !quantum.veq<2> -> !quantum.bits<2>
  quantum.dealloc %q : !quantum.veq<2>
  return
}
示意格式
该片段为 qalgora IR 的示意性文本格式；op 名称、返回值绑定、内存释放和方言命名以实际编译器版本为准。

运行优化 pass

# apply the standard optimization pipeline to a .qke file
qalgora-opt bell.qke --canonicalize --gate-fusion -o bell_opt.qke
往返
IR 是文本格式——可以导出、用自定义工具进行变换，再重新输入。编译器在每次执行前都会对程序进行校验。