UnitaryLab 算法用户手册

概述

本手册面向希望使用 UnitaryLab 算法库（unitarylab_algorithms/）运行量子算法的开发者和研究人员。密码学、基础算法、哈密顿量模拟、线性代数、量子机器学习和态制备算法共享 unitarylab_algorithms.algo_base.BaseAlgorithm 接口，提供统一的执行、日志记录和结果导出流程；schrodingerization 使用与之无继承关系的独立 schrodingerization.base.BaseAlgorithm 接口，其参数和返回结构有所不同。

使用算法库，你可以：

通过一次 .run() 调用运行 Shor、Grover、QFT、HHL、VQE、QAOA 等知名量子算法
自动保存量子线路图以及算法生成的结果文件；具体格式可能是 TXT、SVG 或 NPY，取决于算法实现
使用预配置的 .test() 示例函数快速探索算法行为
基于提供的模板实现自定义算法

安装与版本

算法库随 UnitaryLab 一同发布，安装完整功能需要同时安装核心包和算法子包：


pip install unitarylab
pip install unitarylab-Algorithms

安装完成后，可通过以下方式确认版本：


import unitarylab_algorithms
print(unitarylab_algorithms.__version__)

阅读路径

场景	建议阅读
第一次使用，快速上手	快速开始
了解模块全貌与 API 入口	API 使用总览
Shor、Simon、离散对数算法	密码学算法
Grover、QPE、振幅放大/估计、Hadamard	基础量子算法
Trotter、QDrift、Taylor、QSP、Cartan	哈密顿量模拟
QFT、HHL、LCU、QSP、QSVT、VQLS、AQC	线性代数算法
VQE、VQC、QAOA、QCBM、CVQNN、Fermi-Hubbard VQE	量子机器学习
Möttönen、Multiplexer、MPS、Pauli 等态制备方法	态制备算法
热方程、对流方程求解器	薛定谔化方法
编写新算法	算法模板指南

模块结构概览


unitarylab_algorithms/
├── algo_base.py                          # BaseAlgorithm 共享基类
├── template.py                           # 最小化算法模板
├── cryptology/
│   ├── discrete_log/algorithm.py         # 离散对数算法
│   ├── shor/algorithm.py                 # Shor 质因数分解算法
│   └── simon/algorithm.py               # Simon 算法
├── fundamental_algorithm/
│   ├── amplitude_amplification/          # 振幅放大
│   ├── amplitude_estimation/             # 量子振幅估计
│   ├── grover/                          # Grover 搜索算法
│   ├── hadamard_test/                   # Hadamard 测试
│   ├── hadamard_transform/              # n 比特 Hadamard 变换
│   └── qpe/                            # 量子相位估计
├── hamiltonian_simulation/
│   ├── cartan/                          # Cartan 分解
│   ├── qdrift/                          # QDrift 随机乘积公式
│   ├── qsp/                            # 基于 QSP 的哈密顿量模拟
│   ├── taylor/                         # Taylor 级数展开
│   └── trotter/                        # Trotter 分解
├── linear_algebra/
│   ├── aqc/                             # 绝热量子计算（AQC）线性方程组求解
│   ├── hhl/                            # HHL 线性方程组求解器
│   ├── lcu/                            # 酉算符线性组合
│   ├── qft/                            # 量子傅里叶变换
│   ├── qsp/                            # QSP 多项式变换
│   ├── qsvt_qlsa/                      # 基于 QSVT 的线性求解器
│   └── vqls/                           # 变分量子线性求解器
├── quantum_machine_learning/
│   ├── cvqnn/                          # 连续变量量子神经网络
│   ├── fermi_hubbard_vqe/              # 一维开放 Fermi-Hubbard 模型 VQE 基态求解
│   ├── qaoa/                           # 量子近似优化算法
│   ├── qcbm/                           # 量子线路 Born 机
│   ├── vqc/                            # 变分量子分类器
│   └── vqe/                            # 变分量子本征求解器
├── state_preparation/
│   ├── mottonen/                       # Möttönen 态制备
│   ├── multiplexer/                    # 多路复用器态制备
│   ├── mps/                            # 矩阵乘积态（MPS）态制备
│   ├── pauli/                          # Pauli 特征基态制备
│   └── Superposition/                  # 稀疏支撑集叠加态制备
└── schrodingerization/
    ├── base.py                          # 偏微分方程算法基类
    ├── equation_advection/              # 一维对流方程
    ├── equation_heat/                   # 一维热方程
    └── equation_heat2d/                 # 二维热方程

统一返回格式

cryptology/fundamental_algorithm/hamiltonian_simulation/linear_algebra/quantum_machine_learning/state_preparation 六个包中的算法，其 .run() 方法通常通过 BaseAlgorithm._build_return_dict() 构造返回值（详见算法模板指南），返回 Dict[str, Any]，包含至少以下字段：

字段	类型	说明
`status`	`str`	成功时为 `'ok'`，失败时为 `'failed'`
`circuit_path`	`str \| list[str]`	保存的量子线路 SVG 图的本地路径；若一次运行保存了多张线路图，则为路径列表
`plot`	`list[dict]`	结果文件信息，每项为 `{'format': ..., 'filename': ...}`；`format` 取自文件名最后 3 个字符
`circuit`	线路对象或 `None`	`_build_return_dict()` 透传的原始线路对象，供需要进一步处理线路的调用方使用

注意：schrodingerization 包使用独立的基类和手工构造的返回字典，字段形状不同（circuit 为列表、plot 为单个字典），详见薛定谔化方法。

部分算法还会返回额外的算法专有字段（如 factors、phase、fidelity 等）。