Metadata-Version: 2.4
Name: jiuzhang-sdk
Version: 0.1.0a18
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, parse returned results, and run
lightweight local analysis.

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

## Installation / 安装

Current pre-release:

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

Install a specific version:

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

Local development:

```powershell
cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk\code
pip install -e ".[dev,jupyter]"
```

## Quickstart / 快速开始

Prepare these cloud-platform values:

| Value / 参数 | Description / 说明 |
| --- | --- |
| `JIUZHANG_API_KEY` | Cloud API Key / 云平台 API Key |
| `JIUZHANG_BASE_URL` | API root, normally ending with `/api/v1` / API 根地址，通常包含 `/api/v1` |
| `project_id` | Project `experiment_code`; required when submitting tasks / 平台项目 `experiment_code`，提交任务必填 |
| `quantum_computer_id` | Cloud quantum computer id, for example `PH_QC_04` / 云平台量子计算机 ID |

PowerShell local mock example:

```powershell
$env:JIUZHANG_API_KEY="PQ-3f2c2a3b0f7a4a2ab1cdb0b7d2f1a9c4"
$env:JIUZHANG_BASE_URL="http://127.0.0.1:18081/api/v1"
$env:JIUZHANG_PROJECT_ID="EXP-local-demo"
$env:JIUZHANG_QUANTUM_COMPUTER_ID="PH_QC_04"
```

Python:

```python
from jiuzhang import CloudClient, GBSParams

client = CloudClient.from_env()

params = GBSParams(
    project_id="EXP-local-demo",
    quantum_computer_id="PH_QC_04",
    mt=300,
    pump_energy_nj=4.6,
    task_name="jupter在线测试001",
)

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

client.close()
```

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

The SDK uses these cloud endpoints. `base_url` may already include `/api/v1`.

| 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 `X-Jiuzhang-API-Key`. HTTP status may be 200 even when the
business request failed; the SDK checks response `code` and raises SDK
exceptions for `code != 0`.

SDK 提交任务时与云平台参数保持一致，核心请求字段为：

```python
{
    "project_id": "EXP-39dfbfdcab444d32",
    "task_name": "jupter在线测试001",
    "quantum_computer_id": "PH_QC_04",
    "mt_value": 300,
    "pump_energy_nj": 4.6,
}
```

SDK 请求和返回结果都使用 `quantum_computer_id`，不再使用 `device_id` 或 `machine_id` 作为云平台字段。

## 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="jupter在线测试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 / 原始响应 |

## 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)
```

Complete SDK usage notebook:

```text
doc/cloud-platform/sdk_full_usage.ipynb
```

## Local Cloud Mock / 本地云平台 Mock

Start the mock:

```powershell
python local_test/mock_cloud_platform/mock_cloud_platform.py --port 18081 --mode standalone
```

The mock accepts both plain paths and `/api/v1` paths:

```text
POST http://127.0.0.1:18081/api/v1/estimate
POST http://127.0.0.1:18081/api/v1/tasks/submit
GET  http://127.0.0.1:18081/api/v1/tasks/{task_id}
```

## Development / 开发测试

```powershell
cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk\code
ruff format src tests
ruff check src tests
mypy src
pytest
```

## License / 授权

Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.
