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

本指南汇总了目前Kaiwu SDK与云平台常见使用问题，帮助开发者顺利安装Kaiwu SDK，更好地解决在建模与求解过程中遇到的问题。

一、Kaiwu SDK安装

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

● 安装文档（含视频）：点击链接

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

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

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

1.3.1版本升级到1.4.0时，建议先卸载旧版本再重新安装，避免旧版本文件残留或命名空间包切换导致导入异常。1.4.0的pypi包名统一为kaiwu，安装时会同时依赖kaiwu-community提供core、common等基础模块。

参考指令如下：

pip uninstall kaiwu kaiwu-community

然后重新安装：

pip install kaiwu

安装完成后如仍出现ModuleNotFoundError，可先检查当前环境中是否同时存在kaiwu和kaiwu-community：

pip show kaiwu kaiwu-community

如果使用的是Jupyter或IDE，请确认内核/解释器与安装SDK的Python环境一致。

如果确认kaiwu和kaiwu-community两个包都已安装，但仍然出现ModuleNotFoundError，可能是旧版本残留的kaiwu命名空间目录影响了导入。可先查看当前环境中kaiwu命名空间路径：

python -c "import kaiwu; print(list(kaiwu.__path__))"

记录输出中的kaiwu目录后，先卸载相关包：

pip uninstall kaiwu kaiwu-community

如果卸载后上述路径下仍残留kaiwu文件夹，请删除该Python环境site-packages中的残留kaiwu目录，再重新执行：

pip install kaiwu

注意只删除当前Python环境下site-packages中的残留kaiwu目录，不要删除项目源码目录中的kaiwu文件夹。

二、Kaiwu SDK使用

2.1 模块指南

Kaiwu SDK包含九个模块：cim、classical、common、core、hobo、hybrid、license、preprocess、sampler，其中 core、common 模块已开源在 kaiwu-community 具体用法请参考文档：模块指南

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_{ij}$和$0$两种可能，分别求出这两种情况下最终结果的上界和下界，就可以得知$q_{ij}$在什么范围调整之后不改变最优解。

在1.4.0中，实际使用时更推荐优先使用kw.preprocess.PrecisionReducer作为降精度入口。它可以包装一个基础求解器，例如SimulatedAnnealingOptimizer或CIMOptimizer，在求解前自动进行精度检查、必要的截断缩放和变量拆分，再将求解结果恢复到原变量空间。perform_precision_adaption_mutate更适合作为单独的启发式动态范围压缩工具使用，不是PrecisionReducer当前默认调用的主流程。

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

三、求解器使用

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

● SDK调用量子计算机

● SDK中的经典求解器

比特数超过限制，比如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.3.1和1.4.0），SimulatedCIMOptimizer已被移除，推荐使用kaiwu.classical.SimulatedAnnealingOptimizer，求解效果更好，遇到类似问题时可查询SDK文档确定所需功能所在的模块。

● 真机任务调用（CIMOptimizer）

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

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

● 优化采样参数（一般适用于经典求解器或采样器）

在使用如 SimulatedAnnealingOptimizer、TabuSearchOptimizer 等经典求解器时，可以通过size_limit等参数控制返回候选解数量。1.4.0中kaiwu.sampler模块公开的采样器接口为SimulatedAnnealingSampler，可用于直接对Ising矩阵或QUBO模型进行采样求解。

例如：

sampler = kw.sampler.SimulatedAnnealingSampler(
    initial_temperature=100,
    alpha=0.99,
    cutoff_temperature=0.001,
    iterations_per_t=10,
    size_limit=100,
)
solutions = sampler.solve(ising_matrix)

如果需要影响采样过程，可调整initial_temperature、alpha、cutoff_temperature、iterations_per_t、size_limit、rand_seed等参数。

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

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

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

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

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

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

1.4.0中不再提供kw.solver.SimpleSolver包装优化器，对于已经构建好的QuboModel，可以直接调用优化器的solve_qubo方法：

optimizer = kw.classical.SimulatedAnnealingOptimizer(
    initial_temperature=100,
    alpha=0.99,
    cutoff_temperature=0.001,
    iterations_per_t=10,
    size_limit=100,
)
solutions = optimizer.solve_qubo(qubo_model)

如果模型中包含需要迭代调整惩罚系数的约束，可以使用kw.hybrid.PenaltyMethodOptimizer包装基础优化器：

optimizer = kw.classical.SimulatedAnnealingOptimizer(size_limit=100)
controller = kw.common.SolverLoopController(
    max_repeat_step=100,
    no_improve_limit=100,
)
solver = kw.hybrid.PenaltyMethodOptimizer(optimizer, controller)
solution_dict, objective = solver.solve_qubo(qubo_model)

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