jiuzhang-sdk 0.1.0a20

九章光量子真机云接入软件包（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, and parse returned results.

Installation / 安装

Current pre-release:

pip install --pre jiuzhang-sdk

Install a specific version:

pip install jiuzhang-sdk==0.1.0a20

Quickstart / 快速开始

Set your API Key before running:

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

PowerShell:

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

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.

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

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

ruff format src tests
ruff check src tests
mypy src
pytest

License / 授权

Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.