jiuzhang-sdk 0.1.0a18

九章光量子真机云接入软件包（jiuzhang SDK）

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:

pip install --pre jiuzhang-sdk

Install a specific version:

pip install jiuzhang-sdk==0.1.0a17

Local development:

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:

$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:

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 提交任务时与云平台参数保持一致，核心请求字段为：

{
    "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.

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
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:

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:

doc/cloud-platform/sdk_full_usage.ipynb

Local Cloud Mock / 本地云平台 Mock

Start the mock:

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

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

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 / 开发测试

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.