Language Specification
◐ 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.qalgora-Q defines a kernel language embedded in Python and C++, lowered to the qalgora IR. The public reference build today ships the Python kernel language only; the C++ kernel language, the qalgora++ compiler, and the MLIR toolchain are planned specification interfaces (规划中 · not yet released).
Programming model
- Kernels are pure quantum-classical functions compiled ahead of execution.
- qalgora IR is the MLIR-based dialect that represents quantum programs.
- Targets lower qalgora IR to a specific simulator or hardware backend.
Type system
| Type | Meaning |
|---|---|
qalgora.qubit | A single qubit |
qalgora.qvector | An owned register of qubits |
qalgora.qview | A non-owning reference to qubits passed between kernels |
qalgora.SpinOperator | A weighted sum of Pauli strings |
Two "spin" namespaces — don't confuse them
operators.spin.x/y/z(d) (the dynamics namespace) builds a single-degree-of-freedom
Pauli term for a Hamiltonian handed to evolve. qalgora.SpinOperator and
qalgora.spin.x/y/z(q) build a gate-model Pauli observable — a weighted sum of Pauli
strings — handed to observe. They live in different namespaces and are not interchangeable.
C++ kernel example (规划中 · not runnable yet)
Planned · not runnable yet
The C++ kernel language is a planned specification interface. The example below documents the intended
syntax; it does not run on the open reference build, which ships the Python kernel language only.
#include <qalgora.h>
struct bell {
void operator()() __qpu__ {
qalgora::qvector q(2);
h(q[0]);
cx(q[0], q[1]);
mz(q);
}
};
int main() {
auto counts = qalgora::sample(bell{});
counts.dump();
}C++ API is planned — won’t run today
The runnable reference build is Python-only; the C++ library, its headers and the build tooling shown here are a planned interface and are not published yet, so this snippet will not compile or run as-is. Use the Python API against the reference build to actually run these examples today.Python ↔ C++ naming
Controlled and adjoint forms map across the two front-ends: Python x.ctrl(c, t) ↔ C++
cx(c, t) or x<qalgora::ctrl>(c, t); Python gate.adj(...) ↔ C++
gate<qalgora::adj>(...).
语言规范
◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。qalgora-Q 定义了一套嵌入 Python 与 C++ 的内核语言，并向下编译为 qalgora IR。当前公开参考实现仅提供 Python 内核语言；C++ 内核语言、qalgora++ 编译器和 MLIR 工具链属规划中规范接口（尚未发布）。
编程模型
- 内核是在执行前统一编译的纯量子-经典函数。
- qalgora IR 是基于 MLIR 的方言，用于表示量子程序。
- 目标后端将 qalgora IR 降级到具体的模拟器或硬件后端。
类型系统
| 类型 | 含义 |
|---|---|
qalgora.qubit | 单个量子比特 |
qalgora.qvector | 独占所有权的量子比特寄存器(qvector) |
qalgora.qview | 在内核间传递的非所有权量子比特视图(qview) |
qalgora.SpinOperator | Pauli 串的加权求和 |
两个「spin」命名空间——切勿混淆
operators.spin.x/y/z(d)（动力学命名空间）为传入 evolve 的哈密顿量构造单自由度 Pauli 项；qalgora.SpinOperator 与 qalgora.spin.x/y/z(q) 则构造传入 observe 的门模型 Pauli 可观测量（Pauli 串的加权求和）。二者位于不同命名空间，不可互换。
C++ 内核示例 （规划中 · 暂不可运行）
规划中 · 暂不可运行
C++ 内核语言属规划中规范接口。下方示例仅说明预期语法，无法在仅提供 Python 内核语言的开放参考实现上运行。
#include <qalgora.h>
struct bell {
void operator()() __qpu__ {
qalgora::qvector q(2);
h(q[0]);
cx(q[0], q[1]);
mz(q);
}
};
int main() {
auto counts = qalgora::sample(bell{});
counts.dump();
}C++ 接口为规划中 · 暂不可运行
可运行的参考实现仅提供 Python；此处展示的 C++ 库 头文件与构建工具属于规划中的接口 尚未发布 因此该片段当前无法直接编译或运行。若要真正运行这些示例 请使用 Python API 对接参考实现。Python ↔ C++ 命名对应
受控与伴随形式在两个前端之间一一对应：Python x.ctrl(c, t) ↔ C++ cx(c, t) 或 x<qalgora::ctrl>(c, t)；Python gate.adj(...) ↔ C++ gate<qalgora::adj>(...)。