量子搜索算法

unitarylab_algorithms.search 提供四个共享 BaseAlgorithm 的算法类，均可从根包按名称导入。构造函数接受 text_mode="plain"、algo_dir=None；默认结果目录为当前工作目录下的 results/search/<算法目录>，也可指定可写目录。

返回值包含 status、circuit_path、plot 和原始 circuit，并合并下文的算法专有字段。字段名区分大小写。各模块还提供与对应 run() 参数相同的模块级 test()；量子游走和回溯的 test() 默认 dtype="complex128"，run() 默认 np.complex128。

胶合树量子游走

通过随机胶合二叉树构造振子系统哈密顿量，进行 Pauli 分解及 Suzuki–Trotter 演化，扫描入口到出口的传播概率。

from tempfile import TemporaryDirectory
from unitarylab_algorithms.search import GluedTreesAlgorithm
 
with TemporaryDirectory() as output_dir:
    result = GluedTreesAlgorithm(algo_dir=output_dir).run(
        qubits=4, times="1.0", repetitions=2, shots=32,
    )
    print(result["Peak exit probability"])

专有字段包括 Nodes、Exit state、Pauli terms、Peak exit probability、Peak time、各时间点的 Rows 和耗时。输出包含代表线路 SVG、结果 TXT 和概率曲线 PNG。峰值来自采样，不等同于理论成功率保证。完整矩阵和 Pauli 展开开销较大，示例仅使用小规模参数。

隐藏移位

使用偶数长度的自对偶 bent 函数构造相位黑盒，通过 Hadamard 变换恢复隐藏串。

from tempfile import TemporaryDirectory
from unitarylab_algorithms.search import HiddenShiftAlgorithm
 
with TemporaryDirectory() as output_dir:
    result = HiddenShiftAlgorithm(algo_dir=output_dir).run(
        shift="10", shots=32, measurement_mode="sample",
    )
    print(result["Most common bitstring"], result["Matched"])

专有字段为 Secret shift、Most common bitstring、Counts、Matched 及构建、执行采样、总耗时。status 按恢复结果是否匹配选择 ok 或 failed。输出为线路 SVG 和结果 TXT。该实现针对上述特定 bent 函数族，不是任意隐藏移位问题的通用求解器。

连续时间量子游走搜索

在图上构造搜索哈密顿量，调用模拟器的 hamiltonian_simulation()，并比较近似演化与精确经典演化。

from tempfile import TemporaryDirectory
from unitarylab_algorithms.search import QuantumWalkSearchAlgorithm
 
with TemporaryDirectory() as output_dir:
    result = QuantumWalkSearchAlgorithm(algo_dir=output_dir).run(
        num_vertices=4, marked="1", evolution_time=1.0,
        simulation_steps=2, shots=32,
    )
    print(result["success_probability"], result["counts"])

graph_json 的边形式为 {"num_vertices": 4, "edges": [[0,1], [1,2,0.5]]}，每条边可含权重；标记顶点仍由 marked 指定。矩阵必须是合法的实对称、无自环图；非二次幂顶点数会填充到二次幂维度。包装类限制最多 32 个顶点，不提供底层 allow_large 开关。

返回字段包括 marked_vertices、gamma、evolution_time、time_selection、exact_probability_at_time、success_probability、simulation_probability_error、sampled_success_probability、counts、probabilities、padded_probability、circuit_summary 和 artifacts。simulation 与 final_state 不包含在返回字典中。包装类保存概览线路 SVG 和结果 TXT，不自动启用底层完整图表导出；artifacts 可以为空。

status="ok" 表示流程完成，不能据此认定采样命中标记点；应查看成功概率。自动选时和精确基线涉及稠密经典运算，不能据此声称端到端量子加速。

量子回溯

对二元约束树构造可逆接受/拒绝谓词，用游走反射及 QPE 检测包含解的子树，再恢复并核验路径。

from tempfile import TemporaryDirectory
from unitarylab_algorithms.search import QuantumBacktrackingAlgorithm
 
with TemporaryDirectory() as output_dir:
    result = QuantumBacktrackingAlgorithm(algo_dir=output_dir).run(
        phase_bits=3, shots=32,
    )
    print(result["exists"], result["solution_path"])

problem_json 支持 type="prefix_constraints"（max_depth、accepted_paths、rejected_prefixes）或 type="binary_cnf"（variables、clauses）。CNF 子句以从 1 开始的带符号变量索引表示，例如 {"type":"binary_cnf","variables":["x"],"clauses":[[1]]}。

返回字段为 problem、exists、solution_path、solution_assignment、evidence、resource_report、artifacts 和 Elapsed time (s)。evidence 记录各前缀的检测证据，资源报告用于评估线路开销。输出包含代表线路 SVG 和结果 TXT。

无解时公共返回仍为 status="ok"，应依据 exists 判断是否检测到解；无解的路径和赋值可以是 None。有限相位精度、采样与阈值会影响检测，不能将一次有限采样当作数学上的无解证明。树深度、工作比特与相位比特会快速增加模拟成本。

相关页面

• API 使用总览
• 基础量子算法
• 哈密顿量模拟