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

C++ API (Planned)

○ Planned · Not yet implemented
The capabilities described on this page are planned and not yet implemented or released. They explain future design directions and should not be interpreted as delivered features.

This page describes the planned qalgora-Q C++ API. The public reference build does not yet ship a C++ library, headers, or the qalgora++ compiler, so the code below cannot be compiled or run directly today. It documents the intended qalgora:: namespace for native, high-performance applications.

A complete program

#include <qalgora.h>

// For observe(): no measurement — the expectation value is taken on the prepared state.
struct prepare_bell {
  void operator()() __qpu__ {
    qalgora::qvector q(2);
    h(q[0]);
    cx(q[0], q[1]);
  }
};

// For sample(): add the measurement to collect bitstrings.
struct measure_bell {
  void operator()() __qpu__ {
    qalgora::qvector q(2);
    h(q[0]);
    cx(q[0], q[1]);
    mz(q);
  }
};

int main() {
  auto counts = qalgora::sample(measure_bell{});   // sampling needs the mz
  counts.dump();

  qalgora::spin_op h = qalgora::spin::z(0) * qalgora::spin::z(1);
  double e = qalgora::observe(prepare_bell{}, h);  // observe takes no mz
  printf("energy = %f\n", e);
}
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.

Controlled, adjoint & control flow

struct circuit {
  void operator()(double theta) __qpu__ {
    qalgora::qvector q(3);
    h(q[0]);
    x<qalgora::ctrl>(q[0], q[1]);        // CNOT: q[0] controls, q[1] is the target
    x<qalgora::ctrl>(q[0], q[1], q[2]);  // Toffoli: the LAST qubit q[2] is the target, q[0],q[1] are controls
    rz<qalgora::adj>(theta, q[2]);       // adjoint modifier; equivalent to rz(-theta, q[2])
    for (int i = 0; i < 3; i++) ry(theta, q[i]);
    mz(q);
  }
};
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.

Key namespaces & types

Namespace / typePurpose
qalgora::qubit / qvector / qviewQubit allocation and references
__qpu__Marks a function/struct-call as a quantum kernel
qalgora::ctrl / adjControl and adjoint gate modifiers
qalgora::sample / observe / get_stateExecution primitives (and _async forms)
qalgora::spin_opPauli-sum operators (spin::x/y/z/i)
qalgora::noise_modelNoise channels and density-matrix simulation
qalgora::kernel_builderRuntime (just-in-time) kernel construction
qalgora::optimizers / gradientsVariational optimization

Building

Compile with the qalgora++ driver, or link via CMake (see Integration).

qalgora++ bell.cpp -o bell --target gpu && ./bell
Python parity
The C++ and Python APIs are mirror images — the same primitives, operators, and modifiers, so algorithms port between them with minimal change.

C++ API（规划中）

○ 规划中
本页所述能力属于规划功能，当前尚未发布或尚未实现。相关内容仅用于说明未来设计方向，不应理解为已交付能力。

本页描述规划中的 qalgora-Q C++ API。当前公开参考实现尚未发布 C++ 库、头文件或 qalgora++ 编译器，下面的代码暂不可直接编译运行；此处记录的是预期的 qalgora:: 命名空间接口，面向原生高性能应用。

完整示例程序

#include <qalgora.h>

// 用于 observe()：不做测量——期望值直接在制备的态上计算
struct prepare_bell {
  void operator()() __qpu__ {
    qalgora::qvector q(2);
    h(q[0]);
    cx(q[0], q[1]);
  }
};

// 用于 sample()：加入测量以收集比特串
struct measure_bell {
  void operator()() __qpu__ {
    qalgora::qvector q(2);
    h(q[0]);
    cx(q[0], q[1]);
    mz(q);
  }
};

int main() {
  auto counts = qalgora::sample(measure_bell{});   // 采样需要 mz
  counts.dump();

  qalgora::spin_op h = qalgora::spin::z(0) * qalgora::spin::z(1);
  double e = qalgora::observe(prepare_bell{}, h);  // observe 不需要 mz
  printf("energy = %f\n", e);
}
C++ 接口为规划中 · 暂不可运行
可运行的参考实现仅提供 Python；此处展示的 C++ 库 头文件与构建工具属于规划中的接口 尚未发布 因此该片段当前无法直接编译或运行。若要真正运行这些示例 请使用 Python API 对接参考实现。

受控、伴随与控制流

struct circuit {
  void operator()(double theta) __qpu__ {
    qalgora::qvector q(3);
    h(q[0]);
    x<qalgora::ctrl>(q[0], q[1]);        // CNOT：q[0] 为控制位，q[1] 为目标位
    x<qalgora::ctrl>(q[0], q[1], q[2]);  // Toffoli：最后一个比特 q[2] 是目标位，q[0]、q[1] 为控制位
    rz<qalgora::adj>(theta, q[2]);       // 伴随修饰符；等价于 rz(-theta, q[2])
    for (int i = 0; i < 3; i++) ry(theta, q[i]);
    mz(q);
  }
};
C++ 接口为规划中 · 暂不可运行
可运行的参考实现仅提供 Python；此处展示的 C++ 库 头文件与构建工具属于规划中的接口 尚未发布 因此该片段当前无法直接编译或运行。若要真正运行这些示例 请使用 Python API 对接参考实现。

核心命名空间与类型

命名空间 / 类型用途
qalgora::qubit / qvector / qview量子比特分配与引用
__qpu__把函数或结构体的调用标记为量子内核
qalgora::ctrl / adj受控与伴随门修饰符
qalgora::sample / observe / get_state执行原语（含 _async 形式）
qalgora::spin_opPauli 和算符（spin::x/y/z/i）
qalgora::noise_model噪声信道与密度矩阵模拟
qalgora::kernel_builder即时（运行时）内核构建
qalgora::optimizers / gradients变分优化

编译构建

用 qalgora++ 驱动编译，或在 CMake 中链接（见 集成指南）。

qalgora++ bell.cpp -o bell --target gpu && ./bell
与 Python 对应
C++ 与 Python API 一一对应——原语、算符、修饰符都一样，算法在两者间移植几乎不用改动。