qubitclient 0.3.5

qubit analysis client

QubitClient: 面向量子系统的AI客户端

中文文档 | English Doc

介绍

QubitClient 是一个用于与Qubit服务进行交互的Python客户端库。它提供了丰富的API接口，支持多种量子计算相关的任务，包括曲线分割、参数拟合等功能。

功能特性

• 二维数据分析功能: 二维能谱分析、功率偏移曲线分析等
• 多种任务支持: 包括S21峰值检测、最优π脉冲、Rabi振荡、T1/T2拟合等多种量子计算任务
• 灵活的数据输入: 支持文件路径、NumPy数组、字典等多种数据格式作为输入
• 批量处理: 支持同时处理多个数据文件
• 易于集成: 提供简洁明了的API接口，方便快速集成到现有项目中
• MCP协议支持: 基于MCP协议的实时量子测量任务控制

安装

pip install qubitclient

如果需要使用绘图等功能

pip install qubitclient[full]

或者从源码安装：

cd QubitClient
pip install -e .

快速开始

配置

1. 拷贝配置文件模板：

cp config.py.example config.py

2. 修改 config.py 文件中的服务器地址和API密钥：

API_URL = "http://your-server-address:port"
API_KEY = "your-api-key"

使用示例

NNScope功能（曲线分割）

from qubitclient import QubitNNScopeClient, NNTaskName, CurveType
import numpy as np

# 初始化客户端
client = QubitNNScopeClient(url="http://your-server-address:port", api_key="your-api-key")

# 方式1: 直接使用文件路径
file_path_list = ["data/file1.npz", "data/file2.npz"]
response = client.request(
    file_list=file_path_list,
    task_type=NNTaskName.SPECTRUM2D,
    curve_type=CurveType.COSINE
)

# 方式2: 使用NumPy数组字典
data_ndarray = np.load(file_path, allow_pickle=True)
dict_list = [data_ndarray]

response = client.request(
    file_list=dict_list,
    task_type=NNTaskName.SPECTRUM2D,
    curve_type=CurveType.POLY
)

# 获取结果
results = client.get_result(response=response)

Scope功能

from qubitclient import QubitScopeClient, TaskName
import numpy as np

# 初始化客户端
client = QubitScopeClient(url="http://your-server-address:port", api_key="your-api-key")

# 准备数据
dict_list = [{
    "some_key": np.ndarray(...)
}]

# 发起请求
response = client.request(
    file_list=dict_list,
    task_type=TaskName.OPTPIPULSE  # 可选任务见下方任务类型列表
)

# 获取结果
results = client.get_result(response=response)

Ctrl功能（MCP协议测量任务）

from qubitclient.ctrl import QubitCtrlClient, CtrlTaskName

# 初始化客户端
client = QubitCtrlClient()

# 执行S21腔频测量实验
result = client.run(
    task_type=CtrlTaskName.S21,
    qubits_use=["Q0", "Q1"],
    frequency_start=-40e6,
    frequency_end=40e6,
    frequency_sample_num=101
)

print(result)

支持的任务类型

NNScope任务

• NNTaskName.SPECTRUM2D: 二维频谱数据曲线分割，详见 SPECTRUM2D详细文档
• NNTaskName.POWERSHIFT: 功率偏移曲线分割，详见 POWERSHIFT详细文档
• NNTaskName.S21VFLUX: S21 vs Flux参数曲线分割，详见 S21VFLUX详细文档
• NNTaskName.SPECTRUM: 频谱分析，详见 SPECTRUM详细文档

Scope任务

• TaskName.S21PEAK: S21参数峰值检测，详见 S21PEAK详细文档
• TaskName.OPTPIPULSE: 最优π脉冲计算，详见 OPTPIPULSE详细文档
• TaskName.RABICOS: Rabi振荡余弦第一峰检测，详见 RABICOS详细文档
• TaskName.RAMSEY: RAMSY衰减震荡余弦拟合，详见 RAMSEY详细文档
• TaskName.S21VFLUX: S21 vs Flux分析，详见 S21VFLUX详细文档
• TaskName.SINGLESHOT: 单次测量分析，详见 SINGLESHOT详细文档
• TaskName.SPECTRUM: 频谱分析，详见 SPECTRUM详细文档
• TaskName.T1FIT: T1时间拟合，详见 T1FIT详细文档
• TaskName.T2FIT: T2时间拟合，详见 T2FIT详细文档
• TaskName.POWERSHIFT: 分析功率偏移曲线，详见 POWERSHIFT详细文档
• TaskName.SPECTRUM2D: 二维频谱数据曲线分割，详见 SPECTRUM2D详细文档
• TaskName.DRAG: DRAG免交叉点，详见 DRAG详细文档

Ctrl任务

• CtrlTaskName.S21: S21腔频测量实验，测量指定量子比特在频率范围内的S21响应，详见 S21详细文档
• CtrlTaskName.DRAG: DRAG免交叉点测量，优化量子比特的DRAG参数，详见 DRAG详细文档
• CtrlTaskName.DELTA: 频率偏移校准测量，确定量子比特的最佳工作频率偏移量，详见 DELTA详细文档
• CtrlTaskName.OPT_PIPULSE: 最优π脉冲测量，寻找最佳的π脉冲幅度，详见 OPT_PIPULSE详细文档
• CtrlTaskName.POWERSHIFT: 功率偏移曲线测量，分析不同功率下的量子比特响应，详见 POWERSHIFT详细文档
• CtrlTaskName.RABI: Rabi振荡测量，观察量子比特在驱动场下的振荡行为，详见 RABI详细文档
• CtrlTaskName.RAMSEY: Ramsey干涉测量，测量量子比特的退相干时间，详见 RAMSEY详细文档
• CtrlTaskName.S21VSFLUX: S21 vs Flux测量，分析磁通量对量子比特频率的影响，详见 S21VSFLUX详细文档
• CtrlTaskName.SINGLESHOT: 单次测量分析，评估量子比特的读出保真度，详见 SINGLESHOT详细文档
• CtrlTaskName.SPECTRUM: 频谱分析测量，扫描量子比特的能级结构，详见 SPECTRUM详细文档
• CtrlTaskName.SPECTRUM_2D: 二维频谱测量，同时扫描频率和偏置参数，详见 SPECTRUM_2D详细文档
• CtrlTaskName.T1: T1弛豫时间测量，测量量子比特的能量弛豫时间，详见 T1详细文档

数据格式说明

输入格式

依据功能不同，输入格式有所不同

输出格式

依据功能任务不同，输出格式有所不同

运行测试示例

测试示例包含在 tests 目录下，可依据文件名运行对应的测试代码

# 运行NNScope测试
python tests/test_nnscope.py

# 运行Scope测试
python tests/test_scope.py

# 运行Ctrl测试
python tests/test_ctrl_mcp.py

格式转换及其他工具集成

参考 resources 目录下不同工具对应的代码

更新日志

近期更新:

• 增加Ctrl功能包: 基于MCP协议的测量任务(20260206)
• 增加DRAG分析功能: 增加DRAG任务数据分析(20260205)
• 增加scope功能包: 增加多种任务功能(20251022)
• 增加曲线类型: 增加余弦类型曲线拟合(20250606)
• 构建基础项目: 基础功能与结构构建

许可证

本项目采用GPL-3.0许可证，详见LICENSE文件。