UCB 用户手册

本手册说明何时选择 UCB、如何配置参数，以及结果如何解读。

1. 适用场景

当化合物库规模较大且希望以更低计算成本获得更优命中时，建议使用 UCB。系统在每轮综合“预测均值”和“不确定性”，在探索与利用之间取得平衡。

2. UCB 是什么

UCB（Upper Confidence Bound）是一种在“高分子”和“高不确定性分子”之间取得平衡的采样方法：

• 均值 μ：模型预测的结合强度（越大越好）。
  
• 不确定性 σ：模型对该分子的信心（越大越值得探索）。

系统按 UCB = μ + κ·σ 计算排序分数，κ 越大越鼓励探索；κ 越小越偏向已知高分。
因此，UCB 不是单纯选最高分，而是在“稳妥命中”和“潜在新结构”之间取得平衡。

UCB 通过 Chemprop 打分驱动“探索/利用”取舍：Chemprop 预测每个分子的均值 μ 与不确定性 σ， 系统计算 UCB 分数（通常为 μ + κ·σ），再据此挑选下一轮候选。

3. 操作步骤

1. 在采样策略中选择 UCB
   
2. 设置 UCB 参数（采样数量、kappa、轮数、冷启动样本数）
   
3. 点击提交，系统自动执行多轮迭代

4. 默认迭代流程

1. 冷启动随机采样
   
2. SFCT 全流程（Sampler → Filter → Collector → Tester；Collector 含 GraphDTA 预筛，Tester 为 Boltz‑2）
   
3. Chemprop 训练
   
4. UCB 采样下一轮
   
5. 重复至轮次结束

5. Boltz‑2 介绍

Boltz‑2 是新一代生物分子基础模型，超越 AlphaFold3 与 Boltz‑1，可联合建模复杂结构与结合亲和力。
它是首个在深度学习中接近基于物理的自由能微扰（FEP）精度、且速度快 1000 倍的模型。
在本流程中，Boltz‑2 作为末端精修打分步骤，用于计算结合强度与结构评分（以 boltz2_score 表示）。

6. Chemprop 训练在做什么

Chemprop 用于学习“结构 → 结合强度”的映射，训练目标来自每轮 SFCT 产生的 Boltz‑2 结果：

• 训练数据：SMILES + boltz2_score（即 -ΔG，数值越大结合越强），每轮都会累积已有 Boltz‑2 结果参与训练。
  
• 训练目的：得到预测均值 μ 与不确定性 σ，用于下一轮 UCB 采样。
  
• 输出：预测文件包含均值与不确定性列（例如 prediction/uncertainty 或 chemprop_mu/chemprop_sigma）。

因此，Chemprop 训练的核心是拟合 Boltz‑2 评分趋势并提供不确定性， 随着训练池累积，模型通常会逐轮更稳定；UCB 选择依赖这一对“均值 + 不确定性”的打分完成采样， 但最终仍会在每轮候选上运行 Boltz‑2，用于生成正式评分与结果输出，而不是用 Chemprop 直接替代 Boltz‑2 本身。

Boltz‑2 结果会累计写入训练池（ucb/train/train.csv），训练集会随轮次增长；即使某一轮命中较少， 历史 Boltz‑2 结果仍会用于后续 Chemprop 训练。

当训练集较小导致验证集样本不足时，系统会自动降低 Chemprop 的 batch_size 并放宽早停条件， 避免因验证集为空导致训练失败；仍建议适当增加冷启动样本或放宽筛选阈值。

7. 参数说明

• UCB 采样数量：每轮选取的 TopN，建议 100~500 起步。
• UCB kappa：探索权重，越大越偏向不确定但潜力高的分子。
• UCB 轮数：迭代次数，默认 3（实际建议 7 轮以上）。
• 冷启动样本数：首轮随机样本数，默认 200。

使用建议：

• 命中偏少时，提高冷启动样本数或适当放宽 Filter 阈值。
• 想更稳，kappa 取 0.5~1；想探索更多，kappa 取 2~3。

示例参数（中等规模库，约 5 万 ~ 50 万分子）：

• 采样数量：1000
  
• kappa：1
  
• 轮数：7
  
• 冷启动样本数：800

8. Boltz‑2 结果与最终输出

每轮 UCB 采样后都会对候选分子运行 Boltz‑2 计算，生成当轮 boltz2_score。
所有轮次的 Boltz‑2 结果会持续累积，并在结束时合并为最终结果（去重汇总）。

9. 输出文件（标准文件名）

以下文件按 boltz2_score 降序排序（-ΔG，数值越大结合越强）：

• output/ucb_last_round.csv：最后一轮命中
• output/ucb_last_round_full.csv：最后一轮全量快照
• output/ucb_final_hits.csv：多轮合并命中（去重）
• output/ucb_final_full.csv：多轮合并快照（去重）
• output/ucb_final_hits_topN.csv：合并 Top N 命中（按 Boltz‑2 分数排序）
• output/ucb_final_hits_recommend.csv：合并推荐集合（骨架聚类后每簇保留一定数量）

10. 常见问题

会重复采样吗？
不会，系统按 ligand_id 跨轮去重。

UCB 跑得太慢怎么办？
可适当降低采样数量或减少轮数；也可先用较小 warmup 试跑后再放大参数。

某一轮命中为 0 会怎样？
若该轮 Boltz‑2 结果为空且训练池为空（常见于首轮），UCB 会提前终止并标记失败；若已有训练池，则仍会继续后续轮次。

命中偏少怎么调整？
提高冷启动样本数，或适当放宽 Filter/Collector 阈值。