Kaiwu SDK&云平台使用常见问题指南

Kaiwu SDK旨在帮助开发者在Python环境下直接构建可适用于相干光量子计算机的软件算法，并提供物理接口（目前是提供Ising矩阵）调用量子计算机物理真机。本指南汇总了目前Kaiwu SDK与云平台常见使用问题，帮助开发者顺利安装Kaiwu SDK，更好地解决在建模与求解过程中遇到的问题。

一、Kaiwu SDK安装

目前Kaiwu SDK已更新至1.2.0版本，仅支持Python3.10版本，不区分小版本。

● 安装文档（含视频）：https://kaiwu.qboson.com/plugin.php?id=knowledge&modac=docs&link=KaiwuSDK&name=%E5%AE%89%E8%A3%85%E6%95%99%E7%A8%8B

Mac有intel和m芯片系列，请尝试SDK的intel和m版本，但是不一定完全匹配，可能m芯片的Macbook需要intel版本的SDK

请检查当前项目路径是否已经添加到Path中

按照教程执行安装命令即可，会覆盖旧版本

二、Kaiwu SDK使用

2.1 模块指南

Kaiwu SDK包含十个模块：cim、classical、common、core、ising、license、preprocess、qubo、sampler、solver。具体用法请参考

文档：模块指南

2.2 license问题

1、请到相干光量子云平台重新生成申请：相干光量子云平台

2、代码中init和CIMoptimizer部分的id和code要同步修改

生成license需要连接国内网络，建议本地生成license，服务器下载license时候请检查服务器网络配置。

2.3 问题建模与编码

可以用kaiwu.common.hamiltonian(ising_matrix, c_list)进行计算。

QUBO 的目标函数一般表示为：

$$y=x^{T}Qx+offset$$

其中：

$x$是二进制变量（$0$或$1$）组成的向量，$Q$是对称权重矩阵。

$offset$是一个常数项，独立于变量$x$，通常用于调整目标函数的数值基准，但不会对优化的解产生直接影响。

2.4 数据处理

上传的矩阵格式不对，格式可以参考上传界面的“样例工程”文件。

矩阵精度问题，可以查询学习文档，其中QUBO和Ising矩阵都要保持在8精度范围：适配参数精度指南

mutate：动态范围是系数矩阵的最大差比最小非零差值，它和矩阵的精度正相关。取出某个系数，判断该系数向上向下调整多少时最优解是不变的，在这个范围内调整系数以减小动态范围。

调整范围的计算方式：$q_{ij}{x}_i{x}_j$，这一项对最终结果的贡献有$q_{i}j$和$0$两种可能，分别求出这两种情况下最终结果的上界和下界，就可以得知$q_{i}j$在什么范围调整之后不改变最优解。

QUBO变量满足${𝑥}^2=𝑥$，可以用矩阵的对角线元素表达一次项，而Ising模型${𝑥}^2=1$，所以不能这样表示。模型的常数项在优化过程中通常可忽略，但在计算总能量时需额外累加，常数项单独记录，在计算最终哈密顿量时加上即可。

三、求解器使用

关于模型的求解提供了两种方式，一种是通过云平台或SDK调用相干光量子计算机真机，一种是使用Kaiwu SDK中的经典求解器（一般为SA）求解。

• SDK调用相干光量子计算机：https://kaiwu-sdk-docs.qboson.com/en/latest/source/modules/kaiwu.cim.html

• SDK中的经典求解器：https://kaiwu-sdk-docs.qboson.com/en/latest/source/modules/kaiwu.classical.html

比特数超过限制，比如100配额机器不能提交550比特的任务，请修改数据或联系官方工作人员升级账号。

在调用init_solution之前需要调用set_matrix。

完整示例如下：

matrix = -np.array([[0., 1., 0., 1., 1.],

[1., 0., 0., 1., 1.],

[0., 0., 0., 1., 1.],

[1., 1., 1., 0., 1.],

[1., 1., 1., 1., 0.]])

worker = kw.classical.TabuSearchOptimizer(10, size_limit=1)

init_solution = np.array([1, 1, 1, -1, -1])

worker.set_matrix(matrix)

worker.init_solution(init_solution)

solutions = worker.solve()

可能是以下原因之一：

• 模块版本不匹配：某些模块的功能或类可能只存在于特定版本中，如果使用的是较旧版本，可能缺少 SimulatedCIMOptimizer；

• 模块安装不完整：安装过程中可能存在问题，导致模块内容不完整；

• 导入方式有误：可能 SimulatedCIMOptimizer 并不是直接存在于 kaiwu.cim 下，而是位于其他子模块中；

• 安装的 kaiwu 模块不完整或损坏；

• 运行环境的python路径可能有问题；

注：在最新版本的SDK中（1.0.3和1.2.0），SimulatedCIMOptimizer已被移除，推荐使用kaiwu.classical.SimulatedAnnealingOptimize，求解效果更好。遇到类似问题时可查询SDK文档(https://kaiwu-sdk-docs.qboson.com/en/latest/source/modules/index.html)确定所需功能所在的模块。

• 真机任务调用（CIMOptimizer）

使用 kaiwu.cim.CIMOptimizer 可将问题提交至相干光量子计算云平台。此类计算由后端统一调度，用户无需手动设置底层参数。

注：CIMOptimizer 不支持设置 pump、noise、laps、delta_time、normalization、iterations 等参数，这些参数仅用于早期 CIM模拟器。当前 SDK 中已废弃模拟器相关功能，用户只需设置问题矩阵并调用真机即可。

• 优化采样参数（一般适用于经典求解器结果的后处理）

在使用如 SimulatedAnnealingOptimizer、TabuSearchOptimizer 等经典求解器时，可能返回多个候选解。此时可通过 kaiwu.sampler 模块对结果进行采样排序或偏好选择。

例如，在使用kaiwu.sampler.optimal_sampler进行最优解采样时，可以通过调整bias和negtail_ff等参数来影响采样结果的排序和选择。

注：CIM真机计算返回的解是已经排好序的解。

• 建模参数（适用于QUBO/Ising目标函数设计）

在构建QUBO/Ising模型时，可根据问题需求设定权重、惩罚因子等，优化目标函数。

例如，在旅行商问题中，可设定类似 100 * ham_cycle + path_cost 的目标表达式，通过调节惩罚系数$100$来平衡硬约束与目标函数，从而影响解的可行性和优劣性。

CIM还没有相关的理论来说明求解时间越长求解效果越好。与其求解的原理相关，求解过程对应的是DOPO建立的物理过程，一旦当系统稳定后，就不会利用压缩态这个过程来求解，求解效果也不会有提升；当然如果系统差异或者一旦求解规模上升后，DOPO建立的时间变长后，适当增加求解的时间有助于求到比较好的解。

推荐论文：https://journals.aps.org/pra/abstract/10.1103/PhysRevA.88.06385

初始化方法实际只需要一个位置参数optimizer，用法是创建一个适合问题的QuboModel，进而初始化一个SimpleSolver，传入一个优化器（如SimulatedAnnealingOptimizer）作为参数，例如：

optimizer = kw.classical.SimulatedAnnealingOptimizer(alpha=

0.999, iterations_per_t=50

)

solver = kw.solver.SimpleSolver(optimizer)

以上是一些在使用Kaiwu SDK和云平台时的常见问题，如果有更多问题，欢迎查阅官方文档、学习地图或者在开物量子开发者社区进行讨论！