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

Troubleshooting

Common issues and how to resolve them.

No GPU target available

The GPU backend is not yet published in the open reference build. Calling qalgora.set_target("gpu") should warn and fall back to CPU, or report that it is unavailable; verify with cpu or density-matrix-cpu instead (cpu is an alias of qpp-cpu):

# qalgora-smi                          # planned GPU build — not available yet
# python3 -m pip install qalgora-gpu   # planned GPU build — not available yet

Kernel compilation errors

  • Ensure every kernel argument has a type annotation.
  • Avoid unsupported Python features (generators, comprehensions over qubits, exceptions).
  • Use qalgora.qvector/qalgora.qview rather than plain lists for qubits.

Debugging & verbose output

Inspect what the compiler produced and turn on verbose simulation logs.

Specification API — not implemented yet
qalgora.draw and qalgora.get_ir are specification interfaces; the open reference build does not emit circuit drawings or qalgora IR yet.
import qalgora
qalgora.set_random_seed(13)          # make sampling reproducible
# assume `bell` is defined (see Running your first Program)
print(qalgora.draw(bell))            # confirm the circuit is what you meant
print(qalgora.get_ir(bell))          # dump qalgora IR

import os
os.environ["QALGORA_LOG_LEVEL"] = "info"   # verbose simulation output
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.

Reading Python stack traces

Errors inside a kernel are reported against your source line. The most common are an un-annotated argument, an unsupported construct, or indexing a register out of range — the trace names the offending kernel and line.

Unexpected measurement statistics

  • Too noisy? Raise shots_count (e.g. 10000) to shrink sampling error.
  • Wrong bitstring order? qalgora-Q reads most-significant qubit first; reverse if comparing against a little-endian framework.
  • Forgot to measure? A kernel with no mz returns empty counts — add an explicit measurement.
  • Non-deterministic across runs? Set qalgora.set_random_seed.
Validate on a simulator first
Reproduce on the cpu or density-matrix-cpu target before blaming hardware — most surprises are circuit bugs, not device noise.

故障排查

常见问题及解决方法。

无可用 GPU 目标后端

GPU 后端尚未在开放参考实现中发布；调用 set_target('gpu') 应提示并回退到 CPU，或提示不可用；请用 cpu 或 density-matrix-cpu 验证（cpu 是 qpp-cpu 的别名）。

# qalgora-smi                          # 规划中的 GPU 版本——暂不可用
# python3 -m pip install qalgora-gpu   # 规划中的 GPU 版本——暂不可用

内核编译报错

  • 确保每个内核参数都带有类型标注。
  • 避免使用不支持的 Python 特性（生成器、对量子比特的推导式、异常处理等）。
  • 操作量子比特时请使用 qalgora.qvector/qalgora.qview，而非普通列表。

调试与详细输出

查看编译器生成的内容，并开启详细的模拟器日志。

规范接口 · 暂未实现
qalgora.draw 与 qalgora.get_ir 属规范接口；开放参考实现尚未输出电路图或 qalgora IR。
import qalgora
qalgora.set_random_seed(13)          # 使采样可复现
# 假设 bell 已定义（见「运行第一个程序」）
print(qalgora.draw(bell))            # 确认电路与预期一致
print(qalgora.get_ir(bell))          # 导出 qalgora IR

import os
os.environ["QALGORA_LOG_LEVEL"] = "info"   # 详细模拟输出
规范接口 · 参考实现暂未包含
此示例展示的是 qalgora-Q 规范中的接口（或第三方库），开放参考实现目前尚未内置，仅用于说明预期用法；如需立即运行，请使用参考实现已支持的核心 API。

读懂 Python 堆栈跟踪

内核内部的错误会定位到源代码行号。最常见的原因是参数缺少类型标注、使用了不支持的语法结构，或对寄存器的索引越界——堆栈跟踪会指明出错的内核名称和行号。

测量统计结果异常

  • 噪声过大？ 增大 shots_count（例如设为 10000）以缩小采样误差。
  • 比特串顺序错误？ qalgora-Q 以高位量子比特优先读取；若与小端框架对比，请先反转顺序。
  • 忘记测量？ 没有 mz 的内核会返回空计数——请添加显式测量操作。
  • 多次运行结果不一致？ 请设置 qalgora.set_random_seed 以固定随机种子。
先在 cpu 或 density-matrix-cpu 复现
在归因于硬件之前，请先在 cpu 或 density-matrix-cpu 目标后端上复现问题——大多数意外结果源于线路缺陷，而非设备噪声。