Metadata-Version: 2.4
Name: lqcloud
Version: 0.5.0
Summary: A Cloud Quantum Computing SDK
Author: Lianming LQ
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: requests>=2.31.0
Requires-Dist: envelopes-qc>=0.1.3
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: matplotlib>=3.3.0
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.3.0; extra == "visualization"
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
Requires-Dist: qiskit-aer>=0.13.0; extra == "qiskit"
Provides-Extra: full
Requires-Dist: matplotlib>=3.3.0; extra == "full"
Requires-Dist: qiskit>=1.0.0; extra == "full"
Requires-Dist: qiskit-aer>=0.13.0; extra == "full"
Requires-Dist: networkx>=2.5; extra == "full"
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.30.0; extra == "pennylane"
Provides-Extra: ci
Requires-Dist: pytest>=7.0.0; extra == "ci"
Requires-Dist: pytest-timeout>=2.0.0; extra == "ci"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: ruff==0.16.2; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: cryptography>=41.0.0; extra == "dev"
Dynamic: license-file

# LQCloud SDK

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/downloads/)
![Version](https://img.shields.io/badge/version-0.5.0-brightgreen.svg)

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](https://cloud.logicalqubit.com/#docs/docs/sequence_api.md)
- **QPU 参数快照管理**：本地 SQLite 缓存多组校准参数快照（按日期命名），`backend.get_qpu_params()` 本地优先、支持复制 / 切换 / 删除快照
- **批量线路**：`backend.run([qc1, qc2, ...], shots=...)` 把多条线路作为同一云端任务提交，单次最多 64 条（`MAX_BATCH_CIRCUITS`）
- **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_()`）

### 本地任务存储（可选）

`LQCloudProvider(store=True)` 开启后，提交线路与获取结果时自动落盘到
`~/.lqcloud/store/`（SQLite 索引 + gzip JSON / npz），支持按状态 / 后端 /
标签 / 时间过滤查询、重新加载完整结果、清理旧数据。默认**关闭**，零新增依赖。
详见 [本地任务存储 API](https://cloud.logicalqubit.com/#docs/docs/local_store_api.md)。

### 异常体系

`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，装完即用：

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

```bash
# 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 环境）

```bash
pip install lqcloud
```

可选依赖：

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

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

验证安装：

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

---

## 快速开始

### 1. 配置认证

```python
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. 提交量子线路任务

```python
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. 批量线路提交

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

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

```python
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](https://cloud.logicalqubit.com/#docs/docs/sequence_api.md)。

### 5. 异常处理

```python
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 云平台文档中心](https://cloud.logicalqubit.com/#docs/README.md)**。

---

## 依赖

| 包 | 用途 |
|----|------|
| `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 文件）。
