科学计算【免费下载链接】qiskitQiskit is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.项目地址https://gitcode.com/gh_mirrors/qi/qiskit点击查看免费下载导读Qiskit 的合成synthesis流程并不局限于内置算法qiskit.transpiler.passes.synthesis.plugin模块为外部 Python 包提供了一整套基于 setuptools entry points 的插件接口让任何人都可以把自定义的酉矩阵分解算法或高层对象Clifford、线性函数、置换门等合成算法无缝接入qiskit.compiler.transpile的编译管线并以可选项形式暴露给用户。本文以 docs/apidoc/transpiler_synthesis_plugins.rst 对应的合成插件文档为主线结合仓库源码逐层拆解两套插件 API 的接口契约、注册方式、配置传递机制以及 Qiskit 内置的全部插件读完即可独立编写、注册并使用自己的合成插件。一、Synthesis Plugins 模块概览Qiskit 中的合成插件机制定义在 qiskit/transpiler/passes/synthesis/plugin.py其核心设计目标是为合成类 transpiler pass 提供外部 hook 点使第三方 Python 包可以实现自己的合成技术并作为 opt-in 选项无缝暴露给运行transpile()的用户。插件接口基于 setuptools 的 entry points 机制构建外部包通过声明 entry point 向 Qiskit 广播我包含一个合成插件。模块内一共定义了两套互不相同的插件体系插件体系合成对象命名空间消费它的 transpiler passUnitary Synthesis Pluginnumpy 酉矩阵qiskit.unitary_synthesisUnitarySynthesisHigh-Level Synthesis PluginOperation高层对象Clifford、LinearFunction、PermutationGate 等qiskit.synthesisHighLevelSynthesis从源码结构看两套体系分别由 UnitarySynthesisPlugin、HighLevelSynthesisPlugin 两个抽象基类、各自的*Manager管理类以及*_plugin_names查询函数构成。若读者关心的是 transpiler 各阶段layout、routing、translation 等的插件可参考 preset passmanager 的插件文档qiskit.transpiler.preset_passmanagers.plugin与本文的合成插件属于平行的两套机制。二、Unitary Synthesis 插件 API2.1 接口契约UnitarySynthesisPluginplugin.py是一个abc.ABC抽象类定义了一组supports_*属性与一个核心方法run()。run()接收单个位置参数——以 numpy 数组表示的酉矩阵并返回代表该矩阵合成结果的 DAGCircuit 对象如果插件无法合成可以返回None此时 pass 不会做替换。抽象类要求子类必须实现如下属性均为propertyabc.abstractmethodmin_qubits/max_qubits插件支持的酉矩阵最小/最大量子比特数。超出范围时pass 会回退到default插件若没有上/下界则返回None。supports_basis_gates返回True时run()会收到basis_gateskwarg目标后端支持的门的名称列表如[sx, x, cx, id, rz]。supports_coupling_map返回True时run()收到coupling_mapkwarg——一个二元组(CouplingMap, qubit_indices)前者是目标后端的量子比特连接关系后者是酉矩阵所在的量子比特索引列表若后端未设置耦合图则为(None, qubit_indices)。supports_natural_direction是否支持以natural_direction开关考虑双量子比特门的方向性具体取值与含义见UnitarySynthesispass 文档。supports_pulse_optimize是否支持在合成过程中优化脉冲pulse_optimize开关。supports_gate_lengths返回True时run()收到gate_lengths——形如{gate_name: {(qubit_1, qubit_2): length}}的字典length单位为秒该数据来自目标后端可能不完整甚至为空。supports_gate_errors返回True时run()收到gate_errors——形如{gate_name: {(qubit_1, qubit_2): error}}的字典错误率由目标后端提供不同后端的含义可能不同。supported_bases返回支持的合成基组字典如{XZX: [rz, rx], XYX: [rx, ry]}若只支持单一基组则返回None。返回字典时run()会额外收到matched_basiskwarg即与目标基门集合匹配的基组字符串列表无匹配则为空列表由插件自行决定处理策略。除上述必须实现的属性外基类还提供两个默认返回False、可按需覆写的可选属性supports_gate_lengths_by_qubit/supports_gate_errors_by_qubit与按门名索引的数据不同这两个开关提供按量子比特索引的视图——字典形如{(qubits,): [Gate, length]}用Gate实例而非门名作为键。例如{(0,): [SXGate(): 0.0006149355812506126, RZGate(): 0.0], (0, 1): [CXGate(): 0.012012477900732316]}。supports_target返回True时run()收到targetTarget对象。由于插件接口早于Target类出现该属性默认False若插件启用它则应优先使用Target而非supports_gate_lengths等开关传入的重复信息。run()的返回值有三种形态仅返回DAGCircuit返回(dag, wires)二元组wires用于DAGCircuit.substitute_node_with_dag的线映射为None时等价于只返回 DAG返回None表示放弃替换。一个值得注意的约定所有以supports_前缀命名的方法在UnitarySynthesisPlugin子类上都被保留为接口的一部分不应在子类中自定义任何抽象类未定义的supports_*方法。2.2 管理器与查询函数UnitarySynthesisPluginManagerplugin.py跟踪已安装插件内部通过stevedore.ExtensionManager(qiskit.unitary_synthesis, invoke_on_loadTrue, propagate_map_exceptionsTrue)加载全部 entry point单条属性ext_plugins持有 stevedore 插件对象列表。unitary_synthesis_plugin_names()plugin.py返回已安装的全部 unitary 合成插件名称列表这些名称正是transpile()的unitary_synthesis_methodkwarg 的合法取值。三、High-Level Synthesis 插件 API3.1 接口契约HighLevelSynthesisPluginplugin.py同样是一个抽象基类只要求实现一个run()方法def run(self, high_level_object, coupling_mapNone, targetNone, qubitsNone, **options):各参数含义high_level_object待合成的高层对象即任意Operation类型实例典型如LinearFunction、Clifford。target目标后端Target插件可从中读取耦合图、受支持门集等全部目标相关信息。coupling_map仅在未指定target时使用只提供耦合图信息。qubits若合成发生在物理线路上给出高层对象所在的量子比特列表值为None表示布局尚未选定、物理量子比特未知。options自由形式的配置字典用于传递插件专属参数。run()应返回合成结果的 QuantumCircuit返回None表示该插件无法合成给定的高层对象调用方会继续尝试下一个插件。高层对象的实际合成由HighLevelSynthesistranspiler passhigh_level_synthesis.py驱动执行。3.2 管理器与查询函数HighLevelSynthesisPluginManagerplugin.py通过stevedore.ExtensionManager(qiskit.synthesis, ...)加载插件并将注册名按OperationName.SynthesisMethodName的格式解析、聚合为plugins_by_op字典op_name - [method_name, ...]同时提供method_names(op_name)、method(op_name, method_name)、op_names()三个查询接口。high_level_synthesis_plugin_names(op_name)plugin.py返回指定高层对象名即Operation.name属性例如clifford对应的已安装插件列表。四、编写 Unitary Synthesis 插件两步走4.1 第一步实现插件类以qiskit.transpiler.passes.synthesis.plugin.UnitarySynthesisPlugin为基类创建子类实现所有抽象属性与run()from qiskit.transpiler.passes.synthesis import plugin from qiskit_plugin_pkg.synthesis import generate_dag_circuit_from_matrix class SpecialUnitarySynthesis(plugin.UnitarySynthesisPlugin): property def supports_basis_gates(self): return True property def supports_coupling_map(self): return False property def supports_natural_direction(self): return False property def supports_pulse_optimize(self): return False property def supports_gate_lengths(self): return False property def supports_gate_errors(self): return False property def supports_gate_lengths_by_qubit(self): return False property def supports_gate_errors_by_qubit(self): return False property def min_qubits(self): return None property def max_qubits(self): return None property def supported_bases(self): return None def run(self, unitary, **options): basis_gates options[basis_gates] dag_circuit generate_dag_circuit_from_matrix(unitary, basis_gates) return dag_circuit需要说明的是run()实际能收到的 kwarg 完全由supports_*属性的返回值决定pass 在 unitary_synthesis.py 中逐项检查属性并构造 kwargs包括basis_gates、natural_direction、pulse_optimize、gate_lengths、gate_errors、gate_lengths_by_qubit、gate_errors_by_qubit、matched_basis、target、coupling_map与config只有对应开关返回True的参数才会被传入。因此文档中的示例直接读取options[basis_gates]是安全的——因为supports_basis_gates已返回True。接口稳定性承诺该插件接口被视为稳定接口保证不会以破坏性方式变更。即使未来需要扩展可选输入例如新增可选 kwarg也会以无需修改现有插件的方式进行。若现有run()输入确实不够用建议在 Qiskit 仓库提交 issue 讨论扩展方案。4.2 第二步注册 entry point在插件包的pyproject.toml中为qiskit.unitary_synthesis命名空间添加[project.entry-points]表[project.entry-points.qiskit.unitary_synthesis] special qiskit_plugin_pkg.module.plugin:SpecialUnitarySynthesis约束与惯例单个包可暴露任意数量插件只需保证每个插件名唯一名称default被 Qiskit 自身保留对应DefaultUnitarySynthesis见 pyproject.toml插件不能使用。4.3 插件专属配置字典对于暴露多个可调参数与开关的插件接口预留了自由格式配置用户提供的配置字典会原样以optionskwarg 传入run()。该字段完全自由因此插件作者必须在文档中明确说明用户如何填写这些配置项及其用途。在transpile()层面这个字典就是unitary_synthesis_plugin_config参数见 qiskit/compiler/transpiler.py。五、编写 High-Level Synthesis 插件两步走5.1 第一步实现插件类概念上与 unitary 插件类似但run()接收的是高层对象而非矩阵且返回QuantumCircuit或Nonefrom qiskit.transpiler.passes.synthesis.plugin import HighLevelSynthesisPlugin from qiskit.synthesis.clifford import synth_clifford_bm class SpecialSynthesisClifford(HighLevelSynthesisPlugin): def run(self, high_level_object, coupling_mapNone, targetNone, qubitsNone, **options): if high_level_object.num_qubits 3: return synth_clifford_bm(high_level_object) else: return None上述示例针对Clifford类型对象不超过 3 个量子比特时用synth_clifford_bm合成否则返回None表示无法处理。5.2 第二步注册 entry point在pyproject.toml中为qiskit.synthesis命名空间添加 entry point。插件名由两部分组成用点号分隔第一部分是高层Operation的类型名如clifford第二部分是插件名如special[project.entry-points.qiskit.synthesis] clifford.special qiskit_plugin_pkg.module.plugin:SpecialSynthesisClifford单包同样可以注册任意数量的插件只要名称唯一。Qiskit 官方内置插件的注册方式可参考 pyproject.toml 中qiskit.synthesis命名空间的完整列表例如clifford.default、clifford.layers、linear_function.pmh、permutation.acg等。六、使用插件6.1 自动发现与 Unitary 插件的使用使用插件的唯一前置动作是安装包含该插件的包。安装后 Qiskit 会自动发现已安装插件并将其暴露为transpile()相应 kwarg 与 pass 构造器的合法选项任何无法加载/导入的插件都会被记录到 Python logging 中不会导致崩溃。获取已安装的 unitary 合成插件列表from qiskit.transpiler.passes.synthesis.plugin import unitary_synthesis_plugin_names print(unitary_synthesis_plugin_names())在transpile()中指定合成方法与配置参数定义见 qiskit/compiler/transpiler.pyfrom qiskit import transpile circuit transpile( qc, basis_gates[cx, u], unitary_synthesis_methodaqc, unitary_synthesis_plugin_config{network_layout: sequ, depth: 5}, )其中unitary_synthesis_method决定选用哪个插件unitary_synthesis_plugin_config字典直接透传给插件的run(**options)。6.2 HLSConfig 与 High-Level 插件的使用使用高层合成插件前需要先实例化 HLSConfig 来登记各类高层对象要使用的插件from qiskit.transpiler.passes.synthesis.high_level_synthesis import HLSConfig hls_config HLSConfig(permutation[acg], clifford[layers], linear_function[pmh])该配置的含义用acg插件合成PermutationGate用layers插件合成Clifford用pmh插件合成LinearFunction。关键字参数就是相关对象的Operation.name字段——例如所有Clifford操作的 name 都是clifford因此用作关键字任何已安装插件的对象名包括自定义用户对象都可作为关键字。HLSConfig构造器high_level_synthesis.py还提供三个可配置项use_default_on_unspecified默认True未显式指定方法列表的高层对象若存在default算法则自动使用。plugin_selection默认sequentialsequential模式下按顺序尝试各方法遇到第一个能成功合成的即停止all模式下运行全部方法按plugin_evaluation_fn选出最佳结果。plugin_evaluation_fn在all模式下评估合成电路质量的回调返回值越小越好为None时默认以电路规模所含门数qc.size()为指标。每种方法的指定方式有四种等价写法详见 high_level_synthesis.py# 方式1插件名 参数字典 hls_config HLSConfig(permutation[(acg, {})]) # 方式2仅插件名 hls_config HLSConfig(permutation[acg]) # 方式3插件实例 参数字典 hls_config HLSConfig(permutation[(ACGSynthesisPermutation(), {})]) # 方式4仅插件实例 hls_config HLSConfig(permutation[ACGSynthesisPermutation()])注意第三种、第四种方式直接传入插件实例无需在 entry points 中注册见 high_level_synthesis.py 的解析逻辑字符串形式的插件名必须能在hls_plugin_manager中查到否则抛出TranspilerError实例则直接使用。此外给某类对象赋一个空方法列表即可禁止合成它方法也可写成(name, options)元组第二元素是传给该插件的配置字典。创建配置后把它传给transpile()或generate_preset_pass_manager()的hls_config参数作为更大编译流程的一部分生效circuit transpile(qc, basis_gates[cx, u], hls_confighls_config)底层执行时HighLevelSynthesispass 会为每个高层对象依次调用各插件并注入一组附加上下文参数input_qubits、hls_data、qubit_tracker、可用 clean/dirty ancilla 数量、optimization_metric与optimization_level等见 high_level_synthesis.pysequential模式下第一个返回非None的结果即被采用all模式下则持续比较打分取最优high_level_synthesis.py。查询某类对象可用的插件from qiskit.transpiler.passes.synthesis.plugin import high_level_synthesis_plugin_names high_level_synthesis_plugin_names(clifford)该调用返回所有已安装的 Clifford 合成插件列表。七、Qiskit 内置插件一览文档特别提醒以下类不应被直接实例化使用而应通过上述插件接口unitary_synthesis_method/HLSConfig间接调用此处列出是为了便于查找文档与横向比较不同合成方法。7.1 内置 Unitary Synthesis 插件Qiskit 官方在 pyproject.toml 的qiskit.unitary_synthesis命名空间注册了 5 个插件插件名插件类说明defaultDefaultUnitarySynthesis默认插件全面支持basis_gates、coupling_map、natural_direction、pulse_optimize、gate_lengths_by_qubit、gate_errors_by_qubit与target见 default_unitary_synth_plugin.pymin_qubits/max_qubits均无限制aqcAQCSynthesisPlugin基于近似量子编译AQC的合成支持 3–14 个量子比特aqc_plugin.pyskSolovayKitaevSynthesisSolovay-Kitaev 算法面向单比特门离散基分解solovay_kitaev_synthesis.pygridsynthRossSelingerSynthesisRoss-Selinger 算法无辅助比特的 CliffordT 近似 z 旋转仅支持单比特ross_selinger_plugin.pycliffordCliffordUnitarySynthesis检测酉矩阵是否可由 Clifford 表示并输出纯 Clifford 门电路clifford_unitary_synth_plugin.py各插件的专属配置项通过unitary_synthesis_plugin_config传入aqcaqc_plugin.pynetwork_layoutsequ/spin/cart/cyclic_spin/cyclic_line默认spin、connectivity_typefull/line/star默认full、depthCNOT 网络层数、optimizerMinimizer协议实现、seed随机种子、initial_point优化起始参数。sksolovay_kitaev_synthesis.pybasic_approximations.npy文件路径或{label: SO(3)-matrix}字典默认按basis_gates与depth生成、basis_gates离散基门列表默认[h, t, tdg]、depth基本近似门深度默认 12、recursion_degree递归改进次数默认 5。该插件会缓存生成的近似以加速重复调用。gridsynthross_selinger_plugin.pyepsilon允许的近似误差。cliffordmin_qubits默认 1、max_qubits默认 3。7.2 内置 High-Level Synthesis 插件Qiskit 官方在 hls_plugins.py 中为多种高层对象内置了插件按连接性假设可分为三类这也决定了其适用阶段面向全连接all-to-all的插件合成的电路假设任意两比特可直连通常在布局与布线之前运行之后由布线阶段插入额外 SWAP 门来满足设备连接性。典型例子是ACGSynthesisPermutation——任何置换最多只需 2 层 SWAP。面向线性连接linear的插件合成的电路深度与门数通常更大但如果后续布局恰好选中拓扑中的一段连续量子比特线则几乎无需插入 SWAP。典型例子是KMSSynthesisPermutation——任意 n 比特置换的深度为 n。面向给定连接性的插件必须在布局确定之后运行合成的电路天然符合设备拓扑。典型例子是TokenSwapperSynthesisPermutation——可针对任意耦合图合成任意置换。由于事先很难判断全连接合成 插入 SWAP与线性连接合成 少插入/不插入 SWAP哪种最终电路更优文档建议两者都试再比较结果。Clifford 插件表关键字clifford见 hls_plugins.py插件名插件类目标连接性说明agAGSynthesisCliffordall-to-all贪心优化 CX 门数量bmBMSynthesisCliffordall-to-alln∈{2,3} 时 CX 数量最优default在 n∈{2,3} 时使用它greedyGreedySynthesisCliffordall-to-all贪心优化 CX 数量default在 n≥4 时使用它layersLayerSynthesisCliffordall-to-all分层合成lnnLayerLnnSynthesisCliffordlinearCX 门较多但保证 CX 深度不超过 7n2defaultDefaultSynthesisCliffordall-to-all通常最利于优化 CX 数量n∈{2,3} 时最优DefaultSynthesisClifford的实现hls_plugins.py在 n≤3 时采用 Bravyi-Maslov 最优分解、n3 时采用 Bravyi-Hu-Maslov-Shaydulin 贪心编译非Clifford对象直接返回None。LinearFunction 插件表关键字linear_function见 hls_plugins.py插件名插件类目标连接性说明kmsKMSSynthesisLinearFunctionlinearCX 门较多但保证 CX 深度不超过 5npmhPMHSynthesisLinearFunctionall-to-allPatel-Markov-Hayes 方法defaultDefaultSynthesisLinearFunctionall-to-all使用 pmh 实现KMSSynthesisLinearFunction与PMHSynthesisLinearFunction都支持use_inverted对逆矩阵运行算法再反转电路与use_transposed对转置矩阵运行算法再反转 CX 顺序两个开关某些情况下能获得更好的分解pmh另支持section_size参数默认 2hls_plugins.py。PermutationGate 插件表关键字permutation见 hls_plugins.py插件名插件类目标连接性说明basicBasicSynthesisPermutationall-to-allSWAP 数量最优default使用它acgACGSynthesisPermutationall-to-all保证 SWAP 深度不超过 2kmsKMSSynthesisPermutationlinearSWAP 门较多但保证 SWAP 深度不超过 ntoken_swapperTokenSwapperSynthesisPermutation任意针对任意连接性贪心优化 SWAP 数量defaultBasicSynthesisPermutationall-to-all最利于优化 SWAP 数量例如HLSConfig(permutation[kms])即创建了一个使用kms插件合成PermutationGatename permutation的配置——该算法生成的是符合线性最近邻连接性的电路。TokenSwapperSynthesisPermutation的运行细节值得留意hls_plugins.py当coupling_map与qubits均为None布局前时使用全连接耦合图两者都给出时则把耦合图缩减到置换门所在的量子比特子集上做 token swapper 布线仅生成这些比特之间的 SWAP若无法完成则返回None。其可配置项为trials尝试次数默认 5、seed随机种子默认 0、parallel_threshold并行阈值默认 50。此外hls_plugins.py 还提供了qftQFT 门支持reverse_qubits、approximation_degree、insert_barriers、inverse、name等选项、mcx多控 X 门、mcmt、IntComp整数比较器、WeightedSum、PauliEvolution、ModularAdder、HalfAdder、FullAdder、Multiplier等更多内置高层合成插件可在需要时按相同方式查阅。八、从源码看插件加载与回退机制最后补充几个源码级细节帮助理解插件体系的实际行为加载即校验UnitarySynthesisPluginManager构造时直接创建stevedore.ExtensionManager并设置invoke_on_loadTrue、propagate_map_exceptionsTrueplugin.py即 entry point 指向的类在加载时即被实例化导入错误会显式暴露。范围与回退UnitarySynthesispass 会检查选定插件的min_qubits/max_qubits超出范围的酉矩阵自动交给default插件处理unitary_synthesis.py若非默认插件返回None且设置了fallback_on_default则回退到默认插件unitary_synthesis.py。控制流操作if、for等内部的子块也会被递归地送入同一合成流程unitary_synthesis.py。HLS 的逐方法协商HighLevelSynthesispass 对每个高层对象按配置的方法列表逐个尝试插件返回None即视为不适合该对象并继续尝试下一个在sequential模式下第一个成功者胜出all模式下按评估函数打分择优high_level_synthesis.py。名字即路由高层插件管理器把 entry point 名按op_name.method_name拆分为两层键plugin.py因此注册名必须以点号分隔且两段分别对应Operation.name与插件名。以上机制共同保证了插件体系向后兼容的扩展性新输入以可选 kwarg 形式增量加入已有插件无需任何改动即可继续工作。赞分享科学计算【免费下载链接】qiskitQiskit is an open-source SDK for working with quantum computers at the level of extended quantum circuits, operators, and primitives.项目地址https://gitcode.com/gh_mirrors/qi/qiskit点击查看免费下载相关推荐Highlight.js与Vue.js集成教程vue-plugin插件使用详解Highlight.js与Vue.js集成教程vue plugin插件使用详解 Highlight.js是一个强大的JavaScript语法高亮库支持180前端OpenCode V2 Promise Plugin API 详解用 async/await 编写 OpenCode 插件OpenCode V2 Promise Plugin API 详解用 async/await 编写 OpenCode 插件 OpenCode V2 的插件体系人工智能AI 应用AI Agent代码智能体CLI开发者工具llama-cpp-python API 参考详解High Level 封装、ctypes 底层绑定与类型体系全解析llama cpp python API 参考详解High Level 封装、ctypes 底层绑定与类型体系全解析 llama cpp python 是 l人工智能大模型本地部署模型推理服务上一篇Unity移动端触控优化终极指南10个提升触屏体验的关键技巧下一篇5个实战技巧深度解析OCS网课助手自动化脚本开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
