SuperAPI AI 工具集

cudaq-importing

编程与开发

查看项目

更新于 10-16 02:33

技能介绍

用途:把其他量子框架(如 Qiskit 及 Qiskit 风格线路构建器)的线路移植为 CUDA-Q Python kernel,目标是得到不依赖源框架的 CUDA-Q 实现,保持源量子算法不变,在小规模测试上与源行为一致,并记录无法避免的 CUDA-Q 限制。若需从零编写 CUDA-Q kernel,或涉及安装、模拟目标、QPU 访问与并行化,应使用配套的 cudaq-guide 技能。

前提:Python 3.10+;目标环境已安装 CUDA-Q,可用 python -c "import cudaq; print(getattr(cudaq, 'version', 'unknown'))" 检查版本;能访问源实现并运行或检查其预期行为;源框架(如 Qiskit/Aer)只需装在验证环境,最终移植不得依赖它。使用文档或仓库 MCP 连接器前先确认可用,否则改用本地文档或源码树。

主要能力与流程:读取源线路构建,识别算法、比特/寄存器布局、测量行为与框架辅助函数;保留高层算法,未经用户许可不得替换中段测量、QPE 结构、oracle 定义或分解策略;选择执行模式——最终测量采样用 cudaq.sample,需按 shot 返回或使用中段测量值时用 cudaq.run,优先用运行时参数 kernel 而非按规模生成的 kernel;翻译门与子线路(细节见 references/porting-reference.md);移除运行时源框架依赖,把纯辅助函数抽到无框架模块;先用小规模确定性输入验证,比较原始计数键与分布而非仅聚合保真度;每次修复后重跑此前失败的配置。

核心规则:保持源算法完整;不引入固定比特上限、固定控制元数或源框架导入,除非确实不可避免并已记录;优先使用原生 CUDA-Q 门(r1.ctrl、x.ctrl、swap.ctrl 等);比特序转换只放在移植边界(分配顺序、测量返回列表或计数键格式化);比较结果时匹配浮点精度(CUDA-Q 默认 fp32,Qiskit 为 fp64);源标志在 CUDA-Q 中变为空操作时,若保持源兼容行为则可接受。

限制:指南面向 CUDA-Q 0.14/0.15 装饰器模式 Python API,版本敏感特性需按已安装版本复核;CUDA-Q kernel 语言构造比普通 Python 受限;两框架默认精度与计数键显示顺序不同,保真度或比特串差异可能是约定差异;硬件目标行为、可用后端与目标选项取决于本地安装;本技能不保证性能等价,只关注保持正确性的移植。

排错要点:出现 ModuleNotFoundError: qiskit 说明移植仍导入源框架,应把纯辅助函数移入无框架模块;保真度看似合理但原始键反序,应在边界修正分配、返回列表顺序或格式化,不改算法;深线路保真度差异可能源于精度不同,先匹配精度再重跑最小失败用例;多控操作在高元数下失败或静默改变,说明用了固定元数分发器,应改用 CUDA-Q 控制列表模式;MCP 查询失败先确认连接器再回退本地文档,不要基于未验证结果改动移植;行为与文档冲突时先查 cudaq.version 再对照文档或源码变更。