Metadata-Version: 2.4
Name: jiuzhang-sdk
Version: 0.1.0a19
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.

SDK 只调用九章云平台 API，不直接调用天衍平台，也不在本地执行真实 GBS 物理仿真。

## Installation / 安装

Current pre-release:

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

Install a specific version:

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

## Quickstart / 快速开始

Set your API Key before running:

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

PowerShell:

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

Python:

```python
from jiuzhang import CloudClient, GBSParams

client = CloudClient.from_env()

params = GBSParams(
    project_id="EXP-39dfbfdcab444d32",
    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.
