正向一致性过滤

做什么：对单步逆向拆分给出的每一组候选反应物跑一次正向预测，只保留"正向模型 top-k 模板里包含这条候选自己那个逆向模板"的候选——即这组反应物正向确实倾向于走回目标的那个反应。用来在 单步拆分里过滤掉"逆向拆得出、正向根本不会这么反应"的候选（只删、不重排存活项），从而压低多步搜索的 分支数。正向与逆向模型共享同一套模板库，两边的模板 id 可直接比对。逆向/正向模型分别见 单步逆向反应预测 / 单步正向反应预测。

默认关闭：需要时显式开。

用法一：挂进规划器，过滤每一步

import synomega

planner = synomega.load_default_planner(forward_consistency=True,
                                        forward_top_k=3)
# 之后 plan / score 的每个单步候选都会被筛：若该候选的逆向模板不在其反应物的
# 正向 top-3 模板里，就丢弃（首用会下载 r20 正向模型到 ~/.cache/synomega）

用自己的正向模型（run 目录）：forward_consistency="/path/to/forward_run_dir"。

用法二：命令行

synomega plan --target "O=C(Nc1ccccc1)c1ccc(Cl)cc1" --forward-consistency
#   --forward-top-k 3     收紧/放松：越小越严、砍得越狠
#   --forward-model DIR   指定自定义正向模型（默认下载 r20 正向模型）

参数与注意

• forward_top_k（默认 3）：候选的逆向模板需落在正向 top-k 内才保留；越小筛得越狠、分支砍得越多。
• 过滤器只删候选、不重排存活项；某分子无任何候选通过时，保底留逆向模型自己的 top-1， 保证搜索不死路。要调保底数传 forward_consistency_kwargs={"min_keep": ...}。
• 每个节点会对其全部候选批量跑一次正向推理（与合理性过滤同量级开销）；过滤结果进搜索缓存，不重复算。
• 与反应合理性评分是两种互补的候选过滤器：一个问"这些反应物 → 目标合理吗" （双塔打分），一个问"正向模型是否也预测这条反应"（模板一致）。可同时开。