算法与工具库

概述

本章介绍 unitarylab.library 中的高层算法模块，按功能分组说明各模块的用途、适用场景和基本用法。读完本章，你将能够：

了解算法库中各模块的功能分类
知道在常见量子计算任务中应使用哪个模块
使用 QFT、QPE、LCU、哈密顿量模拟、HHL 等高层接口构建量子线路

这些模块都在 Circuit 之上提供算法级抽象，通常不需要手动编写门序列。

模块功能分组

功能分组	模块	主要接口
基础算法原语	`_qft`、`_qpe`、`_lcu`	`QFT`、`QPE`、`LCU`
哈密顿量模拟	`hamiltonian.method.*`	Trotter、QDrift、QSP、Taylor、Cartan
量子信号处理	`_qsp`、`_qsvt`	`QSP`、`QSVTHermitian`
块编码	`block_encoding.*`	`block_encode`、FABLE、Nagy
线性方程组求解	`linear_solver.*`	HHL、QSVT、Schrödingerization
Pauli 工具	`pauli_operator.*`	`pauli_string_decomposition`
PDE 求解框架	`equation.*`	方程解析器、Schrödingerization、内置示例

基础算法原语

QFT / IQFT：量子傅里叶变换

用途： 构建量子傅里叶变换或其逆变换线路，是 QPE、Shor 算法等的基础模块。


from unitarylab.library._qft import QFT, IQFT
 
# 构建 4 量子比特 QFT 线路
qft_circuit = QFT(n=4)
 
# 构建逆 QFT 线路
iqft_circuit = IQFT(n=4)
 
# 可以嵌入到更大的线路中
qc = Circuit(4)
qc.append(qft_circuit, target=[0, 1, 2, 3])
qc.draw()

函数	参数	返回
`QFT(n)`	`n`：量子比特数	`Circuit`
`IQFT(n)`	`n`：量子比特数	`Circuit`（QFT 的共轭转置）

QPE：量子相位估计

用途： 估计酉算子 $U$ 的本征值相位 $θ$ ，满足 $U ∣ ψ ⟩ = e^{2 π i θ} ∣ ψ ⟩$ 。常用于量子化学和量子算法中估计哈密顿量本征能。


from unitarylab.library._qpe import QPE
from unitarylab.core import Circuit
 
# 被估计的酉算子（T 门，相位为 1/8）
U = Circuit(1)
U.t(0)
 
# 运行 QPE，使用 4 个相位寄存器比特
results = QPE(
    U=U,
    d=4,                  # 相位寄存器比特数，精度 1/2^d
    prepare_target=None,  # 本征态准备线路（None 表示 |0⟩）
    device='cpu',
    return_circuit=False  # 若为 True，同时返回 QPE 线路
)
print(results)
# 包含相位估计结果的字典，估计值接近 0.125（= 1/8）

参数	说明
`U`	被估计的酉算子线路
`d`	相位寄存器比特数，估计精度为 $1/ 2^{d}$
`prepare_target`	本征态准备线路，默认 `None`（从 $∥0 ⟩$ 出发）
`return_circuit`	是否同时返回构造的 QPE 线路

LCU：线性组合酉演算

用途： 实现算子 $A = \sum_{j} α_{j} U_{j}$ ，常用于哈密顿量模拟和块编码的基础构件。


from unitarylab.library._lcu import LCU
from unitarylab.core import Circuit
 
# 构建两个酉算子子线路
U1 = Circuit(1)
U1.x(0)
U2 = Circuit(1)
U2.z(0)
 
# LCU：实现 0.6 * U1 + 0.8 * U2
lcu_circuit = LCU([(U1, 0.6), (U2, 0.8)])

注意： 所有输入酉算子线路必须具有相同的量子比特数。系数须为正有限浮点数。

哈密顿量模拟

哈密顿量模拟模块提供多种方法近似 $e^{- i H t}$ ，适用于量子化学、凝聚态物理等场景。

方法对比

方法	适用场景	说明
Trotter	通用，Pauli 串形式	Trotter-Suzuki 分解，精度可控
QDrift	通用，随机化方法	随机 Trotter 步，门数较少
QSP	高精度需求	基于量子信号处理，精度更高但线路更深
Taylor	解析展开	Taylor 级数近似，适合短时演化
Cartan	少数量子比特精确模拟	Cartan 分解，精确无近似误差

Trotter 示例


import numpy as np
from unitarylab.library.hamiltonian.method.trotter.algorithm import Trotter
 
 
# 1. 定义哈密顿量矩阵
# 示例：单量子比特 Pauli-X 哈密顿量
H = np.array([
    [0, 1],
    [1, 0],
], dtype=complex)
 
# 2. 创建 Trotter-Suzuki 哈密顿量模拟对象
sim = Trotter(
    H=H,
    t=1.0,              # 总演化时间
    target_error=1e-3,  # 目标误差
    order=1,            # Trotter 阶数；可为 1 或偶数
    steps=100,          # 最大 Trotter 步数
    device="cpu",
)
 
# 3. 获取演化线路
circuit = sim.circuit
 
# 4. 查看近似演化矩阵
evolution = sim.evolution_result
 
# 5. 查看总误差
print(sim.total_error)
 
# 6. 绘制线路
circuit.draw(title="Trotter Hamiltonian Simulation")

Cartan 分解

适合 1-2 量子比特的精确哈密顿量演化，无近似误差：


import numpy as np
from unitarylab.library.hamiltonian.method.cartan.algorithm import CartanOptimization
 
 
# 1. 定义实对称哈密顿量
H = np.array([
    [1.0, 0.5],
    [0.5, -1.0],
], dtype=float)
 
# 2. 创建 Cartan 分解哈密顿量模拟对象
sim = CartanOptimization(
    H=H,
    t=1.0,              # 总演化时间
    target_error=1e-3,  # 优化停止误差
    lr=1e-3,            # 学习率
    max_steps=10000,    # 最大优化步数
    optimizer="SD",     # 可选：'SD'、'BB'、'BFGS'
    device="cpu",
)
 
# 3. 获取量子线路
circuit = sim.circuit
 
# 4. 获取近似演化矩阵
evolution = sim._evolution_result
 
# 5. 绘制线路
circuit.draw(title="Cartan Hamiltonian Simulation")

量子信号处理（QSP）与量子奇异值变换（QSVT）

这两个模块提供基于多项式变换的量子算法框架，精度更高但线路深度更大，适合对精度要求高的场景。

QSP

用途： 对酉算子实现多项式变换，是实现哈密顿量模拟、矩阵函数等的通用框架。


 
from unitarylab.core import Circuit
from unitarylab.library._qsp.algorithm import QSP_hamiltonian_simulation
 
 
# 1. 构造一个最小块编码线路 U_H
# 这里使用 1 个系统量子比特 + 1 个辅助量子比特
# 系统量子比特 q0 上施加 Z 门，可视为一个简单的 Pauli-Z 哈密顿量块编码示例
n = 1      # 系统寄存器量子比特数
m = 1      # 块编码辅助量子比特数
 
U_H = Circuit(n + m, name="Block Encoding of Z")
U_H.z(0)
 
# 2. 基于 QSP 构造哈密顿量模拟线路
circuit, factor, n_ancilla, n_qubits, degree = QSP_hamiltonian_simulation(
    U_H=U_H,
    n=n,
    alpha=1.0,       # 块编码归一化系数
    m=m,
    t=1.0,           # 演化时间
    epsilon=1e-3,    # 目标近似误差
    beta=0.5,        # 必须满足 0 < beta < 1
    flag=True,       # True 表示近似 exp(-iHt)
)
 
# 3. 查看返回结果
print("factor:", factor)
print("n_ancilla:", n_ancilla)
print("n_qubits:", n_qubits)
print("degree:", degree)
 
# 4. 查看线路信息
print("circuit qubits:", circuit.get_num_qubits())
 
# 5. 绘制线路
circuit.draw(title="QSP Hamiltonian Simulation")

QSVT（量子奇异值变换）

用途： 对矩阵实现任意多项式函数变换，适用于哈密顿量模拟、线性系统求解等。


import numpy as np
from unitarylab.library._qsvt.algorithm import QSVTHermitian
 
 
# 1. 定义目标厄米矩阵
hamiltonian_matrix = np.array([
    [0.8, 0.0],
    [0.0, 0.4],
], dtype=complex)
 
# 2. 定义目标标量函数
# 示例：f(x) = exp(-i x)
target_function = lambda x: np.exp(-1j * x)
 
# 3. 构造 QSVT Hermitian 对象
qsvt = QSVTHermitian(
    H=hamiltonian_matrix,
    function=target_function,
    target_error=1e-6,
    block_encoding_method="nagy",  # 可选："nagy" 或 "fable"
    device="cpu",
)
 
# 4. 获取完整量子线路
circuit = qsvt.circuit
 
# 5. 获取实际近似误差
error = qsvt.total_error
 
# 6. 获取近似矩阵结果
evolution = qsvt.evolution_result
 
print("degree:", qsvt.degree)
print("alpha:", qsvt.alpha)
print("m:", qsvt.m)
print("total_error:", error)
print("evolution_result:")
print(evolution)
 
# 7. 绘制线路
circuit.draw(title="QSVT Hermitian Approximation")

块编码

用途： 将非酉矩阵 $A$ 嵌入酉矩阵的左上角子块，是 QSVT、LCU 等算法的基础。


from unitarylab.library.block_encoding.block_encoder import block_encode
import numpy as np
 
# 对任意矩阵进行块编码
A = np.array([[0.5, 0.1], [0.2, 0.3]], dtype=complex)
result = block_encode(A, method='nagy')

子模块	方法	说明
`block_encoder`	`block_encode(matrix, method)`	通用接口，支持多种方法
`fable`	FABLE 算法	基于近似二进制振幅编码
`nagy`	Nagy 算法	基于奇异值分解的精确块编码

线性方程组求解

这些模块实现量子线性方程组算法，求解 $A x = b$ 形式的线性系统。

算法	模块	适用场景
HHL	`linear_solver.hhl`	稀疏、条件数小的线性系统，理论加速最经典
QSVT	`linear_solver.qsvt`	高精度求解，依赖块编码
Schrödingerization	`linear_solver.schro`	将线性系统转化为哈密顿量演化求解


from unitarylab.library.linear_solver.hhl import HHLSolver
import numpy as np
 
A = np.array([[2, 1], [1, 3]], dtype=complex)
b = np.array([1, 0], dtype=complex)
 
result = HHLSolver(A=A, b=b)

Pauli 工具

用途： 将任意矩阵分解为 Pauli 算符的线性组合，是哈密顿量模拟的预处理步骤。


from unitarylab.library.pauli_operator.pauli_string_decomposition import pauli_string_decomposition
import numpy as np
 
# 将 2x2 矩阵分解为 Pauli 串
H = np.array([[1, 0.5], [0.5, -1]], dtype=complex)
coefficients = pauli_string_decomposition(H)
print(coefficients)
# {'I': 0.0, 'X': 0.5, 'Y': 0.0, 'Z': 1.0}
# 表示 H = 0.5 * X + 1.0 * Z

PDE 求解框架

unitarylab.library.equation 提供一套完整的量子偏微分方程（PDE）求解框架，包含方程解析、微分算子构造和内置方程示例。

子模块结构


equation/
├── differential_operator/    # 微分算子构造（有限差分、块编码）
├── equation_parser/          # 方程解析器（边界条件、离散化、求解器）
├── examples/                 # 内置方程示例
└── schrodingerization/       # Schrödingerization 变换（时间演化）

内置方程示例

这些示例展示了如何用量子算法求解标准 PDE，可以直接运行：

示例	说明	维度
`equation_heat`	热方程 $\partial_{t} u = Δ u$	1D
`equation_heat2d`	热方程	2D
`equation_advection`	对流方程 $\partial_{t} u + v \nabla u = 0$	1D
`equation_burgers`	Burgers 方程	1D
`equation_burgers2d`	Burgers 方程	2D
`equation_maxwell`	Maxwell 电磁方程	1D/3D
`equation_Helmholtz`	Helmholtz 方程	1D
`equation_blackScholes`	Black-Scholes 金融方程	1D
`equation_elasticWave`	弹性波方程	1D/2D
`equation_OUprocess`	Ornstein-Uhlenbeck 随机过程	1D


from unitarylab.library.equation.examples.equation_heat.algorithm import HeatEquation
 
solver = HeatEquation(n_qubits=4, t=0.1, steps=5)
result = solver.run()