算法与工具库

from unitarylab.library import (
    QFT, IQFT,                      # 量子傅里叶变换 / 逆变换
    QPE,                             # 量子相位估计
    LCU,                             # 酉算子线性组合
    block_encode,                    # 块编码统一入口
    hamiltonian_simulation,          # 哈密顿量模拟统一入口
    solve,                           # 线性方程组求解统一入口
    QSVT,                            # 量子奇异值变换（标量函数变换）
    QSP, QSP_hamiltonian_simulation, # 量子信号处理
)

from unitarylab import Circuit
from unitarylab.library 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()

from unitarylab import Circuit
from unitarylab.library import QPE
 
# 被估计的酉算子（T 门，相位为 1/8）
U = Circuit(1)
U.t(0)
 
# T|1⟩ = exp(2πi/8)|1⟩，因此先制备本征态 |1⟩
prepare_target = Circuit(1)
prepare_target.x(0)
 
# 运行 QPE，返回 (线路, 相位估计值, 该结果的概率)
qpe_circuit, phase, probability = QPE(
    U=U,
    d=4,                  # 相位寄存器比特数，精度 1/2^d
    prepare_target=prepare_target,
    device='cpu',
    return_circuit=False
)
print(phase, probability)  # 0.125 1.0（允许数值舍入误差）

from unitarylab import Circuit
from unitarylab.library import LCU
 
# 构建两个酉算子子线路
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)])

import numpy as np
from unitarylab.library import hamiltonian_simulation
 
H = np.array([[0, 1], [1, 0]], dtype=float)  # 实对称 Pauli-X 哈密顿量
 
sim = hamiltonian_simulation(
    H, t=1.0,
    method='trotter',       # 'trotter'（默认）/ 'qdrift' / 'taylor' / 'qsp'（别名 'qsvt'）/
                             # 'cartan-lax' / 'cartan-optimization'
    target_error=1e-3,
    backend='torch', device='cpu', dtype=np.complex128,
    order=1, steps=100,      # method 专属参数，通过 **kwargs 传递（此处对应 'trotter'）
)
 
circuit = sim.circuit               # 演化线路
evolution = sim.evolution_result    # 近似演化矩阵（懒计算，首次访问时构建）
print(sim.total_error)              # 实际近似误差
circuit.draw(title="Hamiltonian Simulation")

import numpy as np
from unitarylab.library.hamiltonian.method import Trotter, CartanOptimization
 
H = np.array([[0, 1], [1, 0]], dtype=float)
 
# 等价于 hamiltonian_simulation(H, t=1.0, method='trotter', order=1, steps=100)
sim = Trotter(H=H, t=1.0, target_error=1e-3, order=1, steps=100, device="cpu")
circuit = sim.circuit
evolution = sim.evolution_result   # 注意：公开属性名为 evolution_result，不带下划线前缀
print(sim.total_error)

# Cartan 分解：适合 1-2 量子比特的精确哈密顿量演化，误差随优化收敛
H = np.array([[1.0, 0.5], [0.5, -1.0]], dtype=float)  # 须为实对称矩阵
 
sim = CartanOptimization(
    H=H, t=1.0, target_error=1e-3,
    lr=1e-3, max_steps=10000, optimizer="SD",  # 可选：'SD'、'BB'、'BFGS'
    device="cpu",
)
circuit = sim.circuit
evolution = sim.evolution_result  # 公开属性，不是 sim._evolution_result
circuit.draw(title="Cartan Hamiltonian Simulation")

from unitarylab import Circuit
from unitarylab.library 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)
)
 
print("factor:", factor)
print("n_ancilla:", n_ancilla)
print("n_qubits:", n_qubits)
print("degree:", degree)
print("circuit qubits:", circuit.get_num_qubits())
 
circuit.draw(title="QSP Hamiltonian Simulation")

import numpy as np
from unitarylab.library import QSVT
 
# 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 = QSVT(
    hamiltonian_matrix,
    function=target_function,
    target_error=1e-6,
    block_encoding_method="nagy",  # 可选："nagy" 或 "fable"
    device="cpu",
)
 
circuit = qsvt.circuit
error = qsvt.total_error
evolution = qsvt.evolution_result
 
print("degree:", qsvt.degree)
print("alpha:", qsvt.alpha)
print("m:", qsvt.m)
print("total_error:", error)
 
circuit.draw(title="QSVT Hermitian Approximation")

from unitarylab.library 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', eps=1e-3, verbose=False)
 
circuit = result.circuit          # 块编码线路
alpha = result.alpha              # 归一化系数
total_qubits = result.total_qubits
target_qubits = result.target_qubits

from unitarylab.library import solve
import numpy as np
 
A = np.array([[2, 1], [1, 3]], dtype=float)
b = np.array([1, 0], dtype=float)
 
hhl_result = solve(A, b)                       # 默认 method='hhl'
hhl_precise = solve(A, b, method='hhl', d=10) # HHL，10 个相位寄存器比特
qsvt_result = solve(A, b, method='qsvt')       # QSVT-based 求解器
vqls_result = solve(A, b, method='vqls')       # 变分量子线性求解器
 
print(hhl_result.solution)   # 近似解向量 x
print(hhl_result.circuit)    # 构造的量子线路（可能为 None）

result = solve(A, b, method='hhl', precondition='diagonal')
print(result.precondition_mode)   # 预处理元数据

from unitarylab.library.linear_solver import HHLSolver
import numpy as np
 
A = np.array([[2, 1], [1, 3]], dtype=float)
b = np.array([1, 0], dtype=float)
 
# 注意：HHLSolver 返回的是元组 (circuit, solution, scaling_factor)，不是对象
circuit, solution, scale = HHLSolver(A, b, d=6)
print(solution)

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)
terms = pauli_string_decomposition(H)
print(terms)
# 应包含 Z: 1 和 X: 0.5；返回顺序不保证，幅度小于 1e-10 的项会被自动丢弃

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

from unitarylab.library.equation.examples.equation_heat import HeatEquationAlgorithm
 
solver = HeatEquationAlgorithm()
result = solver.run()   # params=None 时自动读取 equation_heat/setup.json 中的默认配置