lqcloud 0.4.2

A Cloud Quantum Computing SDK

LQCloud SDK

LQCloud SDK 是连接 LQCloud 量子云平台的 Python 开发工具包。通过本 SDK，您可以构建量子线路、提交云端任务（线路 / 波形 / 脚本），并获取执行结果。

关于 API 风格：LQCloud SDK 的线路编排接口（QuantumCircuit / h / cx / measure_all / Parameter / …）在命名与用法上借鉴 Qiskit 风格，便于熟悉 Qiskit 的用户上手；但 SDK 自身不依赖 Qiskit——核心运行时只需 numpy 与 requests 两个轻量依赖。qiskit 仅作为可选互操作组件存在。

---

核心功能

量子线路构建

• Native 门（QPU 原生门，一对一映射硬件）
  • Pauli / Hadamard 族：H, HY, X, Y, Z, MX, MY, MZ, I
  • 半角旋转：XHalf, YHalf, MXHalf, MYHalf, XYHalf, MXYHalf, MXMYHalf, XMYHalf
  • Z 旋转族：S, Sdg, T, RZ(θ)
  • 两比特：CZ（原生）
  • 2 态读出脉冲：X21, X21Half（|1⟩↔|2⟩ 子空间）
  • 测量 / 重置 / 控制：Measure, Reset, Barrier, Delay
  • 手动 DD 门：timeanchor / dd（在成对时间锚点间精确插入 DD 脉冲）
• Composite 门（便捷门，提交前自动分解为 native 门）
  • 单比特：RX(θ), RY(θ), U(θ,φ,λ), P(θ), Tdg, SX, SXdg
  • 两比特：CX(CNOT), CY, CH, SWAP, iSWAP, CRZ(θ), CRX(θ), CRY(θ), CP(θ)
  • 三比特：CCX(Toffoli), CCZ
  • 任意单比特 SU(2) 门：qc.su2(matrix, q) / qc.unitary(matrix, q)
• 统一测量接口：使用 measure / measure_all，SDK 按后端能力自动改写（必要时展开为 X21 + Measure）
• 多重测量（Multi-Window）：同一 qubit 可被多次测量，每次结果独立映射到不同 clbit，支持重复码 / 表面码 stabilizer 线路
• 参数化线路：Parameter + assign_parameters()；提交时仍有未绑定参数会在客户端立即抛 CircuitError
• 线路工具：qc.decompose()、qc.depth()、qc.draw()（ASCII 绘图，支持经典寄存器与多比特门连线）

云端任务提交

• 线路模式：提交 QuantumCircuit 到云端 QPU，序列化时自动 decompose()
• 波形模式：backend.run_wave(waves, shots=..., result_format="counts"|"memory"|"raw") 直接上传原始脉冲波形；raw 返回未经态判别的原始 IQ 数据
• 批量线路：backend.run([qc1, qc2, ...], shots=...) 把多条线路作为同一云端任务提交，单次最多 64 条（MAX_BATCH_CIRCUITS）
• shots 上限：单次提交 shots ≤ 50_000，由服务端校验拦截（SDK 本身不做该范围强校验）
• 指定物理比特：initial_layout=[3, 4]（语义同 Qiskit）
• 读出矫正（Readout Correction）：qc.set_readout_correction(True) / backend.run(..., readout_correction=True)，矫正失败自动降级
• 动态解耦（DD）：空闲窗口自动插入 CPMG / CP π 脉冲；线路级与提交级写法均支持
• 网络健壮性：瞬态错误自动指数退避重试；自动携带 Idempotency-Key 防重复入队
• 提交前本地校验：缺测量 / 缺 barrier / 测量类型混用等会直接抛 CircuitError
• 自动按测量比特数切换 counts / memory 结果格式

任务管理

• 状态查询（JobStatus：QUEUED / RUNNING / COMPLETED / FAILED / CANCELLED）
• 阻塞等待并获取结果（支持 timeout / 静默模式）
• 队列位置查询、任务取消 job.cancel()
• 失败任务携带 error_type，便于编程化重试

结果访问

get_counts() · get_memory() · get_iq_data()（波形 raw）· get_probabilities() · get_dynamic_decoupling_info()；Jupyter 自动渲染结果表格（_repr_html_()）

异常体系

LQCloudError（基类）、AuthenticationError、BackendNotFoundError、JobError、JobTimeoutError、CircuitError，支持精确与粗粒度捕获

轻量依赖 & 日志

核心依赖仅 numpy + requests，qiskit / matplotlib / networkx 均为可选；库内统一使用 logging.getLogger("lqcloud")，可自行配置日志级别。

---

安装

pip install lqcloud

可选依赖：

pip install lqcloud[visualization]   # matplotlib 直方图可视化
pip install lqcloud[qiskit]          # Qiskit 互操作
pip install lqcloud[full]            # matplotlib + qiskit + networkx

验证安装：

python -c "import lqcloud; print(lqcloud.__version__)"

---

快速开始

1. 配置认证

from lqcloud import save_account

save_account(
    api_key="your_api_key_here",
    url="https://cloud.logicalqubit.com",   # 或替换为实际服务器地址
)

配置保存在 ~/.lqcloud/config.json，之后无需重复配置。也可改用环境变量 LQCLOUD_API_KEY（或 LQCLOUD_TOKEN）+ LQCLOUD_URL；无终端环境（CI / Docker）可传 LQCloudProvider(interactive=False)，无凭证时直接抛 AuthenticationError。

2. 提交量子线路任务

from lqcloud import LQCloudProvider, QuantumCircuit

provider = LQCloudProvider()
backend = provider.get_backend("QZ02")

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)        # CX 会被自动分解为 native 门
qc.barrier()       # 计算与读出窗口的分隔
qc.measure_all()

job = backend.run(qc, shots=1000)
result = job.result()
print(result.get_counts())   # {'00': 503, '11': 497}

3. 批量线路提交

jobs = backend.run([qc1, qc2, qc3], shots=2000)   # 单次最多 64 条
results = jobs.result()
results[0].get_counts()       # 每个子项仍是 Result，全部老 API 可用

4. 异常处理

from lqcloud import LQCloudError, JobError, JobTimeoutError

try:
    result = job.result(timeout=300)
except JobTimeoutError:
    job.cancel()
except JobError as e:
    print(f"Job failed: {e}")
except LQCloudError as e:
    print(f"SDK error: {e}")

完整的 API 文档、快速入门与示例代码发布在 LQCloud 云平台文档中心。

---

依赖

包	用途
numpy, requests	必需（核心运行时）
matplotlib	可选，直方图可视化
qiskit, qiskit-aer	可选，Qiskit 互操作
networkx	可选，拓扑可视化

Python 版本要求：≥ 3.10

---

许可证

本项目采用 Apache License 2.0（见随包附带的 LICENSE 文件）。