Metadata-Version: 2.4
Name: lqcloud
Version: 0.4.2
Summary: A Cloud Quantum Computing SDK
Author: Lianming LQ
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: requests>=2.31.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: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; 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.10+-blue.svg)](https://www.python.org/downloads/)
![Version](https://img.shields.io/badge/version-0.4.2-brightgreen.svg)

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")`，可自行配置日志级别。

---

## 安装

```bash
pip install lqcloud
```

可选依赖：

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

验证安装：

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

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

### 4. 异常处理

```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 云平台文档中心**。

---

## 依赖

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

Python 版本要求：**≥ 3.10**

---

## 许可证

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