Integration & Interop
◐ 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.Drop qalgora-Q into existing C++ builds and scientific Python stacks.
What runs today
Only the Python interop shown below works against the open reference build
(supported · 参考实现已支持). The C++ build integration, GPU/MPI distributed execution, and
the IR/MLIR/custom-backend paths are planned / specification interfaces
(planned, not yet released · 规划中·尚未发布 / spec interface, not implemented · 规范接口·暂未实现):
they document the intended design, not shipped functionality.CMake integration (C++)
find_package(qalgora REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE qalgora::qalgora)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.Compiling a C++ kernel
qalgora++ main.cpp -o my_app --target gpu && ./my_appInterfacing with Python libraries
Kernels return ordinary Python objects, so results flow straight into NumPy, SciPy, and PyTorch:
import numpy as np
import qalgora
counts = qalgora.sample(kernel, shots_count=10000)
probs = np.array([counts.probability(b) for b in counts])
# feed `probs` into any classical optimizer / ML pipelineDistributed execution with MPI
Planned runtime capability
MPI / GPU distributed execution
(qalgora.mpi.* and set_target("gpu", option="mqpu") below) is a planned
runtime capability; the current Python reference build does not include it yet.qalgora.mpi.initialize()
rank = qalgora.mpi.rank()
# qalgora.set_target("gpu", option="mqpu") # planned: multi-GPU/QPU backend, not in the open reference build
result = qalgora.observe(kernel, hamiltonian) # work auto-distributed
qalgora.mpi.finalize()集成与互操作
◐ 设计接口
本页描述的是 qalgora-Q 的接口设计、架构设计或适配工作流。相关代码用于说明预期用法，当前参考实现不保证可以直接运行。将 qalgora-Q 嵌入现有 C++ 构建体系和 Python 科学计算栈。
当前可运行范围
下方仅 Python 互操作在开放参考实现中可用（参考实现已支持）。C++ 构建集成、GPU/MPI 分布式执行，
以及 IR/MLIR/自定义后端路径均为规划中·尚未发布或规范接口·暂未实现，
仅用于说明预期设计，并非已交付功能。CMake 集成（C++）
find_package(qalgora REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE qalgora::qalgora)C++ 接口为规划中 · 暂不可运行
可运行的参考实现仅提供 Python；此处展示的 C++ 库 头文件与构建工具属于规划中的接口 尚未发布 因此该片段当前无法直接编译或运行。若要真正运行这些示例 请使用 Python API 对接参考实现。编译 C++ 内核
qalgora++ main.cpp -o my_app --target gpu && ./my_app与 Python 库对接
内核返回普通 Python 对象，结果可直接流入 NumPy、SciPy 和 PyTorch：
import numpy as np
import qalgora
counts = qalgora.sample(kernel, shots_count=10000)
probs = np.array([counts.probability(b) for b in counts])
# feed `probs` into any classical optimizer / ML pipeline基于 MPI 的分布式执行
规划中运行时能力
MPI / GPU 分布式执行属规划中运行时能力，当前 Python 参考实现暂未包含。qalgora.mpi.initialize()
rank = qalgora.mpi.rank()
# qalgora.set_target("gpu", option="mqpu") # 规划中：多 GPU / 多 QPU 后端，参考实现暂未包含
result = qalgora.observe(kernel, hamiltonian) # work auto-distributed
qalgora.mpi.finalize()