jiuzhang-sdk 0.1.0a11

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

⚛️ 九章光量子云平台 Python SDK

🌐 English | 简体中文

jiuzhang 是面向九章光量子云平台的 Python SDK。

它提供简洁、类型化、适合脚本和 Notebook 使用的接口，帮助用户提交高斯玻色采样（Gaussian Boson Sampling, GBS）任务、查询任务状态、获取实验结果，并对返回数据进行基础分析。

📦 安装

使用 pip 安装：

pip install jiuzhang-sdk

安装预发布版本：

pip install --pre jiuzhang-sdk

安装指定版本：

pip install jiuzhang-sdk==0.1.0a11

🚀 快速开始

请先准备平台提供的：

• 🔑 API Key
• 🖥️ 量子计算机 ID

推荐通过环境变量配置密钥和默认量子计算机 ID，避免在代码中明文写入敏感信息。

🍎 macOS / Linux

export JIUZHANG_API_KEY="your_api_key_here"
export JIUZHANG_DEFAULT_MACHINE_ID="your_machine_id_here"

🪟 Windows PowerShell

$env:JIUZHANG_API_KEY="your_api_key_here"
$env:JIUZHANG_DEFAULT_MACHINE_ID="your_machine_id_here"

提交一个最小 GBS 任务：

import os

from jiuzhang import CloudClient, GBSParams

client = CloudClient.from_env()

params = GBSParams(
    machine_id=int(os.environ["JIUZHANG_DEFAULT_MACHINE_ID"]),
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
    task_name="GBS quickstart demo",
)

result = client.run_gbs(params)

print("Task ID:", result.task_id)
print("Status:", result.status_name)
print("Experimental distribution:", result.experimental_distribution)

client.close()

🧩 核心概念

☁️ CloudClient

CloudClient 是 SDK 的主要入口，用于连接九章光量子云平台。

它负责：

• 📝 创建请求
• 🚀 提交任务
• 🔄 查询任务状态
• 📥 获取任务结果
• 🔍 解析平台返回数据

推荐使用环境变量创建客户端：

from jiuzhang import CloudClient

client = CloudClient.from_env()

也可以手动传入 API Key：

from jiuzhang import CloudClient

client = CloudClient(api_key="your_api_key_here")

⚛️ GBSParams

GBSParams 用于定义高斯玻色采样任务参数。

from jiuzhang import GBSParams

params = GBSParams(
    machine_id=123456789,
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
    task_name="my-gbs-task",
)

常用参数：

参数	类型	说明
machine_id	int	目标量子计算机 ID
mt	int	时间模式数
pump_energy_nj	float	泵浦能量，单位 nJ
squeezing_param	float | None	压缩参数
shots	int | None	采样次数
task_name	str	任务名称

📊 GBSResult

GBSResult 是任务执行结果的解析对象。

result = client.run_gbs(params)

print(result.task_id)
print(result.status_name)
print(result.experimental_distribution)

常用字段：

字段	说明
task_id	平台任务 ID
status_name	标准化任务状态
machine_id	量子计算机 ID
experimental_distribution	实验分布数据
ground_truth_distribution	参考分布数据
result_map_points	结果可视化数据点
download_url	结果文件下载地址
raw	原始响应数据

💡 使用示例

🔮 估算任务

estimate = client.estimate_gbs(params)

print(estimate)

🚀 提交任务

task = client.submit_gbs(params)

print(task)

📥 查询结果

result = client.get_result("your_task_id_here")

print(result)

⏳ 提交并等待结果

result = client.run_gbs(
    params,
    poll_interval=1.0,
    timeout=60.0,
)

print(result.status_name)

📒 Jupyter Notebook 集成

SDK 提供适合 Notebook 场景的辅助方法。

from jiuzhang import GBSParams
from jiuzhang.jupyter import (
    get_notebook_client,
    show_environment,
    display_gbs_result,
)

show_environment()

client = get_notebook_client()

params = GBSParams(
    machine_id=123456789,
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
)

result = client.run_gbs(params)

display_gbs_result(result)

show_environment() 会显示当前运行环境配置，并对 API Key 做脱敏处理。

✨ 功能特性

🔄 任务生命周期管理

SDK 封装了云端任务的完整生命周期：

• 🏗️ 构造任务参数
• ✅ 校验任务参数
• 🚀 提交 GBS 任务
• 🔄 轮询任务状态
• 📥 获取任务结果
• 🔍 解析返回数据

🏷️ 类型化参数

SDK 使用 GBSParams 对任务输入进行封装，使参数结构更加清晰，便于在脚本、服务端程序和 Notebook 中复用。

params = GBSParams(
    machine_id=123456789,
    mt=64,
    pump_energy_nj=2.0,
    squeezing_param=0.35,
)

📈 结果分析

jiuzhang.gbs.analysis 模块提供常用的采样结果分析工具。

from jiuzhang.gbs.analysis import (
    photon_count_histogram,
    click_count_histogram,
    collision_rate,
    total_variation_distance,
)

photon_hist = photon_count_histogram(samples)
click_hist = click_count_histogram(samples)
collision = collision_rate(samples)

常用方法：

方法	说明
photon_count(samples)	计算每个样本的总光子数
photon_count_histogram(samples)	生成光子数直方图
click_count(samples)	计算每个样本的 click 数
click_count_histogram(samples)	生成 click 数直方图
mode_occupancy(samples)	统计各模式占用情况
collision_rate(samples)	计算 collision 样本比例
top_k_patterns(samples, k=20)	获取高频采样模式
total_variation_distance(p, q)	计算总变差距离
hellinger_distance(p, q)	计算 Hellinger 距离
js_divergence(p, q)	计算 Jensen-Shannon 散度

📒 Notebook 友好

SDK 支持在 Jupyter Notebook 中快速创建客户端、检查运行环境和展示 GBS 任务结果，适合教学、实验演示和数据分析场景。

🌱 环境变量

推荐使用环境变量管理平台连接信息：

环境变量	说明
JIUZHANG_API_KEY	平台 API Key
JIUZHANG_DEFAULT_MACHINE_ID	默认量子计算机 ID

示例：

from jiuzhang import CloudClient

client = CloudClient.from_env()

🏗️ 架构

SDK 采用轻量级客户端架构：

层级	作用	主要组件
用户层	Python 脚本、Notebook、业务程序	用户代码
SDK 层	任务参数、任务提交、结果解析	CloudClient, GBSParams, GBSResult
通信层	请求构造、认证、HTTP 通信	TokenManager, HTTP Client
云平台层	远程量子计算服务	九章光量子云平台

SDK 作为云平台客户端使用，不要求用户管理底层量子硬件、服务调度或任务执行环境。

🧱 组件说明

• ☁️ CloudClient：云平台客户端，负责任务提交、查询和结果获取
• ⚛️ GBSParams：GBS 任务参数对象
• 📊 GBSResult：GBS 任务结果对象
• 🔐 TokenManager：API Key 管理与脱敏工具
• 📈 jiuzhang.gbs.analysis：采样结果分析工具
• 📒 jiuzhang.jupyter：Notebook 集成工具

⚠️ 错误处理

SDK 会针对请求失败、参数错误、认证失败、任务超时等情况抛出 Python 异常。

from jiuzhang import CloudClient, GBSParams
from jiuzhang.exceptions import JiuZhangError

try:
    client = CloudClient.from_env()
    result = client.run_gbs(params)
except JiuZhangError as exc:
    print("JiuZhang SDK error:", exc)

✅ 最佳实践

• 🔑 使用环境变量保存 API Key。
• 🚫 不要在 Notebook 或源代码中明文写入真实密钥。
• 🌱 在共享环境中优先使用 CloudClient.from_env()。
• ⏳ 长时间任务建议设置明确的 timeout。
• 🔒 使用完成后调用 client.close() 关闭连接。
• 🧾 保存任务参数和结果，便于后续复现和分析。

---

❓ 常见问题

SDK 需要用户配置服务地址吗？

不需要。

SDK 默认连接九章光量子云平台服务，用户只需要配置 API Key 和量子计算机 ID。

SDK 会在本地执行 GBS 物理采样吗？

不会。

SDK 是九章光量子云平台的 Python 客户端，主要负责任务提交、状态查询、结果获取和返回数据分析。

API Key 应该写在哪里？

推荐写入环境变量，不建议直接写入 Notebook、脚本或代码仓库。

任务执行需要多长时间？

任务耗时取决于任务参数、平台资源和当前队列情况。对于长时间任务，建议使用 run_gbs() 的 timeout 和 poll_interval 参数控制等待行为。

📄 授权协议

Copyright © 2026 JiuZhang Quantum.

All rights reserved.