pyqpanda_alg.plugin¶

Classes¶

hadamard_circuit

自定义Hadamard电路类，继承自QCircuit。

Functions¶

`apply_QGate`(→ pyqpanda3.core.QCircuit)	批量为量子比特列表中的每个量子比特应用自定义量子门函数，生成并返回组合后的量子电路。
`measure_all`(→ pyqpanda3.core.QProg)	批量创建量子比特到经典比特的测量操作，组合为量子程序（QProg）。
`qft`(→ pyqpanda3.core.QCircuit)	构建量子傅里叶变换（QFT）电路，对输入的量子比特列表应用QFT操作。
`QFT`(→ pyqpanda3.core.QCircuit)	实现完整的量子傅里叶变换（QFT）电路，包含相位变换和比特交换步骤。
`bind_nonnegative_data`(→ pyqpanda3.core.QCircuit)	将非负整数绑定到量子比特列表，生成初始化电路（将量子比特从全\|0⟩态转换为对应整数的量子态）。
`parse_quantum_result_dict`(→ Dict[str, float])	解析量子程序测量结果字典，支持筛选Top-N概率结果，保持与prob_run_dict一致的功能逻辑。
`parse_quantum_result_list`(→ List[float])	解析量子程序测量结果列表，支持筛选Top-N概率结果，功能逻辑与字典版本保持一致。

Module Contents¶

class pyqpanda_alg.plugin.hadamard_circuit(qubit_list: list[int])¶

Bases: pyqpanda3.core.QCircuit

digraph inheritance3ba5ca4bc7 { bgcolor=transparent; rankdir=TB; size=""; "hadamard_circuit" [URL="../autoapi/pyqpanda_alg/plugin/index.html#pyqpanda_alg.plugin.hadamard_circuit",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="自定义Hadamard电路类，继承自QCircuit。"]; }

自定义Hadamard电路类，继承自QCircuit。功能：为输入的Python列表（含量子比特索引）中的每个量子比特应用Hadamard门。

pyqpanda_alg.plugin.apply_QGate(qubit_list: list[int], func_obj) → pyqpanda3.core.QCircuit¶

批量为量子比特列表中的每个量子比特应用自定义量子门函数，生成并返回组合后的量子电路。

功能说明：

遍历输入的量子比特列表，对每个量子比特应用`func_obj`生成的量子门（QGate），所有门操作按顺序组合成一个QCircuit对象，便于嵌入主量子程序中执行。支持PyQpanda3内置门函数（如H、X、RX等）或自定义门生成函数。

参数：

qubit_list (list[int]): 量子比特索引列表，元素为非负整数（size_t类型），: 表示需要应用门操作的量子比特。例如：[0, 1, 2] 对应第0、1、2个量子比特。
func_obj: 门生成函数，接收一个量子比特索引（int）作为输入，返回一个QGate对象。: 要求： - 输入必须为整数（量子比特索引）； - 返回值必须是PyQpanda3的QGate类型（如H门、RX门等）。示例：pq.H（Hadamard门）、lambda q: pq.RX(q, 0.5)（带角度的RX门）。

返回：

QCircuit: 包含所有量子门操作的电路对象，可通过`<<`操作符嵌入主程序（QProg）。

异常：

TypeError: 若`qubit_list`中元素不是整数，或`func_obj`返回值不是QGate类型。 ValueError: 若`qubit_list`中包含负数（不符合size_t无符号整数特性）。

使用示例：

批量应用Hadamard门：

>>> q_list = [0, 1, 2]
>>> circuit = apply_QGate(q_list, H)
>>> # 电路包含：H(0) << H(1) << H(2)

批量应用带参数的RX门：

>>> q_list = [0, 1]
>>> rx_func = lambda q: RX(q, 0.314)  # 自定义带固定角度的RX门函数
>>> circuit = apply_QGate(q_list, rx_func)
>>> # 电路包含：RX(0, 0.314) << RX(1, 0.314)

动态生成门（根据量子比特索引调整参数）：

>>> q_list = [0, 1, 2]
>>> def dynamic_gate(q):
...     angles = [0.1, 0.2, 0.3]  # 为不同qubit设置不同角度
...     return RY(q, angles[q])
>>> circuit = apply_QGate(q_list, dynamic_gate)
>>> # 电路包含：RY(0, 0.1) << RY(1, 0.2) << RY(2, 0.3)

pyqpanda_alg.plugin.measure_all(qubit_list: list[int], cbit_list: list[int]) → pyqpanda3.core.QProg¶

批量创建量子比特到经典比特的测量操作，组合为量子程序（QProg）。

功能说明：

为输入的量子比特索引列表和经典比特索引列表创建一一对应的测量操作，所有测量操作按顺序添加到QProg中，用于读取量子态的测量结果。要求量子比特列表和经典比特列表长度必须相等。

参数：

qubit_list (list[int]): 量子比特索引列表（非负整数），表示需要测量的量子比特。: 例如：[0, 1, 2] 对应第0、1、2个量子比特。
cbit_list (list[int]): 经典比特索引列表（非负整数），用于存储测量结果。: 例如：[0, 1, 2] 对应第0、1、2个经典比特。

返回：

QProg: 包含所有测量操作的量子程序，可直接嵌入主量子程序中执行。

异常：

ValueError: 若qubit_list与cbit_list的长度不相等。 TypeError: 若列表中包含非整数元素。

使用示例：

>>> # 测量量子比特0、1到经典比特0、1
>>> q_list = [0, 1]
>>> c_list = [0, 1]
>>> measure_prog = measure_all(q_list, c_list)
>>> # 测量程序包含：Measure(0, 0) << Measure(1, 1)

pyqpanda_alg.plugin.qft(qubit_list: list[int]) → pyqpanda3.core.QCircuit¶

构建量子傅里叶变换（QFT）电路，对输入的量子比特列表应用QFT操作。

功能说明：

量子傅里叶变换是经典傅里叶变换的量子版本，通过Hadamard门和受控旋转门（CR）的组合实现，可在O(n²)时间内完成n个量子比特的傅里叶变换，远快于经典算法的O(n·2ⁿ)。本实现遵循标准QFT电路结构：从最后一个量子比特开始，逐层应用H门和CR门。

参数：

qubit_list (list[int]): 量子比特索引列表（非负整数），表示参与QFT的量子比特。: 例如：[0, 1, 2] 表示对3个量子比特执行QFT。

返回：

QCircuit: 包含完整QFT操作的量子电路，可嵌入主程序执行。

异常：

TypeError: 若qubit_list中包含非整数元素。 ValueError: 若qubit_list为空或包含负数索引。

使用示例：

>>> # 对3个量子比特（0,1,2）执行QFT
>>> q_list = [0, 1, 2]
>>> qft_circuit = qft(q_list)
>>> # 电路结构：
>>> # H(2) << CR(1, 2, π) << CR(0, 2, π/2)
>>> # << H(1) << CR(0, 1, π)
>>> # << H(0)
>>>
>>> # 嵌入主程序执行
>>> qvm = pq.QMachine(pq.QMachineType.CPU)
>>> main_prog = pq.QProg()
>>> main_prog << qft_circuit  # 添加QFT电路
>>> qvm.run(main_prog)

pyqpanda_alg.plugin.QFT(qubit_list: list[int]) → pyqpanda3.core.QCircuit¶

实现完整的量子傅里叶变换（QFT）电路，包含相位变换和比特交换步骤。

功能说明：

量子傅里叶变换是经典离散傅里叶变换的量子版本，通过H门、CR门实现相位变换，最后通过SWAP门修正比特顺序，输出符合标准傅里叶变换的量子态。适用于量子算法中需要频率域分析的场景（如Shor算法、量子相位估计等）。

参数：

qubit_list (list[int]): 量子比特索引列表（非负整数），按从低到高顺序传入。: 例如：[0, 1, 2] 表示3个量子比特，0为最低位，2为最高位。

返回：

QCircuit: 包含完整QFT操作的量子电路（含SWAP交换）。

异常：

TypeError: 若列表中包含非整数元素。 ValueError: 若列表为空或包含负数索引。

使用示例：

>>> q_list = [0, 1, 2]  # 3个量子比特
>>> qft_circuit = qft(q_list)
>>> # 电路结构：
>>> # 相位变换部分：H(2) << CR(1,2,π/2) << CR(0,2,π/4)
>>> #            << H(1) << CR(0,1,π/2)
>>> #            << H(0)
>>> # 交换部分：SWAP(0,2)
>>>
>>> # 嵌入主程序执行
>>> qvm = pq.QMachine(pq.QMachineType.CPU)
>>> main_prog = pq.QProg() << qft_circuit
>>> qvm.run(main_prog)

pyqpanda_alg.plugin.bind_nonnegative_data(value: int, qubit_list: list[int]) → pyqpanda3.core.QCircuit¶

将非负整数绑定到量子比特列表，生成初始化电路（将量子比特从全|0⟩态转换为对应整数的量子态）。

功能说明：

根据输入整数的二进制表示，通过X门翻转量子比特列表中对应位置的比特（1对应|1⟩，0对应|0⟩），实现经典数据到量子态的映射。量子比特列表的初始状态需为全|0⟩，且不考虑符号位（仅支持非负数）。

参数：

value (int): 待绑定的非负整数（≥0）。 qubit_list (list[int]): 量子比特索引列表（非负整数），用于存储量子态。

返回：

QCircuit: 初始化电路，包含X门操作，使量子比特列表表示value的二进制形式。

异常：

ValueError: 若value为负数，或qubit_list长度不足（无法存储value的二进制表示）。 TypeError: 若qubit_list中包含非整数元素。

使用示例：

>>> # 将整数5（二进制101）绑定到3个量子比特[0,1,2]
>>> circuit = bind_nonnegative_data(5, [0, 1, 2])
>>> # 电路包含：X(0) << X(2)（对应二进制101，低位在前）
>>>
>>> # 验证：量子比特0和2被翻转为|1⟩，1保持|0⟩
>>> qvm = pq.QMachine(pq.QMachineType.CPU)
>>> main_prog = pq.QProg() << circuit
>>> qvm.run(main_prog)

pyqpanda_alg.plugin.parse_quantum_result_dict(result: Dict[str, float], qubit_list: List[int], select_max: int = -1) → Dict[str, float]¶

解析量子程序测量结果字典，支持筛选Top-N概率结果，保持与prob_run_dict一致的功能逻辑。

功能说明：

对量子测量结果（键为二进制字符串，值为概率）进行处理，根据select_max筛选结果，同时验证结果的合法性（如概率和为1），并保持与原量子比特顺序的对应关系。

参数：

result (Dict[str, float]): 原始测量结果字典，键为二进制字符串（如”0110”），: 值为对应结果的概率（浮点数，范围[0,1]）。

qubit_list (List[int]): 测量的量子比特索引列表，用于验证二进制字符串长度是否匹配。 select_max (int, 可选): 限制返回结果的数量，默认为-1（返回所有结果）。

取值范围：[-1, 2^len(qubit_list)]，其中-1表示无限制，正整数n表示返回前n个最高概率结果。

返回：

Dict[str, float]: 处理后的测量结果字典，按概率从高到低排序（若select_max>0）。

异常：

ValueError: 若输入参数不合法（如select_max超出范围、二进制字符串长度与qubit_list不匹配、概率和不为1等）。 TypeError: 若输入result不是字典或概率不是浮点数。

使用示例：

>>> # 原始结果：3个量子比特的测量概率
>>> raw_result = {"000": 0.1, "111": 0.8, "010": 0.1}
>>> qubit_list = [0, 1, 2]
>>>
>>> # 1. 返回所有结果
>>> parse_quantum_result(raw_result, qubit_list)
{'000': 0.1, '111': 0.8, '010': 0.1}
>>>
>>> # 2. 返回概率最高的1个结果
>>> parse_quantum_result(raw_result, qubit_list, select_max=1)
{'111': 0.8}
>>>
>>> # 3. 返回概率最高的2个结果
>>> parse_quantum_result(raw_result, qubit_list, select_max=2)
{'111': 0.8, '000': 0.1, '010': 0.1}  # 概率相同则保留原始顺序

pyqpanda_alg.plugin.parse_quantum_result_list(result: List[float], qubit_list: List[int], select_max: int = -1) → List[float]¶

解析量子程序测量结果列表，支持筛选Top-N概率结果，功能逻辑与字典版本保持一致。

功能说明：

对量子测量结果列表（元素为概率值）进行处理，根据select_max筛选结果，验证结果的合法性（如概率和为1），保持与原量子比特顺序的对应关系。列表索引对应二进制结果（如索引0对应”000…”, 索引1对应”000…1”等）。

参数：

result (List[float]): 原始测量结果列表，元素为概率值（范围[0,1]），: 索引对应二进制结果（按整数解析，如索引3对应二进制”11”）。

qubit_list (List[int]): 测量的量子比特索引列表，用于确定总结果数。 select_max (int, 可选): 限制返回结果的数量，默认为-1（返回所有结果）。

取值范围：[-1, 2^len(qubit_list)]，其中-1表示无限制，正整数n表示返回前n个最高概率结果。

返回：

List[float]: 处理后的测量结果列表，按概率从高到低排序（若select_max>0）。

异常：

ValueError: 若输入参数不合法（如select_max超出范围、列表长度不符合量子比特数、概率和不为1等）。 TypeError: 若输入result不是列表或元素不是浮点数。