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

一、Kaiwu SDK安装

安装教程

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

● 安装文档（含视频）：Kaiwu SDK安装教程

Mac架构错误

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

SDK导入错误（ModuleNotFoundError）

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

安装最新版本SDK

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

二、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，服务器下载license时候请检查服务器网络配置

2.3 问题建模与编码

自行输入自旋矩阵和Ising系数矩阵如何计算哈密顿量的函数？

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

qubo中的offset是什么意思，在计算目标函数时会有影响吗?

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

y=x^TQx+offset

其中：

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

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

2.4 数据处理

上传QUBO矩阵时显示校验失败——“非标准QUBO矩阵文件”

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

上传QUBO矩阵时显示校验失败——“CSV数据文件的精度过高”

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

动态空间压缩函数kw.preprocess.perform_precision_adaption_mutate的内嵌转化过程是怎样的？转化后再根据极值放大并取整是否可行？

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

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

QUBO matrix 对角线元素转化的Ising耦合矩阵对角线元素为何一定要为零？

QUBO变量满足𝑥²=𝑥，可以用矩阵的对角线元素表达一次项，而Ising模型𝑥²=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

ValueError: Verification failed for task task_1: CSV数据文件的行数超过限制

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

给kaiwu.classical.TabuSearchOptimizer求解器用init_solution(solution)方法给一个初始解向量时报错

在调用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()

AttributeError: module 'kaiwu.cim' has no attribute 'SimulatedCIMOptimizer'

可能是以下原因之一：

● 模块版本不匹配：某些模块的功能或类可能只存在于特定版本中，如果使用的是较旧版本，可能缺少 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的solution quality有没有theoretical bound？比如对于量子退火而言，如果退火时间最够长，是趋近于最优解的。对于CIM来说，是否有相似的原理？

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

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

SimpleSolver 的初始化方法需要的位置参数

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

optimizer = kw.classical.SimulatedAnnealingOptimizer(alpha=



0.999, iterations_per_t=50



)



solver = kw.solver.SimpleSolver(optimizer) 

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

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

一、Kaiwu SDK安装

安装教程

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

● 安装文档（含视频）：Kaiwu SDK安装教程

Mac架构错误

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

SDK导入错误（ModuleNotFoundError）

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

安装最新版本SDK

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

二、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，服务器下载license时候请检查服务器网络配置

2.3 问题建模与编码

自行输入自旋矩阵和Ising系数矩阵如何计算哈密顿量的函数？

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

qubo中的offset是什么意思，在计算目标函数时会有影响吗?

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

y=x^TQx+offset

其中：

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

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

2.4 数据处理

上传QUBO矩阵时显示校验失败——“非标准QUBO矩阵文件”

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

上传QUBO矩阵时显示校验失败——“CSV数据文件的精度过高”

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

动态空间压缩函数kw.preprocess.perform_precision_adaption_mutate的内嵌转化过程是怎样的？转化后再根据极值放大并取整是否可行？

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

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

QUBO matrix 对角线元素转化的Ising耦合矩阵对角线元素为何一定要为零？

QUBO变量满足𝑥²=𝑥，可以用矩阵的对角线元素表达一次项，而Ising模型𝑥²=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

ValueError: Verification failed for task task_1: CSV数据文件的行数超过限制

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

给kaiwu.classical.TabuSearchOptimizer求解器用init_solution(solution)方法给一个初始解向量时报错

在调用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()

AttributeError: module 'kaiwu.cim' has no attribute 'SimulatedCIMOptimizer'

可能是以下原因之一：

● 模块版本不匹配：某些模块的功能或类可能只存在于特定版本中，如果使用的是较旧版本，可能缺少 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的solution quality有没有theoretical bound？比如对于量子退火而言，如果退火时间最够长，是趋近于最优解的。对于CIM来说，是否有相似的原理？

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

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

SimpleSolver 的初始化方法需要的位置参数

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

optimizer = kw.classical.SimulatedAnnealingOptimizer(alpha=



0.999, iterations_per_t=50



)



solver = kw.solver.SimpleSolver(optimizer) 

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