Metadata-Version: 2.4
Name: jiuzhang-sdk
Version: 0.1.0a20
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.29,>=0.27
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: mypy>=1.11; 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

# jiuzhang SDK - 九章光量子云平台 Python SDK

`jiuzhang-sdk` is the Python SDK for the JiuZhang photonic quantum cloud
platform. It helps Python scripts and Jupyter notebooks submit Gaussian Boson
Sampling (GBS) tasks, poll task status, and parse returned results.

## Installation / 安装

Current pre-release:

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

Install a specific version:

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

## Quickstart / 快速开始

Set your API Key before running:

```bash
export JIUZHANG_API_KEY="your-api-key-here"
export JIUZHANG_PROJECT_ID="EXP-39dfbfdcab444d32"
```

PowerShell:

```powershell
$env:JIUZHANG_API_KEY="your-api-key-here"
$env:JIUZHANG_PROJECT_ID="EXP-39dfbfdcab444d32"
```

Python:

```python
import os
from jiuzhang import CloudClient, GBSParams

# 使用环境中的 API Key 初始化客户端，接入指定的服务根地址
client = CloudClient(
    base_url="https://api.jiuzhang.com/api/v1",
    api_key=os.environ["JIUZHANG_API_KEY"],
)

# 构造实验参数，项目 ID 从环境变量读取，其余参数直接写入
params = GBSParams(
    project_id=os.environ["JIUZHANG_PROJECT_ID"],
    quantum_computer_id="PH_QC_04",
    mt=300,
    pump_energy_nj=4.6,
    task_name="GBS experiment 001",
)

result = client.run_gbs(params)
print(result.task_id)
print(result.status_name)
print(result.quantum_computer_id)

client.close()
```

## GBSParams / GBS 参数

`GBSParams` is the typed task configuration object.

```python
from jiuzhang import GBSParams

params = GBSParams(
    project_id="EXP-39dfbfdcab444d32",
    quantum_computer_id="PH_QC_04",
    mt=300,
    pump_energy_nj=4.6,
    task_name="GBS experiment 001",
)
```

| Field / 字段 | Type / 类型 | Required / 必填 | Description / 说明 |
| --- | --- | --- | --- |
| `project_id` | `str` | Yes | Project `experiment_code` / 平台项目 `experiment_code` |
| `quantum_computer_id` | `str` | Yes | Cloud quantum computer id / 云平台量子计算机 ID |
| `mt` | `int` | Yes | Time-bin count, `1 <= mt <= 500` / 泵浦脉冲时序数 |
| `pump_energy_nj` | `float` | Yes | Pump energy in nJ / 泵浦能量 |
| `squeezing_param` | `float | None` | No | Squeezing parameter / 压缩参数 |
| `task_name` | `str` | No | Task display name / 任务展示名 |

`params.to_cloud_payload()` emits `project_id`, `quantum_computer_id`, `task_name`,
`mt_value`, `pump_energy_nj`, and optional task fields.

## GBSResult / GBS 结果

`GBSResult` parses the JiuZhang task wrapper and result fields.

| Property / 属性 | Description / 说明 |
| --- | --- |
| `task_id` | JiuZhang task id / 九章任务 ID |
| `status_name` | Normalized status / 标准化状态 |
| `project_id` | Project id / 项目 ID |
| `quantum_computer_id` | Cloud quantum computer id / 云平台量子计算机 ID |
| `experimental_distribution` | Experimental curve / 实验分布曲线 |
| `ground_truth_distribution` | Ground-truth curve / 参考分布曲线 |
| `result_map_points` | All visualization curves / 全部分布验证曲线 |
| `raw` | Original response / 原始响应 |

## Cloud API Contract / 云平台接口约定

| SDK method / SDK 方法 | HTTP endpoint / HTTP 接口 |
| --- | --- |
| `estimate_runtime(...)` / `estimate_gbs(params)` | `POST /estimate` |
| `submit_task(...)` / `submit_gbs(params)` | `POST /tasks/submit` |
| `get_result(task_id)` | `GET /tasks/{task_id}` |
| `run_experiment(...)` / `run_gbs(params)` | estimate → submit → poll → parse |

Authentication uses the `X-Jiuzhang-API-Key` header. The SDK checks the
response `code` field and raises SDK exceptions for `code != 0`.

SDK 请求和返回结果都使用 `quantum_computer_id`，不再使用 `device_id` 或 `machine_id`。

## Jupyter / Notebook

Notebook helpers avoid printing the full API Key:

```python
from jiuzhang.jupyter import display_gbs_result, get_notebook_client, show_environment

show_environment()
client = get_notebook_client()
result = client.run_gbs(params)
display_gbs_result(result)
```

## Development / 开发测试

```bash
ruff format src tests
ruff check src tests
mypy src
pytest
```

## License / 授权

Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.
