编码 -- 量子态编码
Encode 类的 API 参考，提供将经典数据编码到量子态的方法。每种编码方法使用不同的策略将输入数据映射到量子比特上，产生一个 QCircuit，可通过 get_circuit() 获取。
Encode
python
class Encode:
def __init__() -> None构造新的 Encode 实例。
编码方法
basic_encode
将经典二进制字符串映射到量子比特。字符串中的每个字符决定对应量子比特的基态。
签名
python
basic_encode(qubits: list[int], data: str) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | str | 二进制字符串数据（例如 "1010"）。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
示例
python
from pyqpanda3.core import Encode
enc = Encode()
enc.basic_encode([0, 1, 2, 3], "1010")
circuit = enc.get_circuit()amplitude_encode
使用振幅编码将经典数据编码到量子态。输入矢量被归一化并映射到态矢量振幅上。
签名
python
amplitude_encode(qubits: list[int], data: list[float]) -> None
amplitude_encode(qubits: list[int], data: list[complex]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] 或 list[complex] | 经典数据矢量。自动归一化。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
示例
python
from pyqpanda3.core import Encode
enc = Encode()
enc.amplitude_encode([0, 1], [0.5, 0.5, 0.5, 0.5])
circuit = enc.get_circuit()amplitude_encode_recursive
使用递归振幅编码将经典数据编码到量子态。此方法将编码分解为更小的子问题，产生更有结构的线路。
签名
python
amplitude_encode_recursive(qubits: list[int], data: list[float]) -> None
amplitude_encode_recursive(qubits: list[int], data: list[complex]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] 或 list[complex] | 经典数据矢量。自动归一化。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
angle_encode
通过将每个值映射到对应量子比特的旋转角度来编码经典数据。常用于变分量子算法。
签名
python
angle_encode(qubits: list[int], data: list[float], gate_type: GateType = GateType.RY) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] | 用作旋转角度的数据值。 |
| gate_type | GateType | 旋转门类型。默认为 GateType.RY。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
示例
python
from pyqpanda3.core import Encode, GateType
enc = Encode()
enc.angle_encode([0, 1, 2], [0.5, 1.0, 1.5], gate_type=GateType.RX)
circuit = enc.get_circuit()dense_angle_encode
通过使用两个旋转轴在每个量子比特上编码两个经典数据值，提供比标准角度编码更紧凑的编码。
签名
python
dense_angle_encode(qubits: list[int], data: list[float]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] | 要编码的数据值。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
iqp_encode
使用瞬时量子多项式（IQP, Instantaneous Quantum Polynomial）编码对数据进行编码，在 Hadamard 基中应用参数化对角门。
签名
python
iqp_encode(
qubits: list[int],
data: list[float],
control_list: list[tuple[int, int]] = [],
bool_inverse: bool = False,
repeats: int = 1,
) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] | 要编码的数据值。 |
| control_list | list[tuple[int, int]] | 定义量子比特交互的配对。默认为空。 |
| bool_inverse | bool | 是否应用 IQP 线路的逆。默认为 False。 |
| repeats | int | 编码线路的重复次数。默认为 1。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
bid_amplitude_encode
使用 BID（双向）振幅编码对数据进行编码，迭代地将目标态分解为更小的块。
签名
python
bid_amplitude_encode(qubits: list[int], data: list[float], split: int = -1) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] | 表示量子态的振幅矢量。 |
| split | int | 迭代分解的块大小。默认为 -1（自动）。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
dc_amplitude_encode
使用 DC（分治法）振幅编码通过层次分解方法对数据进行编码。
签名
python
dc_amplitude_encode(qubits: list[int], data: list[float]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] | 表示量子态的振幅矢量。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
schmidt_encode
使用 Schmidt 分解对数据进行编码。目标态被分解为子系统的乘积，并使用截断值来截断小的奇异值。
签名
python
schmidt_encode(qubits: list[int], data: list[float], cutoff: float = 0.0) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] | 表示量子态的振幅矢量。 |
| cutoff | float | 截断小奇异值的阈值。默认为 0.0（不截断）。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
示例
python
from pyqpanda3.core import Encode
import numpy as np
data = np.array([0.5, 0.5, 0.5, 0.5])
enc = Encode()
enc.schmidt_encode([0, 1], data.tolist(), cutoff=1)
circuit = enc.get_circuit()sparse_isometry
使用等距分解制备稀疏量子态。接受多种格式的数据：将基态字符串映射到振幅的字典，或完整态矢量。
签名
python
sparse_isometry(qubits: list[int], data: dict[str, float]) -> None
sparse_isometry(qubits: list[int], data: dict[str, complex]) -> None
sparse_isometry(qubits: list[int], data: list[float]) -> None
sparse_isometry(qubits: list[int], data: list[complex]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | dict[str, float]、dict[str, complex]、list[float] 或 list[complex] | 稀疏态数据。当为字典时，键是基态二进制字符串（例如 "00"、"11"），值是振幅。当为列表时，视为完整态矢量。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
示例
python
from pyqpanda3.core import Encode
import numpy as np
enc = Encode()
enc.sparse_isometry([0, 1], {"00": 1.0/np.sqrt(2), "11": 1.0/np.sqrt(2)})
circuit = enc.get_circuit()efficient_sparse
使用高效稀疏分解制备稀疏量子态。与 sparse_isometry 类似，但针对降低线路深度进行了优化。接受相同的数据格式。
签名
python
efficient_sparse(qubits: list[int], data: dict[str, float]) -> None
efficient_sparse(qubits: list[int], data: dict[str, complex]) -> None
efficient_sparse(qubits: list[int], data: list[float]) -> None
efficient_sparse(qubits: list[int], data: list[complex]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | dict[str, float]、dict[str, complex]、list[float] 或 list[complex] | 与 sparse_isometry 相同格式的稀疏态数据。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
ds_quantum_state_preparation
使用双稀疏态制备制备量子态。接受多种格式的数据。
签名
python
ds_quantum_state_preparation(qubits: list[int], data: dict[str, float]) -> None
ds_quantum_state_preparation(qubits: list[int], data: dict[str, complex]) -> None
ds_quantum_state_preparation(qubits: list[int], data: list[float]) -> None
ds_quantum_state_preparation(qubits: list[int], data: list[complex]) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | dict[str, float]、dict[str, complex]、list[float] 或 list[complex] | 制备的态参数。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
approx_mps_encode
使用近似矩阵积态（MPS, Matrix Product State）编码对数据进行编码。MPS 编码使用通过迭代扫描优化的低秩近似。
签名
python
approx_mps_encode(qubits: list[int], data: list[float], layers: int = 3, sweeps: int = 100, double2float: bool = False) -> None
approx_mps_encode(qubits: list[int], data: list[complex], layers: int = 3, sweeps: int = 100) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 要编码的量子比特索引。 |
| data | list[float] 或 list[complex] | 要编码的经典输入数据。 |
| layers | int | 编码层数。默认为 3。 |
| sweeps | int | 优化扫描次数。默认为 100。 |
| double2float | bool | 编码前将 double 数据转换为 float。默认为 False。仅适用于 list[float] 重载。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
topology_aware_mps_encode
拓扑感知 MPS 振幅编码。使用拓扑保持的 MPS 近似制备量子态。仅在拓扑边列表指定的物理连接量子比特对之间生成双量子比特门，实现零 SWAP 开销。
签名
python
topology_aware_mps_encode(qubits: list[int], data: list[float], topology: list[list[int]], depth: int = 3) -> None
topology_aware_mps_encode(qubits: list[int], data: list[complex], topology: list[list[int]], depth: int = 3) -> None参数
| 参数 | 类型 | 说明 |
|---|---|---|
| qubits | list[int] | 可用于编码的量子比特。 |
| data | list[float] 或 list[complex] | 目标振幅矢量。必须已归一化，长度须为 2 的幂且 >= 16。 |
| topology | list[list[int]] | 芯片拓扑边列表。每个元素为 [qubit_a, qubit_b]，表示物理耦合（例如 4 比特线性链为 [[0, 1], [1, 2], [2, 3]]）。 |
| depth | int | 解纠缠遍数。深度越大保真度越高。默认为 3。 |
返回
无。线路存储在内部，可通过 get_circuit() 获取。
异常
RuntimeError：当 data 未归一化、长度不是 2 的幂、长度 < 16，或拓扑图不连通时抛出。
示例
python
from pyqpanda3.core import Encode
data = [0.25] * 16
topology = [[0, 1], [1, 2], [2, 3]]
encoder = Encode()
encoder.topology_aware_mps_encode([0, 1, 2, 3], data, topology, depth=3)
print(type(encoder.get_circuit()).__name__)
print(round(encoder.get_fidelity(data), 6))预期输出：
text
QCircuit
1.0工具方法
Encode.get_circuit
获取最近一次编码调用生成的量子线路。
签名
python
Encode.get_circuit() -> QCircuit返回
编码方法产生的 QCircuit。
Encode.get_out_qubits
获取编码过程的输出量子比特。
签名
python
Encode.get_out_qubits() -> list[int]返回
表示编码输出的量子比特索引列表。
Encode.get_fidelity
计算编码量子态与输入数据描述的目标态之间的保真度。
签名
python
Encode.get_fidelity(data: list[float]) -> float
Encode.get_fidelity(data: list[complex]) -> float参数
| 参数 | 类型 | 说明 |
|---|---|---|
| data | list[float] 或 list[complex] | 用于保真度计算的输入数据。 |
返回
计算得到的保真度值，表示编码态与目标态的接近程度。