API 使用总览
概述
本页面是 unitarylab_algorithms/ 库的导航指南，汇总了所有可用算法的类名、导入路径、关键参数及 .test() 签名。
本页不是完整的自动生成 API 参考。其目的是帮助你快速定位所需算法并了解调用方式。
BaseAlgorithm——共享基类
cryptology、fundamental_algorithm、hamiltonian_simulation、linear_algebra、quantum_chemistry、quantum_machine_learning、state_preparation 七个包的算法类均继承自 unitarylab_algorithms.algo_base.BaseAlgorithm（schrodingerization 包使用独立的 schrodingerization.base.BaseAlgorithm，返回字典形状也不同，详见薛定谔化方法章节）。每个算法实例都具备以下方法：
| 方法 | 说明 |
|---|---|
.run(*args, **kwargs) | 执行算法，返回 Dict[str, Any]（基类本身抛出 NotImplementedError，由子类实现） |
.log(message) | 打印消息并追加到内部日志；传入 dict 时会以 - key = value 格式逐条打印（不追加到 self.info） |
.update_input(input_dict) | 合并到 self.input，并打印 "Starting {name}" 与参数列表 |
.update_output(output_dict) | 合并到 self.output，并打印输出信息列表 |
.save_circuit(circuit, name=None) | 保存线路 SVG，返回完整文件路径（未指定 name 时用算法名生成文件名） |
.save_txt() | 将 format_result_ascii() 的内容写入文本文件，返回仅文件名（不含目录，与 save_circuit 不同） |
.format_result_ascii() | 按 text_mode（'plain' 或 'legacy'）格式化状态/输入/日志/输出/摘要为文本 |
._build_return_dict(success, circuit_path, filepath, circuit=None) | 内部使用：构造 {"status": "ok"/"failed", "circuit_path": ..., "plot": [...], "circuit": ...}，并合并 self.output；plot 中每项的 "format" 字段是文件名最后 3 个字符（而非显式声明的扩展名） |
共享基类本身不会创建 algo_dir。直接继承该类时，调用 save_circuit() 或 save_txt() 前必须提供一个可写目录并自行创建；当前各算法子类会在自己的 __init__() 中补齐默认结果目录并调用 os.makedirs(..., exist_ok=True)。此外，_build_return_dict() 的 filepath 必须是字符串或可迭代的文件名集合，不能传入 None。
按类别的算法索引
密码学
| 类 | 导入路径 | 关键参数 |
|---|---|---|
DiscreteLogAlgorithm | unitarylab_algorithms.cryptology.discrete_log.algorithm | g、y、P |
ShorAlgorithm | unitarylab_algorithms.cryptology.shor.algorithm | N、method、max_retries |
SimonAlgorithm | unitarylab_algorithms.cryptology.simon.algorithm | s |
基础量子算法
| 类 | 导入路径 | 关键参数 |
|---|---|---|
AmplitudeAmplificationAlgorithm | unitarylab_algorithms.fundamental_algorithm.amplitude_amplification.algorithm | U、good_zero_qubits、p、reps |
AmplitudeEstimationAlgorithm | unitarylab_algorithms.fundamental_algorithm.amplitude_estimation.algorithm | U、good_zero_qubits、d |
GroverAlgorithm | unitarylab_algorithms.fundamental_algorithm.grover.algorithm | n、target |
HadamardTestAlgorithm | unitarylab_algorithms.fundamental_algorithm.hadamard_test.algorithm | mode、U、prepare_psi、prepare_phi、imag、shots |
HadamardTransformAlgorithm | unitarylab_algorithms.fundamental_algorithm.hadamard_transform.algorithm | n、mode |
QPEAlgorithm | unitarylab_algorithms.fundamental_algorithm.qpe.algorithm | U、d、prepare_target |
哈密顿量模拟
| 类 | 导入路径 | 关键参数 |
|---|---|---|
CartanDecompositionAlgorithm | unitarylab_algorithms.hamiltonian_simulation.cartan.algorithm | H、t、error |
QDriftAlgorithm | unitarylab_algorithms.hamiltonian_simulation.qdrift.algorithm | H、t、error、steps |
QSPHSAlgorithm | unitarylab_algorithms.hamiltonian_simulation.qsp.algorithm | H、t、error、degree、beta |
TaylorAlgorithm | unitarylab_algorithms.hamiltonian_simulation.taylor.algorithm | H、t、error、degree |
TrotterAlgorithm | unitarylab_algorithms.hamiltonian_simulation.trotter.algorithm | H、t、error、order、steps |
线性代数
| 类 | 导入路径 | 关键参数 |
|---|---|---|
AQCAlgorithm | unitarylab_algorithms.linear_algebra.aqc.algorithm | n、T、p、backend、device、dtype（不接受用户自定义 A/b，内部固定用 np.random.seed(42) 生成，详见线性代数算法） |
HHLAlgorithm | unitarylab_algorithms.linear_algebra.hhl.algorithm | A、b、d |
LCUAlgorithm | unitarylab_algorithms.linear_algebra.lcu.algorithm | alphas、unitaries、n_sys、initial_state |
QFTAlgorithm | unitarylab_algorithms.linear_algebra.qft.algorithm | n、state、inverse |
QSPAlgorithm | unitarylab_algorithms.linear_algebra.qsp.algorithm | t、d、x |
QSVTLinearSolverAlgorithm | unitarylab_algorithms.linear_algebra.qsvt_qlsa.algorithm | A、b、epsilon |
VQLSAlgorithm | unitarylab_algorithms.linear_algebra.vqls.algorithm | A、b、cost_function='local_ht'、n_layers=4、maxiter=500、tol=1e-6、seed=42、epsilon=None、backend/device/dtype |
量子机器学习
| 类 | 导入路径 | 关键参数 |
|---|---|---|
CVQNNAlgorithm | unitarylab_algorithms.quantum_machine_learning.cvqnn.algorithm | x_train、y_train、n_layers、cutoff、epochs、lr |
FermiHubbardVQEAlgorithm | unitarylab_algorithms.quantum_machine_learning.fermi_hubbard_vqe.algorithm | params、L、t、U、B、layers、max_iter、seed、measure_shots、backend、device、dtype |
QAOAAlgorithm | unitarylab_algorithms.quantum_machine_learning.qaoa.algorithm | edges、n、layers、max_iter |
QCBMAlgorithm | unitarylab_algorithms.quantum_machine_learning.qcbm.algorithm | n、layers、epochs、lr |
VQCAlgorithm | unitarylab_algorithms.quantum_machine_learning.vqc.algorithm | layers、epochs、lr、batch_size |
VQEAlgorithm | unitarylab_algorithms.quantum_machine_learning.vqe.algorithm | n、layers、max_iter、seed、hamiltonian、normalize |
IsingAlgorithm | unitarylab_algorithms.quantum_machine_learning.ising.algorithm | rows、cols、coupling_J、field_h、time_step、trotter_steps、trotter_order、max_bond、cutoff、routing、seed、sample_shots、local_configuration_mode |
IsingAlgorithm 已由 unitarylab_algorithms.quantum_machine_learning 导出，也可直接从根包按名称导入；但当前根包 __all__ 遗漏该名称，因此文档示例使用明确的类别导入路径。详见量子机器学习。
量子化学
| 类 | 导入路径 | 关键参数 |
|---|---|---|
MolecularDMRGAlgorithm | unitarylab_algorithms.quantum_chemistry.molecular_dmrg.algorithm | xyz_file、basis、charge、multiplicity、活性空间、DMRG/CVD 参数、shots、seed、backend、device、dtype |
MolecularDMRGAlgorithm 已列入根包 __all__，可使用 from unitarylab_algorithms import MolecularDMRGAlgorithm。它依赖独立 Chemistry 包，仅支持 Linux/macOS，详见量子化学算法。
态制备
| 类 | 导入路径 | 关键参数 |
|---|---|---|
MottonenAlgorithm | unitarylab_algorithms.state_preparation.mottonen.algorithm | Psi、target_qubits、target_error |
MultiplexerAlgorithm | unitarylab_algorithms.state_preparation.multiplexer.algorithm | Psi、target_qubits、target_error |
MPSAlgorithm | unitarylab_algorithms.state_preparation.mps.algorithm | Psi、target_qubits、target_error、mps、work_wires、right_canonicalize、mps_max_bond_dim、rng_seed |
PauliAlgorithm | unitarylab_algorithms.state_preparation.pauli.algorithm | Psi、target_qubits、target_error |
SuperpositionAlgorithm | unitarylab_algorithms.state_preparation.Superposition.algorithm | Psi、target_qubits、target_error |
详见态制备算法，其中包含 backend/device/dtype 参数、target_error 默认值与 parameters.json 不一致（MPS、Superposition）等 9 项包级差异说明。
薛定谔化（偏微分方程求解器）
| 类 | 导入路径 | 说明 |
|---|---|---|
AdvectionEquationAlgorithm | unitarylab_algorithms.schrodingerization.equation_advection.algorithm | 一维线性对流 |
HeatEquationAlgorithm | unitarylab_algorithms.schrodingerization.equation_heat.algorithm | 一维热扩散 |
Heat2dEquationAlgorithm | unitarylab_algorithms.schrodingerization.equation_heat2d.algorithm | 二维热扩散 |
.test() 快速参考
多数算法模块提供独立的 test() 函数，可用于快速运行默认示例或验证算法是否可用：
# 使用内置默认值运行——无需实例化类
from unitarylab_algorithms.fundamental_algorithm.grover.algorithm import test
test()
from unitarylab_algorithms.cryptology.shor.algorithm import test
test(N=15, method='matrix', max_retries=15)
from unitarylab_algorithms.linear_algebra.hhl.algorithm import test
test(A=[[0.8, 0], [0, 0.4]], b=[1, 2], d=11)
from unitarylab_algorithms.quantum_machine_learning.vqe.algorithm import test
test(n=2, layers=2, max_iter=150)
from unitarylab_algorithms.state_preparation.mottonen.algorithm import test
test(Psi=[1, 0, 0, 1], target_qubits=2, target_error=1e-6)
from unitarylab_algorithms.quantum_machine_learning.ising.algorithm import test
test(rows=2, cols=2, trotter_steps=2, local_configuration_mode="none")
from unitarylab_algorithms.quantum_chemistry.molecular_dmrg.algorithm import test
test(xyz_file="H2") # 运行完整重型 Chemistry 工作流常见使用模式
传入 Circuit 对象
QPE、LCU、振幅放大等算法接受来自 unitarylab 的 Circuit 对象：
from unitarylab.core import Circuit
from unitarylab_algorithms import QPEAlgorithm
# 构造一个需要估计相位的酉线路
U = Circuit(1)
U.t(0) # T 门的相位为 π/4
algo = QPEAlgorithm()
result = algo.run(U=U, d=4)传入哈密顿量矩阵
哈密顿量模拟算法接受 NumPy 数组或二维 Python 列表：
import numpy as np
from unitarylab_algorithms import TrotterAlgorithm
H = np.array([[2, 1], [1, 3]])
algo = TrotterAlgorithm()
result = algo.run(H=H, t=1.0, error=1e-8, order=1, steps=1000)最后更新于