Skip to Content
文档UnitaryLab 算法用户手册态制备算法

态制备算法

概述

unitarylab_algorithms.state_preparation 包提供 5 种将任意（或有特定结构的）经典向量 编码为量子态振幅的线路构造方法。5 个子模块分别位于 mottonen/、multiplexer/、mps/、pauli/、Superposition/（注意最后一个目录名首字母大写）。

算法类方法思路
MöttönenMottonenAlgorithm振幅（RY）/相位（RZ）分离的均匀受控旋转递归分解
MultiplexerMultiplexerAlgorithm概率二叉树多路复用 RY 旋转 + 对角相位门
MPSMPSAlgorithm基于矩阵乘积态（MPS）的顺序 SVD 分解 + QR 酉补全
PauliPauliAlgorithm固定 Pauli 字拟设 + L-BFGS-B 数值优化（唯一非精确解析方法）
SuperpositionSuperpositionAlgorithm稀疏支撑集系数编码 + 置换线路，利用非零振幅个数

5 个算法使用统一的返回结构，包含 status、circuit_path、plot、circuit 和算法专属结果；其中 plot 指向保存的 .txt 结果报告。Pauli 方法因数值优化开销较高，界面最多支持 6 个目标比特；其余方法最多支持 8 个。MPS 的高级结构参数仅能通过 Python API 配置。

Möttönen 状态制备

背景

实现 Möttönen 等人提出的态制备算法：将振幅（RY）与相位（RZ）的合成分离，递归计算均匀受控旋转（uniformly controlled rotation）角度，再将每个均匀受控旋转沿格雷码（Gray code）阶梯分解为单比特旋转与 CNOT 的交替序列（ 顺序）。若目标态全实（所有相位 ~0，容差 1e-15），则完全跳过 RZ 均匀受控旋转阶段。

导入

from unitarylab_algorithms import MottonenAlgorithm

.run() 参数

def run(self, Psi, target_qubits: int, target_error: float = 1e-6,
        backend='torch', device='cpu', dtype=np.complex128) -> Dict[str, Any]
参数类型默认值说明
Psilist / np.ndarray必填目标态振幅向量
target_qubitsint必填（UI 默认 2，max 8, min 1）目标量子比特数
target_errorfloat1e-6目标保真度误差阈值；实际生效阈值为 max(target_error, 1e-10)
backend/device/dtype—'torch'/'cpu'/np.complex128保留参数，当前版本使用默认执行配置

返回值

{
    "status": "ok",
    "circuit_path": "<mottonen_state_preparation_algorithm_circuit.svg 路径>",
    "plot": [{"format": "txt", "filename": "<mottonen_state_preparation_algorithm_result.txt>"}],
    "circuit": <Circuit 对象>,
    "Prepared state": ...,
    "Total error": ...,
    "Computation time (s)": ...,
}

示例

from unitarylab_algorithms import MottonenAlgorithm
 
algo = MottonenAlgorithm()
result = algo.run(Psi=[1, 0, 0, 1], target_qubits=2, target_error=1e-6)
print(result['status'], result['Total error'])

快速演示

from unitarylab_algorithms.state_preparation.mottonen.algorithm import test
test(Psi=[1, 0, 0, 1], target_qubits=2, target_error=1e-6)

注意事项

  • Psi 未指定时 test() 默认使用 Bell 态 [1, 0, 0, 1]/√2。
  • 内部通过 @dataclass(slots=True) class StatePreparationResult 与嵌套 class Mottonen(StatePreparationResult) 完成实际计算，run() 只是薄封装。

Multiplexer 状态制备

背景

实现多路复用/均匀受控 RY 旋转态制备：以概率二叉树的方式递归分裂振幅（每个节点发出一个可能带多控制的 RY 旋转，，将概率质量路由到左右子树），随后附加一个对角相位阶段（对每个非零相位的基态选择性施加 P/CP/MCP 门）。

导入

from unitarylab_algorithms import MultiplexerAlgorithm

.run() 参数

def run(self, Psi, target_qubits: int, target_error: float = 1e-6,
        backend='torch', device='cpu', dtype=np.complex128) -> Dict[str, Any]
参数类型默认值说明
Psilist / np.ndarray必填目标态振幅向量
target_qubitsint必填（UI 默认 2，max 8, min 1）目标量子比特数
target_errorfloat1e-6与 Möttönen 相同的误差阈值与下限规则
backend/device/dtype—'torch'/'cpu'/np.complex128保留参数，当前版本使用默认执行配置

返回值

{
    "status": "ok",
    "circuit_path": "<multiplexer_state_preparation_algorithm_circuit.svg 路径>",
    "plot": [{"format": "txt", "filename": "<multiplexer_state_preparation_algorithm_result.txt>"}],
    "circuit": <Circuit 对象>,
    "Prepared state": ...,
    "Total error": ...,
    "Computation time (s)": ...,
}

示例

from unitarylab_algorithms import MultiplexerAlgorithm
 
algo = MultiplexerAlgorithm()
result = algo.run(Psi=[1, 1j, 0, 1], target_qubits=2, target_error=1e-6)
print(result['status'], result['Total error'])

快速演示

from unitarylab_algorithms.state_preparation.multiplexer.algorithm import test
test(Psi=[1, 1j, 0, 1], target_qubits=2, target_error=1e-6)

注意事项

  • Psi 未指定时 test() 默认使用归一化后的 [1, 1j, 0, 1]。
  • 退化子树（left_norm + right_norm <= 1e-15）时 theta 直接取 0.0，避免除零。

MPS 状态制备

背景

实现基于矩阵乘积态（MPS）的量子态制备：目标态先（可自动）通过顺序 SVD 分解为 MPS（参考 arXiv:2310.18410），每个 MPS 张量作为等距映射通过 QR 分解补全为完整酉矩阵（Eq. 23），这些酉矩阵依次作用在一个系统比特与一组共享的辅助”work”比特（编码键指标）上，最终系统态从 work 比特全零子空间中提取。

导入

from unitarylab_algorithms import MPSAlgorithm

.run() 参数

def run(self, Psi, target_qubits: int, target_error: float = 1e-6,
        mps: Optional[list[np.ndarray]] = None,
        work_wires: Optional[list[int]] = None,
        right_canonicalize: bool = False,
        mps_max_bond_dim: Optional[int] = None,
        rng_seed: int = 42,
        backend='torch', device='cpu', dtype=np.complex128) -> Dict[str, Any]
参数类型默认值说明
Psilist / np.ndarray必填目标态振幅向量
target_qubitsint必填（UI 默认 2，max 8, min 1）目标量子比特数
target_errorfloat代码默认 1e-6（parameters.json 声明为 1e-9，二者不一致）目标误差阈值
mpslist[np.ndarray] | NoneNone可选：直接传入已构造好的 MPS 张量列表；为 None 时从 Psi 自动构造
work_wireslist[int] | NoneNone可选：辅助 work 比特索引；为 None 时自动推导
right_canonicalizeboolFalse是否右正则化；当 mps=None（自动从 Psi 构造）时会被静默覆盖为 False，用户传入值被忽略（因为自动构造的 MPS 已保证右正则）
mps_max_bond_dimint | NoneNone可选：限制最大键维数
rng_seedint42内部随机数种子
backend/device/dtype—'torch'/'cpu'/np.complex128保留参数，当前版本使用默认执行配置

mps、work_wires、right_canonicalize、mps_max_bond_dim、rng_seed 均未出现在 parameters.json 中，网页端参数面板只能配置 Psi/target_qubits/target_error，这 5 个参数只能通过直接 Python 调用使用。

返回值

{
    "status": "ok",
    "circuit_path": "<mps_state_preparation_algorithm_circuit.svg 路径>",
    "plot": [{"format": "txt", "filename": "<mps_state_preparation_algorithm_result.txt>"}],
    "circuit": <Circuit 对象>,
    "Prepared state": ...,
    "Total error": ...,
    "Work leakage": ...,
    "MPS tensors": ...,
    "Computation time (s)": ...,
}

示例

from unitarylab_algorithms import MPSAlgorithm
 
algo = MPSAlgorithm()
result = algo.run(Psi=[1, 0, 0, 1], target_qubits=2, target_error=1e-6)
print(result['status'], result['Work leakage'], result['MPS tensors'])

快速演示

from unitarylab_algorithms.state_preparation.mps.algorithm import test
test(Psi=[1, 0, 0, 1], target_qubits=2, target_error=1e-6)

注意事项

  • target_qubits == 0 时走特殊快速路径，直接返回平凡的 0 比特线路与单位矩阵，跳过整个分解流程。
  • 是 5 个算法中唯一暴露 MPS 内部结构的一个（unitaries、mps、work_leakage、full_evolution_result 等只读属性），但这些属性本身不直接出现在 .run() 返回字典中，除非通过 self.output 合并的字段间接体现。

Pauli 状态制备

背景

实现变分 Pauli 旋转（“Pauli 字”）态制备拟设，显式模仿 PennyLane 的 ArbitraryStatePreparation 模板：一个固定的、递归生成的有序 Pauli 字符串列表（长度 ）中每个 Pauli 字对应一个可训练旋转角； 旋转块序列作用于 ，通过 L-BFGS-B（解析参数漂移梯度、多起点重启）优化以最大化与目标态的保真度。是 5 个算法中唯一非精确解析、依赖数值优化的方法，不保证对每个目标态都能达到 target_error（README 中明确说明此局限）。

导入

from unitarylab_algorithms import PauliAlgorithm

.run() 参数

def run(self, Psi, target_qubits: int, target_error: float = 1e-6,
        backend='torch', device='cpu', dtype=np.complex128) -> Dict[str, Any]
参数类型默认值说明
Psilist / np.ndarray必填目标态振幅向量
target_qubitsint必填（UI 默认 2，max 6，min 1——上限低于其余 4 个算法的 8）目标量子比特数
target_errorfloat1e-6目标误差阈值；由于是数值优化，不保证一定能达到
backend/device/dtype—'torch'/'cpu'/np.complex128保留参数，当前版本使用默认执行配置

返回值

{
    "status": "ok",
    "circuit_path": "<pauli_state_preparation_algorithm_circuit.svg 路径>",
    "plot": [{"format": "txt", "filename": "<pauli_state_preparation_algorithm_result.txt>"}],
    "circuit": <Circuit 对象>,
    "Prepared state": ...,
    "Total error": ...,
    "Pauli words": ...,
    "Weights": ...,
    "Computation time (s)": ...,
}

示例

from unitarylab_algorithms import PauliAlgorithm
 
algo = PauliAlgorithm()
result = algo.run(Psi=[1, 1j], target_qubits=1, target_error=1e-6)
print(result['status'], result['Total error'], result['Pauli words'])

快速演示

from unitarylab_algorithms.state_preparation.pauli.algorithm import test
test(Psi=[1, 1j], target_qubits=1, target_error=1e-6)

注意事项

  • test() 默认 target_qubits=1（其余 4 个算法的 test() 默认为 2，Superposition 默认为 3），且与 parameters.json 的 UI 默认值 2 不一致，属于示例性默认值差异，非 .run() 签名本身的默认值。
  • 多起点优化最多重启 4 次（_MAX_OPTIMIZATION_RESTARTS = 4，固定种子 np.random.default_rng(7)），每次最多 800 次迭代（_MAX_OPTIMIZATION_ITERATIONS = 800）；一旦某次重启已达到 target_error，会提前跳出重启循环，因此不保证真正运行满 4 次重启。
  • 依赖外部模块 unitarylab.library.pauli_operator.pauli_string_decomposition，并使用 functools.lru_cache 缓存不同比特数下的稠密 Pauli 矩阵（进程生命周期内不清除）。

Superposition 状态制备

背景

实现稀疏支撑集”叠加态”制备方法（代码注释称其”启发于 PennyLane Superposition 模板的高层思路”，但为独立重写）：对于仅有 个非零振幅的目标态，先在尽可能小的寄存器上通过 QR 补全构造一个紧凑的 项系数态，再施加一个显式的置换线路（借助 1 个 work 比特的”标记—CNOT—取消标记”模式），将这些紧凑索引映射到真实（任意分布）的稀疏支撑基态上，从而避免通用稠密态合成的开销。

导入

from unitarylab_algorithms import SuperpositionAlgorithm

导入路径中的 Superposition 目录名首字母大写，与其余 4 个全小写的目录名（mottonen/multiplexer/mps/pauli）不一致，书写时需注意大小写。

.run() 参数

def run(self, Psi, target_qubits: int, target_error: float = 1e-6,
        backend='torch', device='cpu', dtype=np.complex128) -> Dict[str, Any]
参数类型默认值说明
Psilist / np.ndarray必填目标态振幅向量（可稀疏）
target_qubitsint必填（UI 默认 2，max 8, min 1）目标量子比特数
target_errorfloat代码默认 1e-6（parameters.json 声明为 1e-9，二者不一致，与 MPS 相同的问题模式）目标误差阈值
backend/device/dtype—'torch'/'cpu'/np.complex128保留参数，当前版本使用默认执行配置

返回值

{
    "status": "ok",
    "circuit_path": "<superposition_state_preparation_algorithm_circuit.svg 路径>",
    "plot": [{"format": "txt", "filename": "<superposition_state_preparation_algorithm_result.txt>"}],
    "circuit": <Circuit 对象>,
    "Prepared state": ...,
    "Total error": ...,
    "Support size": ...,
    "Index register qubits": ...,
    "Computation time (s)": ...,
}

示例

import numpy as np
from unitarylab_algorithms import SuperpositionAlgorithm
 
algo = SuperpositionAlgorithm()
Psi = np.ones(8, dtype=complex) / np.sqrt(8)
result = algo.run(Psi=Psi, target_qubits=3, target_error=1e-6)
print(result['status'], result['Support size'], result['Index register qubits'])

快速演示

from unitarylab_algorithms.state_preparation.Superposition.algorithm import test
test(target_qubits=3, Psi=None, target_error=1e-6)

注意事项

  • test() 默认使用 3 比特稀疏态（索引 1 与 6 处振幅非零，Psi[1]=1/√2、Psi[6]=1j/√2）。
  • 内部 _build_coefficient_stage_matrix 中有 del target_error 语句并附注释说明”QR 补全是精确的”——即该内部辅助函数虽然接受 target_error，但并不实际使用它（total_error 仍会在下游从最终线路与目标态的比较中计算得出，不受此影响）。
  • register_qubits == 0（支撑集大小 ≤ 1）时，系数阶段矩阵直接返回单位矩阵，跳过 QR 补全。
  • 需要 1 个额外的 work 比特（默认 work_wire = target_qubits），线路总宽度为 max(target_qubits, work_wire + 1)。

通用注意事项

  • 5 个算法的 .run() 均要求显式传入 Psi 与 target_qubits（无默认值），仅 target_error 等其余参数有默认值；直接调用 Algorithm().run() 不带参数会报错，务必参考各算法示例。
  • 5 个算法共享同一套“均匀受控旋转 / MPS / Pauli 拟设 / 稀疏叠加”思路谱系，覆盖了从通用稠密态（Möttönen、Multiplexer）、结构化低纠缠态（MPS）、变分近似（Pauli）到稀疏态（Superposition）等不同应用场景，选择时应根据目标态的稀疏性、纠缠结构与对精确度的要求决定。
  • 所有算法的 is_success 判据均为 total_error <= max(target_error, 1e-10)，target_error 传入过小的值不会进一步提高判据精度。
  • backend/device/dtype 为兼容性保留参数，当前版本使用默认执行配置。
最后更新于
量子机器学习薛定谔化方法