SDK使用教程

1.关于 Plectrum（拨片）

想象一位音乐家手持拨片，优雅地演奏着旋律。每个音符如同珠子般落入玉盘——那玉盘便是伊辛云平台。

Plectrum（拨片） 是一个统一的 Python SDK，帮助您轻松地将优化问题提交到云端或本地求解器。正如拨片帮助音乐家创造美妙的音乐，Plectrum 帮助您轻松解决复杂的优化问题。

2.特性

统一接口：云端和本地求解器使用同一套 API

灵活选择：运行时可自由切换求解器

多种任务类型：QUBO、ISING、通用任务和模板任务

云端支付选项：云端任务支持选择是否使用账户额度和优惠券抵扣费用

3.安装

4.快速开始

5.求解器

CloudSolver

将任务提交至伊辛云平台，并轮询获取结果。

参数：

参数	类型	默认值	说明
`api_key`	`str`	`$PLECTRUM_API_KEY`	API 密钥（必填）
`host`	`str`	`https://api.isingq.com`	云端 API 地址
`computer_type`	`int`	`OEPO_ISING_1601`	机器类型 ID
`gear`	`int`	`GEAR_PRECISE`	档位模式 (0/1/2)
`poll_interval`	`int`	`2`	轮询间隔（秒）
`timeout`	`int`	`300`	最大等待时间（秒）

LocalSolver

在本地运行模拟退火算法，无需网络。

参数：

参数	类型	默认值	说明
`gear`	`int`	`GEAR_PRECISE`	档位模式 (0/1/2)
`algorithm`	`str`	`"sa"`	算法（`"sa"` = 模拟退火）

LocalOepoSolver

通过 HTTP 将任务提交至本地的光电伊辛机。

参数：

参数	类型	默认值	说明
`host`	`str`	`http://192.168.137.100:5001`	OEPO 设备地址
`api_path`	`str`	`/api/v1/job/`	API 端点路径
`computer_type`	`int`	`None`	机器类型 ID
`gear`	`int`	`None`	档位模式 (0/1/2)

6.任务

QuboTask

用于 QUBO（二次无约束二进制优化）问题 — 二进制变量 (0/1)。

MinimalIsingEnergyTask

用于 ISING 问题 — 自旋变量 (-1/+1)，最小化伊辛能量。

GeneralTask

优化任务的基类。建议使用 QuboTask 或 MinimalIsingEnergyTask 替代。

云端支付选项

云端支付选项可用于 GeneralTask、QuboTask 和 MinimalIsingEnergyTask。

use_credit：是否使用账户额度/余额抵扣，默认 False

use_coupon：是否使用优惠券抵扣，默认 False

启用后，SDK 会将 useCredit 和 useCoupon 发送给云端 API，由云端服务处理费用抵扣。

不需要抵扣时保持默认值即可：

TemplateTask

基于模板的任务，用于云平台预定义的问题类型。

7.矩阵 (Matrix)

Matrix 类封装 numpy 数组并处理 CSV 转换。创建时自动验证输入。

空数据、非二维数组、NaN/Inf 值或非数字输入会抛出 MatrixError。

8.结果 (Result)

所有求解器通过 task.solve() 返回统一的结果格式：

9.档位模式 (Gear)

Gear 模式控制求解速度和质量的平衡。

10.错误处理

所有异常通过 __cause__ 链接原始原因

PlectrumError                 ← 基类，可统一捕获
├── AuthenticationError       ← API 密钥缺失或无效
├── ClientError               ← HTTP 或求解器通信失败
│   ├── TimeoutError          ← 请求或轮询超时
│   └── ConnectionError       ← 网络连接失败
├── TaskError                 ← 任务验证或执行失败
├── MatrixError               ← 矩阵数据验证失败
└── ValidationError           ← 通用输入验证失败

示例：

11.配置

API Key

可以通过两种方式配置：

环境变量（推荐）：

直接传入参数：

注意： 如果未找到 API Key，CloudSolver 会在初始化时抛出 AuthenticationError。

1.关于 Plectrum（拨片）#

2.特性#

3.安装#

4.快速开始#

5.求解器#

CloudSolver#

LocalSolver#

LocalOepoSolver#

6.任务#

QuboTask#

MinimalIsingEnergyTask#

GeneralTask#

云端支付选项#

TemplateTask#

7.矩阵 (Matrix)#

8.结果 (Result)#

9.档位模式 (Gear)#

10.错误处理#

11.配置#

API Key#

问题类型#

12.开发#

1.关于 Plectrum（拨片）

2.特性

3.安装

4.快速开始

5.求解器

CloudSolver

LocalSolver

LocalOepoSolver

6.任务

QuboTask

MinimalIsingEnergyTask

GeneralTask

云端支付选项

TemplateTask

7.矩阵 (Matrix)

8.结果 (Result)

9.档位模式 (Gear)

10.错误处理

11.配置

API Key

问题类型

12.开发