Metadata-Version: 2.4
Name: jiuzhang-sdk
Version: 0.1.0a12
Summary: 九章光量子真机云接入软件包（jiuzhang SDK）
Author: 九章量子 SDK 团队
License: Proprietary
Keywords: gbs,jiuzhang,photonic,quantum,sdk
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: jupyter
Requires-Dist: ipython>=8; extra == 'jupyter'
Description-Content-Type: text/markdown

# ⚛️ 九章光量子云平台 Python SDK

🌐 [English](https://github.com/JiuZhangLiangZi/jiuzhang-sdk/blob/main/README_EN.md) | 简体中文

`jiuzhang` 是面向九章光量子云平台的 Python SDK。

它提供简洁、类型化、适合脚本和 Notebook 使用的接口，帮助用户提交高斯玻色采样（Gaussian Boson Sampling, GBS）任务、查询任务状态、获取实验结果，并对返回数据进行基础分析。

## 📦 安装

使用 pip 安装：

```bash
pip install jiuzhang-sdk
```

安装预发布版本：

```bash
pip install --pre jiuzhang-sdk
```

安装指定版本：

```bash
pip install jiuzhang-sdk==0.1.0a12
```

## 🚀 快速开始

请先准备平台提供的：

* 🔑 API Key
* 🖥️ 量子计算机 ID

推荐通过环境变量配置密钥和默认量子计算机 ID，避免在代码中明文写入敏感信息。

### 🍎 macOS / Linux

```bash
export JIUZHANG_API_KEY="your_api_key_here"
export JIUZHANG_DEFAULT_MACHINE_ID="your_machine_id_here"
```

### 🪟 Windows PowerShell

```powershell
$env:JIUZHANG_API_KEY="your_api_key_here"
$env:JIUZHANG_DEFAULT_MACHINE_ID="your_machine_id_here"
```

提交一个最小 GBS 任务：

```python
import os

from jiuzhang import CloudClient, GBSParams

client = CloudClient.from_env()

params = GBSParams(
    machine_id=int(os.environ["JIUZHANG_DEFAULT_MACHINE_ID"]),
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
    task_name="GBS quickstart demo",
)

result = client.run_gbs(params)

print("Task ID:", result.task_id)
print("Status:", result.status_name)
print("Experimental distribution:", result.experimental_distribution)

client.close()
```

## 🧩 核心概念

### ☁️ CloudClient
![CloudClient.png](https://raw.githubusercontent.com/JiuZhangLiangZi/jiuzhang-sdk/main/imgs/CloudClient.png)
`CloudClient` 是 SDK 的主要入口，用于连接九章光量子云平台。

它负责：

* 📝 创建请求
* 🚀 提交任务
* 🔄 查询任务状态
* 📥 获取任务结果
* 🔍 解析平台返回数据

推荐使用环境变量创建客户端：

```python
from jiuzhang import CloudClient

client = CloudClient.from_env()
```

也可以手动传入 API Key：

```python
from jiuzhang import CloudClient

client = CloudClient(api_key="your_api_key_here")
```

### ⚛️ GBSParams

`GBSParams` 用于定义高斯玻色采样任务参数。

```python
from jiuzhang import GBSParams

params = GBSParams(
    machine_id=123456789,
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
    task_name="my-gbs-task",
)
```

常用参数：

| 参数                | 类型              | 说明         |
| ----------------- | --------------- | ---------- |
| `machine_id`      | `int`           | 目标量子计算机 ID |
| `mt`              | `int`           | 时间模式数      |
| `pump_energy_nj`  | `float`         | 泵浦能量，单位 nJ |
| `squeezing_param` | `float \| None` | 压缩参数       |
| `shots`           | `int \| None`   | 采样次数       |
| `task_name`       | `str`           | 任务名称       |

### 📊 GBSResult

`GBSResult` 是任务执行结果的解析对象。

```python
result = client.run_gbs(params)

print(result.task_id)
print(result.status_name)
print(result.experimental_distribution)
```

常用字段：

| 字段                          | 说明       |
| --------------------------- | -------- |
| `task_id`                   | 平台任务 ID  |
| `status_name`               | 标准化任务状态  |
| `machine_id`                | 量子计算机 ID |
| `experimental_distribution` | 实验分布数据   |
| `ground_truth_distribution` | 参考分布数据   |
| `result_map_points`         | 结果可视化数据点 |
| `download_url`              | 结果文件下载地址 |
| `raw`                       | 原始响应数据   |

## 💡 使用示例

### 🔮 估算任务

```python
estimate = client.estimate_gbs(params)

print(estimate)
```

### 🚀 提交任务

```python
task = client.submit_gbs(params)

print(task)
```

### 📥 查询结果

```python
result = client.get_result("your_task_id_here")

print(result)
```

### ⏳ 提交并等待结果

```python
result = client.run_gbs(
    params,
    poll_interval=1.0,
    timeout=60.0,
)

print(result.status_name)
```

## 📒 Jupyter Notebook 集成

SDK 提供适合 Notebook 场景的辅助方法。

```python
from jiuzhang import GBSParams
from jiuzhang.jupyter import (
    get_notebook_client,
    show_environment,
    display_gbs_result,
)

show_environment()

client = get_notebook_client()

params = GBSParams(
    machine_id=123456789,
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
)

result = client.run_gbs(params)

display_gbs_result(result)
```

`show_environment()` 会显示当前运行环境配置，并对 API Key 做脱敏处理。

## ✨ 功能特性

### 🔄 任务生命周期管理

SDK 封装了云端任务的完整生命周期：

* 🏗️ 构造任务参数
* ✅ 校验任务参数
* 🚀 提交 GBS 任务
* 🔄 轮询任务状态
* 📥 获取任务结果
* 🔍 解析返回数据

### 🏷️ 类型化参数

SDK 使用 `GBSParams` 对任务输入进行封装，使参数结构更加清晰，便于在脚本、服务端程序和 Notebook 中复用。

```python
params = GBSParams(
    machine_id=123456789,
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
)
```

### 📈 结果分析

`jiuzhang.gbs.analysis` 模块提供常用的采样结果分析工具。

```python
from jiuzhang.gbs.analysis import (
    photon_count_histogram,
    click_count_histogram,
    collision_rate,
    total_variation_distance,
)

photon_hist = photon_count_histogram(samples)
click_hist = click_count_histogram(samples)
collision = collision_rate(samples)
```

常用方法：

| 方法                                | 说明                   |
| --------------------------------- | -------------------- |
| `photon_count(samples)`           | 计算每个样本的总光子数          |
| `photon_count_histogram(samples)` | 生成光子数直方图             |
| `click_count(samples)`            | 计算每个样本的 click 数      |
| `click_count_histogram(samples)`  | 生成 click 数直方图        |
| `mode_occupancy(samples)`         | 统计各模式占用情况            |
| `collision_rate(samples)`         | 计算 collision 样本比例    |
| `top_k_patterns(samples, k=20)`   | 获取高频采样模式             |
| `total_variation_distance(p, q)`  | 计算总变差距离              |
| `hellinger_distance(p, q)`        | 计算 Hellinger 距离      |
| `js_divergence(p, q)`             | 计算 Jensen-Shannon 散度 |

### 📒 Notebook 友好

SDK 支持在 Jupyter Notebook 中快速创建客户端、检查运行环境和展示 GBS 任务结果，适合教学、实验演示和数据分析场景。

## 🌱 环境变量

推荐使用环境变量管理平台连接信息：

| 环境变量                          | 说明         |
| ----------------------------- | ---------- |
| `JIUZHANG_API_KEY`            | 平台 API Key |
| `JIUZHANG_DEFAULT_MACHINE_ID` | 默认量子计算机 ID |

示例：

```python
from jiuzhang import CloudClient

client = CloudClient.from_env()
```

## 🏗️ 架构

SDK 采用轻量级客户端架构：

![structure-chart.png](https://raw.githubusercontent.com/JiuZhangLiangZi/jiuzhang-sdk/main/imgs/structure-chart.png)

| 层级    | 作用                      | 主要组件                                    |
|-------|-------------------------|-----------------------------------------|
| 用户层   | Python 脚本、Notebook、业务程序 | 用户代码                                    |
| SDK 层 | 任务参数、任务提交、结果解析          | `CloudClient`, `GBSParams`, `GBSResult` |
| 通信层   | 请求构造、认证、HTTP 通信         | `TokenManager`, HTTP Client             |
| 云平台层  | 远程量子计算服务                | 九章光量子云平台                                |

SDK 作为云平台客户端使用，不要求用户管理底层量子硬件、服务调度或任务执行环境。

## 🧱 组件说明

![module.png](https://raw.githubusercontent.com/JiuZhangLiangZi/jiuzhang-sdk/main/imgs/module.png)

* ☁️ `CloudClient`：云平台客户端，负责任务提交、查询和结果获取
* ⚛️ `GBSParams`：GBS 任务参数对象
* 📊 `GBSResult`：GBS 任务结果对象
* 🔐 `TokenManager`：API Key 管理与脱敏工具
* 📈 `jiuzhang.gbs.analysis`：采样结果分析工具
* 📒 `jiuzhang.jupyter`：Notebook 集成工具

## ⚠️ 错误处理

SDK 会针对请求失败、参数错误、认证失败、任务超时等情况抛出 Python 异常。

```python
from jiuzhang import CloudClient, GBSParams
from jiuzhang.exceptions import JiuZhangError

try:
    client = CloudClient.from_env()
    result = client.run_gbs(params)
except JiuZhangError as exc:
    print("JiuZhang SDK error:", exc)
```

## ✅ 最佳实践

* 🔑 使用环境变量保存 API Key。
* 🚫 不要在 Notebook 或源代码中明文写入真实密钥。
* 🌱 在共享环境中优先使用 `CloudClient.from_env()`。
* ⏳ 长时间任务建议设置明确的 `timeout`。
* 🔒 使用完成后调用 `client.close()` 关闭连接。
* 🧾 保存任务参数和结果，便于后续复现和分析。

---

## ❓ 常见问题

### SDK 需要用户配置服务地址吗？

不需要。

SDK 默认连接九章光量子云平台服务，用户只需要配置 API Key 和量子计算机 ID。

### SDK 会在本地执行 GBS 物理采样吗？

不会。

SDK 是九章光量子云平台的 Python 客户端，主要负责任务提交、状态查询、结果获取和返回数据分析。

### API Key 应该写在哪里？

推荐写入环境变量，不建议直接写入 Notebook、脚本或代码仓库。

### 任务执行需要多长时间？

任务耗时取决于任务参数、平台资源和当前队列情况。对于长时间任务，建议使用 `run_gbs()` 的 `timeout` 和 `poll_interval` 参数控制等待行为。

## 📄 授权协议

Copyright © 2026 JiuZhang Quantum.

All rights reserved.
