Python API
◐ 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.
The most common entry points of the qalgora-Q Python package, grouped by purpose.
Reference-build status
The
Status column reflects the open reference build:
Supported = runs today on the local CPU NumPy simulator;
Spec API = documented specification interface, not implemented in the open build yet;
Planned = a distribution or hardware path not released yet. See
Capability Coverage for the full matrix.
Program construction
| Symbol | Purpose | Status |
|---|
@qalgora.kernel | Decorate a function as a quantum kernel | Supported |
qalgora.make_kernel() | Build a kernel imperatively at runtime | Spec API |
qalgora.qubit / qvector / qview | Allocate qubits inside a kernel | Supported |
Kernel execution
| Function | Returns | Status |
|---|
sample() / sample_async() | Measured bitstring histogram | Supported |
run() / run_async() | List of typed kernel return values | Spec API |
observe() / observe_async() | Expectation values | Supported |
get_state() / get_state_async() | Full simulated state | Supported |
vqe() | Run a variational eigensolver loop | Spec API |
evolve() / evolve_async() | Time-evolve a system | Supported |
Backend configuration
| Function | Purpose | Status |
|---|
set_target() / get_target() | Choose / query the execution backend | Supported |
get_targets() | List available targets | Supported |
set_noise() / unset_noise() | Attach a global noise model | Supported |
num_available_gpus() | Count usable GPUs | Planned |
Data types
| Type | Role |
|---|
SampleResult | Counts; most_probable(), probability(b), expectation(), get_marginal_counts() |
ObserveResult | Expectation values; expectation(), per-term access |
EvolveResult | Dynamics output of evolve; expectation_values() returns a 2-D array of shape [n_observables, n_steps] (one row per observable, one column per time step), plus the final and any saved intermediate State objects |
State | Statevector / density matrix; indexable, amplitude(b), dump() |
SpinOperator | Pauli sum; get_term_count(), get_qubit_count(), iterable |
Target | num_qubits, native_gates, connectivity |
Submodules
| Module | Key members |
|---|
qalgora.optimizers | COBYLA, NelderMead, LBFGS, Adam, SGD, SPSA |
qalgora.gradients | ParameterShift, CentralDifference, ForwardDifference |
qalgora.spin | x(i), y(i), z(i), i(i) |
qalgora.operators | boson, fermion, scalar, spin (dynamics) |
qalgora.dynamics / Schedule | Integrators and time schedules for evolve |
qalgora.mpi | initialize(), rank(), num_ranks(), all_gather(), finalize() |
Inspection & utilities
| Function | Purpose | Status |
|---|
draw(kernel, *args, format=) | ASCII or LaTeX circuit diagram | Spec API |
get_ir(kernel) | Dump the qalgora IR | Spec API |
estimate_resources(kernel, *args) | Gate count, depth, qubit count | Spec API |
set_random_seed(n) | Reproducible sampling | Supported |
register_operation(name, matrix) | Add a custom unitary gate | Spec API · not implemented |
Python ↔ C++ parity
In the planned full interface, the Python and
C++ API aim to stay
conceptually aligned in the
qalgora:: namespace; the current public reference build
provides only a subset of these features, on the Python side. See also the
operations reference.
Python API
◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。
qalgora-Q Python 包中最常用的入口，按用途分组整理。
参考实现状态
状态列反映开放参考实现的现状：
参考实现已支持表示当前可在本地 CPU NumPy 模拟器上运行；
规范接口·暂未实现表示已写入规范、开放实现暂未提供；
规划中·尚未发布表示分发或硬件路径尚未发布。完整对照见
能力覆盖。
程序构建
| 符号 | 用途 | 状态 |
|---|
@qalgora.kernel | 将函数修饰为量子内核 | 参考实现已支持 |
qalgora.make_kernel() | 在运行时以命令式方式构建内核 | 规范接口·暂未实现 |
qalgora.qubit / qvector / qview | 在内核内部分配量子比特 | 参考实现已支持 |
内核执行
| 函数 | 返回值 | 状态 |
|---|
sample() / sample_async() | 测量比特串直方图 | 参考实现已支持 |
run() / run_async() | 带类型的内核返回值列表 | 规范接口·暂未实现 |
observe() / observe_async() | 期望值 | 参考实现已支持 |
get_state() / get_state_async() | 完整模拟态 | 参考实现已支持 |
vqe() | 运行变分本征求解器循环 | 规范接口·暂未实现 |
evolve() / evolve_async() | 对系统进行时间演化 | 参考实现已支持 |
后端配置
| 函数 | 用途 | 状态 |
|---|
set_target() / get_target() | 选择或查询执行后端 | 参考实现已支持 |
get_targets() | 列出可用目标后端 | 参考实现已支持 |
set_noise() / unset_noise() | 附加或移除全局噪声模型 | 参考实现已支持 |
num_available_gpus() | 统计可用 GPU 数量 | 规划中·尚未发布 |
数据类型
| 类型 | 说明 |
|---|
SampleResult | 计数；包含 most_probable()、probability(b)、expectation()、get_marginal_counts() |
ObserveResult | 期望值；包含 expectation() 及逐项访问 |
EvolveResult | evolve 的动力学输出；expectation_values() 返回形状为 [n_observables, n_steps] 的二维数组（每个可观测量一行，每个时间步一列），并附带末态及保存的中间 State |
State | 态矢量 / 密度矩阵；支持索引、amplitude(b)、dump() |
SpinOperator | Pauli 和；包含 get_term_count()、get_qubit_count()，可迭代 |
Target | num_qubits、native_gates、connectivity |
子模块
| 模块 | 主要成员 |
|---|
qalgora.optimizers | COBYLA、NelderMead、LBFGS、Adam、SGD、SPSA |
qalgora.gradients | ParameterShift、CentralDifference、ForwardDifference |
qalgora.spin | x(i)、y(i)、z(i)、i(i) |
qalgora.operators | boson、fermion、scalar、spin（动力学） |
qalgora.dynamics / Schedule | 用于 evolve 的积分器与时间表 |
qalgora.mpi | initialize()、rank()、num_ranks()、all_gather()、finalize() |
检查与工具
| 函数 | 用途 | 状态 |
|---|
draw(kernel, *args, format=) | ASCII 或 LaTeX 格式的电路图 | 规范接口·暂未实现 |
get_ir(kernel) | 导出 qalgora IR | 规范接口·暂未实现 |
estimate_resources(kernel, *args) | 门数、深度、量子比特数 | 规范接口·暂未实现 |
set_random_seed(n) | 可复现采样 | 参考实现已支持 |
register_operation(name, matrix) | 添加自定义幺正门 | 规范接口·暂未实现 |
Python 与 C++ 对应
在规划中的完整接口中，Python 与
C++ API 在
qalgora::
命名空间下尽量保持概念对应；当前公开参考实现仅提供 Python 侧的一部分功能。另请参阅
操作参考。