LQCloud SDK

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

关于 API 风格：LQCloud SDK 的线路编排接口（QuantumCircuit / h / cx / measure_all / Parameter / …）在命名与用法上借鉴 Qiskit 风格，便于熟悉 Qiskit 的用户上手；但 SDK 自身不依赖 Qiskit，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 数据
• 脉冲序列模式：lqcloud.sequence 子包提供基于批量对齐（batch-align）的多通道脉冲序列构建（Sequence / Channel / EnvelopeAligner），由 gate_seqs 从本地校准参数翻译 π 脉冲 / 读入等操作，并通过 backend.run_sequence(seq) 以紧凑序列化形式提交（上传体积极小）。详见 脉冲序列 API
• QPU 参数快照管理：本地 SQLite 缓存多组校准参数快照（按日期命名），backend.get_qpu_params() 本地优先、支持复制 / 切换 / 删除快照
• 批量线路：backend.run([qc1, qc2, ...], shots=...) 把多条线路作为同一云端任务提交，单次最多线路条数随 shots 递减：1000 shots 时 2000 条，50 000 shots 时 80 条；提交前会按云端存储上限估算载荷与结果体积，放不下的批量在本地就被拒绝，并提示当前参数下可放多少条
• shots 区间：单次提交 1 ≤ shots ≤ 50_000（MAX_CIRCUIT_SHOTS），SDK 与服务端双向校验；越界在 backend.run() 入口就抛 ValueError，请求不会发出
• 指定物理比特：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_()）

本地任务存储（默认开启）

提交线路与获取结果时自动落盘到 ~/.lqcloud/store/（SQLite 索引 + gzip JSON / npz）， 支持按状态 / 后端 / 标签 / 时间过滤查询、重新加载完整结果、清理旧数据。云端按套餐只保留 一段时间的任务结果，本地库让取回过的结果不受这个期限影响。默认上限 2 GB，超出后自动删除 最旧的记录；用量接近上限或磁盘空间不足时会给出警告。关闭方式：LQCloudProvider(store=False)、环境变量 LQCLOUD_STORE=0，或在 ~/.lqcloud/config.json 中设置 "store": false。零新增依赖。 详见 本地任务存储 API。

异常体系

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

依赖 & 日志

必装依赖为 numpy、requests、envelopes-qc（脉冲包络）、scikit-learn（IQ 聚类分析）与 matplotlib（绘图）；qiskit / networkx 为可选。库内统一使用 logging.getLogger("lqcloud")，可自行配置日志级别。

---

安装

一键安装（推荐，无需预装 Python / pip）

一行命令自动装好 Python 环境、隔离安装 lqcloud 并提示填入 API Key，装完即用：

# Windows (PowerShell)
irm https://cloud.logicalqubit.com/install.ps1 | iex

# macOS / Linux
sh -c "$(curl -fsSL https://cloud.logicalqubit.com/install.sh)"

装完后用统一命令 lq（无需 activate 环境）：lq 看总览、lq shell 进 IPython、 lq run 脚本.py 跑脚本、lq update 升级、lq config 配置 Key、lq help 看全部。

用 pip 安装（已有 Python 环境）

pip install lqcloud

可选依赖：

pip install lqcloud[qiskit]          # Qiskit 互操作
pip install lqcloud[full]            # qiskit + networkx（拓扑可视化）

0.5.0 起 matplotlib 已是必装依赖，lqcloud[visualization] 不再额外安装任何包，仅为兼容旧命令保留。

验证安装：

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("MQ02")

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)   # 1000 shots 时最多 2000 条，50 000 shots 时最多 80 条
results = jobs.result()
results[0].get_counts()       # 每个子项仍是 Result，全部老 API 可用

4. 提交脉冲序列（envelope 级波形）

from lqcloud import LQCloudProvider, Sequence, QpuParams
import lqcloud.sequence.gate_seqs as g

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

params = backend.get_qpu_params()   # 本地优先；无则从云端拉取并缓存为当天快照
qubit = params.qubit(0)             # 取出该比特校准 dict

seq = Sequence()                    # 多通道脉冲序列
end = g.xy_gate(seq, qubit, start=0.0, gate_name="pi")  # X 门（自动用 pi.amp/pi.length/df_10）
g.measure_ring_flattop(seq, qubit, start=end)            # 读入（自动用 read.amp/read.length）

job = backend.run_sequence(seq, shots=1000)   # 紧凑序列化提交（体积极小）
print(job.result().get_counts())

脉冲序列功能由 lqcloud.sequence 子包提供，核心是 Sequence / Channel / EnvelopeAligner （批量对齐 + virtual-Z 相位累积），gate_seqs 提供单比特门与读入辅助，并可通过 backend.list_param_snapshots() / copy_param_snapshot() / use_param_snapshot() 管理多组 本地校准快照。详见 脉冲序列 API。

5. 异常处理

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	必需（核心运行时）
envelopes-qc	必需，脉冲包络构建（lqcloud.sequence，依赖 scipy）
scikit-learn	必需，免标定 IQ 聚类分析（lqcloud.backend.iq_discriminate）
matplotlib	必需，直方图与 IQ 平面绘图
qiskit, qiskit-aer	可选，Qiskit 互操作
networkx	可选，拓扑可视化

Python 版本要求：3.11 或 3.12（requires-python = ">=3.11,<3.13"；3.10 及更早、3.13 及更新均不支持，pip 会直接拒绝安装）

---

许可证

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