SynPlanner 完整教學 — 電腦輔助逆合成規劃

第 1 章：專案定位與核心價值

逆合成規劃 (Retrosynthetic Planning) 是什麼？

逆合成分析 (retrosynthetic analysis) 是有機化學中最核心的策略思維：從目標分子 (target molecule) 出發，反向推導出一系列可行的合成步驟，最終到達可商業購買的起始原料 (building blocks)。

傳統上，這需要經驗豐富的有機化學家逐步拆解分子，考慮每一步的 selectivity（選擇性）、yield（產率）、與 building block 的可取得性。SynPlanner 將這個過程自動化：

1目標分子 (Target)
2    ↓ 反應規則 (Reaction Rule)
3前驅物 A + 前驅物 B
4    ↓               ↓
5Building Block    進一步拆解...
6(可購買)              ↓
7                Building Block + Building Block
8                (可購買)         (可購買)

SynPlanner 的設計哲學

SynPlanner 是一個 end-to-end（端到端） 工具：從原始反應數據（例如 USPTO patent reactions）開始，經過資料整理、規則提取、模型訓練，到最終的逆合成搜尋。

它的核心引擎結合兩個關鍵技術：

  1. Monte Carlo Tree Search（MCTS; 蒙地卡羅樹搜尋）：與 AlphaGo 使用的演算法相同概念，在巨大的化學空間中有效搜尋最佳路線
  2. Graph Neural Network（GNN; 圖神經網路）：將分子圖 (molecular graph) 編碼為向量，預測哪些反應規則最可能適用

為什麼選擇 SynPlanner？

特色SynPlanner其他工具 (AiZynthFinder / ASKCOS)
端到端管線從原始反應到規劃通常需要額外工具做 data curation
搜尋演算法6 種 MCTS 變體通常 1-2 種
Priority Rules可注入 curated 反應不支援
Route QualityCompeting sites scoring無或有限
建置系統uv + supply-chain hardening通常 pip/conda
授權MIT (完全開源)有些限制商業用途

對生物資訊分析師的特殊價值

如果你正在做 lead optimization（先導化合物優化），需要對新 analog（類似物）做 retrosynthesis，SynPlanner 的以下特性特別重要：

  • 短步驟合成路線：max_depth: 6 預設最多 6 步，可調整
  • Building block 可購買性：內建 eMolecules 等商業 building block 資料庫比對
  • 批次處理：一次對多個 target 分子進行規劃（targets.smi 一行一個 SMILES）
  • Route clustering：從多條成功路線中找出最具代表性的合成策略

專案統計

項目數值
Stars54
版本v1.5.0 (2026-05-18)
授權MIT
Python3.10 – 3.14
論文JCIM 2025, doi:10.1021/acs.jcim.4c02004
DemoHuggingFace Spaces
Colab3 篇 (planning / benchmarking / clustering)
教學14 篇 Jupyter Notebooks

第 2 章：安裝指南 (Installation Guide)

2.1 系統需求

項目需求
作業系統Linux x86_64、macOS arm64（Windows 需用 Docker）
Python3.10 – 3.14
硬碟空間~2 GB（含預訓練模型 + building blocks）
GPU可選，PyTorch CUDA 支援（加速 atom mapping + 模型訓練）

2.2 pip 安裝（最簡單）

 1# 建立虛擬環境（推薦使用 uv）
 2uv venv synplanner-env --python 3.12
 3source synplanner-env/bin/activate
 4
 5# 安裝（CPU 版本）
 6uv pip install "SynPlanner[cpu]"
 7
 8# 或 GPU 版本（CUDA 12.6）
 9uv pip install "SynPlanner[cu126]"
10
11# 驗證
12synplan --version
13# SynPlanner 1.5.0

2.3 Docker 安裝（跨平台）

1# CLI 版本
2docker pull ghcr.io/laboratoire-de-chemoinformatique/synplanner:v1.5.0
3
4# GUI 版本（含 Streamlit）
5docker pull ghcr.io/laboratoire-de-chemoinformatique/synplanner-gui:v1.5.0
6
7# 使用
8docker run -v $(pwd):/data synplanner:v1.5.0 synplan --help

2.4 開發者安裝

1git clone https://github.com/Laboratoire-de-Chemoinformatique/SynPlanner.git
2cd SynPlanner
3
4# 使用 uv（推薦）
5uv sync --extra cpu --dev-group dev
6uv run synplan --version
7
8# 跑測試
9uv run pytest tests/ -v

2.5 下載預訓練資料

1# 下載完整 preset（模型 + 規則 + building blocks）
2synplan download_preset --preset synplanner-gps --save_to synplan_data

這會從 HuggingFace Hub 下載：

  • reaction_rules.tsv：從 USPTO 提取的反應規則（~17K 條）
  • ranking_policy.ckpt：預訓練的 GCN policy network
  • building_blocks.tsv：eMolecules 商業 building blocks（~300K 種分子）

第 3 章：Quick Start — 第一次逆合成規劃

3.1 準備 target 分子

建立 targets.smi 檔案，每行一個 SMILES：

1CC(=O)Nc1ccc(O)cc1
2c1cc(ccc1Cl)C(CCO)NC(C2(CCN(CC2)c3c4cc[nH]c4ncn3)N)=O

第一行是 paracetamol（乙醯氨酚，簡單分子測試用），第二行是 GUI 範例的藥物分子。

3.2 執行規劃

1synplan planning \
2  --config configs/planning_standard.yaml \
3  --targets targets.smi \
4  --reaction_rules synplan_data/policy/supervised_gcn/v1/reaction_rules.tsv \
5  --building_blocks synplan_data/building_blocks/emolecules-salt-ln/building_blocks.tsv \
6  --policy_network synplan_data/policy/supervised_gcn/v1/v1/ranking_policy.ckpt \
7  --results_dir planning_results

3.3 理解輸出

1planning_results/
2├── tree_search_stats.csv      # 每個 target 的搜尋統計
3├── extracted_routes.json      # 所有成功路線的結構化 JSON
4└── extracted_routes_html/     # 每個 target 的 HTML 視覺化報告
5    ├── retroroutes_target_0.html
6    ├── mapped_routes_0.csv    # 映射後的反應（CSV 格式）
7    └── mapped_routes_0.json   # 映射後的反應（JSON 格式）

tree_search_stats.csv 包含關鍵指標：

  • num_routes：找到的路線數量
  • search_time：搜尋時間（秒）
  • first_solution_time：找到第一條路線的時間
  • rule_applicability_rate：規則適用率
  • best_route_score：最佳路線分數

3.4 使用 Google Colab（無需安裝）

最快的嘗試方式是直接使用 Colab notebook：

第 4 章：核心架構解析

4.1 端到端管線總覽

SynPlanner 的完整管線分為 5 個階段：

 1Stage 1: Data Curation（資料整理）
 2  原始反應 → atom mapping → 標準化 → 過濾
 3  ↓
 4Stage 2: Rule Extraction（規則提取）
 5  Clean reactions → reaction templates (SMARTS)
 6  ↓
 7Stage 3: Model Training（模型訓練）
 8  Templates + molecules → policy network (supervised) → value network (RL)
 9  ↓
10Stage 4: Retrosynthetic Planning（逆合成規劃）
11  Target + rules + models + building blocks → MCTS 搜尋 → 路線
12  ↓
13Stage 5: Post-Analysis（後分析）
14  路線 → quality scoring → clustering → visualization

4.2 MCTS 搜尋引擎

SynPlanner 的搜尋引擎是 MCTS 的化學特化版本。核心循環：

  1. Selection（選擇）：從根節點（target 分子）出發，使用 UCB（Upper Confidence Bound）公式選擇最有前途的節點
  2. Expansion（擴展）：對選中的節點，使用 policy network 預測最可能適用的反應規則（Top-50），逐一嘗試套用
  3. Evaluation（評估）：對新生成的前驅物，使用 value network 或 rollout 估算其可合成性
  4. Backpropagation（回傳）：將評估結果回傳到路徑上所有節點，更新 visit count 和 value

搜尋終止條件（任一滿足即停止）：

  • 達到最大迭代次數（預設 100）
  • 達到最大樹大小（預設 1,000,000 節點）
  • 達到時間限制（預設 600 秒）

「成功」的定義：所有 leaf nodes 的分子都在 building blocks 資料庫中找到，或分子太小不需進一步拆解（min_mol_size: 6）。

4.3 六種搜尋演算法

演算法說明適用場景
uct (預設)Upper Confidence Tree — 經典 MCTS通用，平衡 exploration/exploitation
best_first貪心搜尋，永遠展開最高分節點快速找到第一條路線
breadth_first寬度優先搜尋探索所有可能性
beamBeam search，保留 top-K 節點限制記憶體使用
nmcsNested Monte Carlo Search更深入的搜尋
lazy_nmcsLazy NMCS，延遲展開大搜尋空間

4.4 Policy Network（策略網路）

  • 架構：5-layer GCN (Graph Convolutional Network) → 512-dim embedding → dropout 0.4 → Linear → softmax
  • 輸入：分子圖（原子特徵 + 鍵特徵）
  • 輸出：所有反應規則的排序機率
  • 訓練：supervised learning（從已知反應中學習哪條規則適用於哪個分子）
  • 推論：取 Top-50 機率最高的規則嘗試套用（使用 torch.topk 而非 full sort，10% 加速）

4.5 Value Network（價值網路）

  • 架構：與 policy network 共用 GCN backbone
  • 輸入：中間分子圖
  • 輸出：0-1 之間的可合成性分數
  • 訓練：reinforcement learning — 透過 planning simulation 收集正負樣本
  • 用途：在 MCTS expansion 中評估新節點的價值，引導搜尋方向

4.6 Evaluation Strategies（評估策略）

策略說明
gcn使用 value network 預測可合成性（需要預訓練的 value network）
rollout使用 policy network 做模擬 rollout 到 building blocks
random隨機評估（基準線）
policy直接使用 policy network 的機率作為價值
rdkit使用 RDKit 的 SA Score (synthetic accessibility score)

第 5 章：完整管線實戰 — 從原始數據到逆合成

5.1 Step 1：反應映射 (Atom Mapping)

如果你的反應數據沒有 atom mapping，SynPlanner 提供基於 neural attention 的自動映射：

1synplan reaction_mapping \
2  --input raw_reactions.smi \
3  --output mapped_reactions.smi \
4  --workers 4 \
5  --device cuda   # 或 cpu / mps

這一步將 unmapped 反應 A.B>>C 轉換為 mapped 反應 [CH3:1][OH:2].[CH3:3][Cl:4]>>[CH3:1][O:2][CH3:3].[HCl:4]。

5.2 Step 2：反應標準化 (Standardization)

1synplan reaction_standardizing \
2  --config configs/reactions_standardization.yaml \
3  --input mapped_reactions.smi \
4  --output standardized_reactions.smi \
5  --num_cpus 8

標準化包含：

  • 清除 stereo 資訊（可選，v1.5.0 預設 ignore_stereo: true）
  • 正規化分子表示
  • 去除重複反應

5.3 Step 3：反應過濾 (Filtering)

1synplan reaction_filtering \
2  --config configs/reactions_filtration.yaml \
3  --input standardized_reactions.smi \
4  --output filtered_reactions.smi \
5  --num_cpus 8

過濾規則包含：

  • 移除 reaction center 過大的反應
  • 移除產物數量異常的反應
  • 移除原子數量不平衡的反應

5.4 Step 4：規則提取 (Rule Extraction)

1synplan rule_extracting \
2  --config configs/rules_extraction.yaml \
3  --input filtered_reactions.smi \
4  --output reaction_rules.tsv \
5  --num_cpus 8

產出：

  • reaction_rules.tsv：提取的反應規則（SMARTS 格式）
  • *_policy_data.tsv：policy network 訓練資料

5.5 Step 5：Policy Network 訓練

1synplan ranking_policy_training \
2  --config configs/policy_training.yaml \
3  --policy_data reaction_rules_policy_data.tsv \
4  --results_dir policy_results \
5  --workers 4

訓練參數（configs/policy_training.yaml）：

1vector_dim: 512     # GCN embedding 維度
2num_conv_layers: 5  # GCN 層數
3learning_rate: 0.0005
4dropout: 0.4
5num_epoch: 100
6batch_size: 1000
7logger:
8  type: csv         # 也支援 tensorboard / wandb / mlflow

5.6 Step 6：Value Network 微調（可選）

1synplan value_network_tuning \
2  --config configs/tuning.yaml \
3  --targets train_targets.smi \
4  --reaction_rules reaction_rules.tsv \
5  --building_blocks building_blocks.tsv \
6  --policy_network policy_results/ranking_policy.ckpt \
7  --results_dir value_results

5.7 Step 7：逆合成規劃

1synplan planning \
2  --config configs/planning_standard.yaml \
3  --targets targets.smi \
4  --reaction_rules reaction_rules.tsv \
5  --building_blocks building_blocks.tsv \
6  --policy_network policy_results/ranking_policy.ckpt \
7  --value_network value_results/value_network.ckpt \  # 可選
8  --results_dir planning_results

第 6 章：設定檔詳解 (Configuration Deep Dive)

6.1 planning_standard.yaml（核心搜尋設定）

 1tree:
 2  max_iterations: 100        # MCTS 迭代上限
 3  max_tree_size: 1000000     # 樹節點上限
 4  max_time: 600              # 時間限制（秒）
 5  max_depth: 6               # 最大合成步驟數
 6  search_strategy: expansion_first  # 先展開再評估
 7  ucb_type: uct              # UCT 演算法
 8  c_ucb: 0.1                 # exploration 係數（越大越探索）
 9  backprop_type: muzero      # 回傳策略
10  evaluation_agg: max        # 評估聚合方式
11  exclude_small: True        # 排除太小的分子
12  init_node_value: 0.5       # 節點初始值
13  min_mol_size: 6            # 最小分子原子數（小於此的不需拆解）
14  epsilon: 0.0               # epsilon-greedy 探索
15  silent: True               # 不顯示進度條
16node_expansion:
17  top_rules: 50              # 每次展開嘗試前 50 條規則
18  rule_prob_threshold: 0.0   # 機率閾值
19  priority_rules_fraction: 0.5  # priority rules 佔比

6.2 關鍵參數調校指南

場景建議調整
想要更短的路線max_depth: 4（限制最多 4 步）
搜尋時間太長max_iterations: 50 或 max_time: 120
找不到路線top_rules: 100（嘗試更多規則）+ max_iterations: 500
想要更多路線選擇max_iterations: 500 + max_time: 1200
使用 value network設定 evaluation_type: gcn + 提供 --value_network
偏好 exploration增加 c_ucb: 0.5

6.3 Evaluation Type 選擇

在 planning config 中加入 node_evaluation 區塊：

 1node_evaluation:
 2  evaluation_type: gcn       # 使用 value network
 3  normalize: false
 4
 5# 或
 6
 7node_evaluation:
 8  evaluation_type: rollout   # 使用 rollout（不需要 value network）
 9
10# 或
11
12node_evaluation:
13  evaluation_type: rdkit     # 使用 RDKit SA Score
14  score_function: sascore

第 7 章：Priority Rules — 注入專家知識 (v1.5.0 新功能)

7.1 概念

Priority rules 讓你將 curated（人工策劃） 的反應規則注入 MCTS 搜尋，在 policy network 之前優先嘗試。這對 medicinal chemistry 場景特別有價值：

  • 確保特定的 key disconnection（例如 amide bond formation）被優先考慮
  • 注入 multi-component reactions（例如 Ugi 反應）
  • 強制嘗試特定的 deprotection strategies

7.2 使用方式（Python API）

 1from synplan.mcts.tree import Tree, TreeConfig
 2from synplan.utils.loading import load_reaction_rules, load_building_blocks, load_policy_function
 3from synplan.chem.utils import mol_from_smiles
 4
 5# 載入資源
 6reaction_rules = load_reaction_rules("reaction_rules.tsv")
 7building_blocks = load_building_blocks("building_blocks.tsv")
 8policy_fn = load_policy_function(weights_path="ranking_policy.ckpt")
 9
10# 定義 priority rules（SMARTS 格式的 Reactor 物件）
11from chython import smarts
12ugi_rules = [smarts("[pattern]>>")]  # 自訂 SMARTS 規則
13
14# 設定
15config = TreeConfig(
16    max_iterations=200,
17    max_depth=6,
18    use_priority=True,              # 啟用 priority rules
19    priority_rule_multiapplication=True,  # 允許同一規則多次套用
20)
21
22# 建立搜尋樹
23tree = Tree(
24    target=mol_from_smiles("CC(=O)Nc1ccc(O)cc1"),
25    config=config,
26    reaction_rules=reaction_rules,
27    building_blocks=building_blocks,
28    expansion_function=policy_fn,
29    evaluation_function=eval_fn,
30    priority_rules={"ugi": ugi_rules},  # 命名的規則集
31)
32
33# 執行搜尋
34for result in tree:
35    pass
36
37# 檢查統計
38print(tree.stats.per_priority_source)
39# {'ugi': PerSourceCounters(tried=42, succeeded=8)}

7.3 Priority Rules 的搜尋行為

  • Priority rules 在 每個節點 上都會被嘗試（在 policy rules 之前）
  • 進入 UCB 時的機率設為 prob = 1.0 * N（N = 產出的 qualifying fragment 數量）
  • 這意味著 multi-component 反應（如 4-component Ugi）會以 prior=4 進入，自然地主導 sibling selection
  • Priority rules 與 policy rules 是 additive（相加的），兩者都會在每個節點上執行

第 8 章：Route Quality Scoring — 路線品質評估

8.1 Competing Sites Score

v1.5.0 引入了 competing sites scoring，評估合成路線中 functional group selectivity（官能基選擇性）的風險：

  • 偵測路線中每一步是否存在 competing（競爭） 或 incompatible（不相容） 的 functional groups
  • 使用 incompatibility matrix（不相容矩陣）判斷嚴重程度
  • 計算 S(T) 分數：0 = 高風險，1 = 低風險
1S(T) = max[1 - (sum(w_s) + H) / max(N, 1), 0]
2
3w_s = 每步最大嚴重度（incompatible: 1.0, competing: 0.5, compatible: 0.0）
4H = halogen competing-site count
5N = 合成步驟數

8.2 Protection Route Scorer

結合 competing sites score 與原始 route score 進行 re-ranking：

1from synplan.route_quality.scorer import ProtectionRouteScorer
2
3scorer = ProtectionRouteScorer()
4# 在 Tree 建構時傳入
5tree = Tree(..., route_scorer=scorer)

8.3 對 Lead Optimization 的意義

  • 高分路線 = functional group 衝突少 = 合成較不需要保護基 (protecting groups)
  • 低分路線 = 需要額外的 protection/deprotection 步驟 = 實際步驟數會增加
  • 結合 priority rules 使用 deprotection SMARTS，可以自動規劃保護基策略

第 9 章：路線聚類 (Route Clustering)

9.1 為什麼需要路線聚類？

MCTS 搜尋可能找到 數十到數百條 成功路線。這些路線中有很多是相似的（例如只是在某一步使用了不同的 building block）。路線聚類可以：

  • 將相似路線歸為同一 cluster
  • 每個 cluster 代表一種不同的合成策略
  • 幫助化學家快速選擇最佳策略

9.2 Strategic Bonds 方法

SynPlanner 使用 strategic bonds（策略性化學鍵） 作為聚類特徵：

  1. 比較每條路線與 target 分子，找出被切斷的化學鍵
  2. 將切斷的鍵集合作為路線的 fingerprint
  3. 使用 hierarchical clustering 進行分群
1synplan clustering \
2  --targets targets.smi \
3  --routes_file planning_results/extracted_routes.json \
4  --cluster_results_dir cluster_results \
5  --perform_subcluster \
6  --subcluster_results_dir subcluster_results

9.3 輸出解讀

Clustering 產出 HTML 報告，視覺化每個 cluster 的代表路線與 strategic bonds。

第 10 章：進階用法與實戰技巧

10.1 批次規劃多個 target

1# targets.smi 中每行一個 SMILES
2# SynPlanner 會逐一處理，結果分別存檔
3synplan planning \
4  --config configs/planning_standard.yaml \
5  --targets targets.smi \
6  --reaction_rules reaction_rules.tsv \
7  --building_blocks building_blocks.tsv \
8  --policy_network ranking_policy.ckpt \
9  --results_dir batch_results

10.2 自訂 Building Blocks

如果你有特定的 building blocks 來源（例如特定供應商）：

 1# 先標準化 building blocks
 2synplan building_blocks_standardizing \
 3  --input my_building_blocks.smi \
 4  --output my_building_blocks_standardized.tsv
 5
 6# 然後在規劃時使用
 7synplan planning \
 8  ... \
 9  --building_blocks my_building_blocks_standardized.tsv \
10  ...

10.3 使用 Streamlit GUI

1# 從 Docker
2docker run -p 8501:8501 synplanner-gui:v1.5.0
3
4# 或本地安裝後
5streamlit run synplan/interfaces/gui.py

GUI 支援：

  • 使用 Ketcher 繪製目標分子
  • 即時搜尋與結果視覺化
  • 路線比較與聚類
  • 一鍵下載結果

10.4 ORD 格式轉換

如果你使用 Open Reaction Database (ORD) 的資料：

1synplan ord_convert \
2  --input reactions.pb \
3  --output reactions.smi

10.5 Python API 直接使用

 1from synplan.mcts.tree import Tree, TreeConfig
 2from synplan.utils.loading import (
 3    load_reaction_rules, load_building_blocks,
 4    load_policy_function, load_evaluation_function
 5)
 6from synplan.utils.config import PolicyNetworkConfig, ValueNetworkEvaluationConfig
 7from synplan.chem.utils import mol_from_smiles
 8from synplan.utils.visualisation import generate_results_html
 9
10# 載入資源
11rules = load_reaction_rules("reaction_rules.tsv")
12bb = load_building_blocks("building_blocks.tsv", standardize=False)
13
14policy_config = PolicyNetworkConfig(weights_path="ranking_policy.ckpt", top_rules=50)
15policy_fn = load_policy_function(policy_config=policy_config)
16
17# Value network evaluation（可選）
18eval_config = ValueNetworkEvaluationConfig(weights_path="value_network.ckpt")
19eval_fn = load_evaluation_function(eval_config)
20
21# 搜尋
22config = TreeConfig(max_iterations=200, max_depth=5, max_time=300)
23target = mol_from_smiles("CC(=O)Nc1ccc(O)cc1")
24
25tree = Tree(
26    target=target, config=config,
27    reaction_rules=rules, building_blocks=bb,
28    expansion_function=policy_fn, evaluation_function=eval_fn,
29)
30
31for _ in tree:
32    pass
33
34# 結果
35print(tree.report())
36print(f"找到 {len(tree.winning_nodes)} 條路線")
37
38# 視覺化
39generate_results_html(tree, "result.html", extended=True)
40
41# 路線品質分析
42for wid in tree.winning_nodes:
43    details = tree.route_details(wid)
44    print(f"路線分數: {details['route_score']:.4f}, 步驟數: {details['route_length']}")

10.6 Lead Optimization 典型工作流

 11. 確定 lead compound + 想探索的 structural modifications
 22. 用 RDKit 或 DataWarrior 列舉 analogs（替換 R-groups）
 33. 產生 analogs.smi
 44. 執行批次規劃：
 5   synplan planning --targets analogs.smi ...
 65. 篩選：
 7   - 成功找到路線的 analog ✓
 8   - 步驟數 ≤ 4 ✓
 9   - Building blocks 都可購買 ✓
10   - Route quality score ≥ 0.5 ✓
116. 將篩選結果交給合成化學家評估

第 11 章：疑難排解與常見問題

11.1 找不到路線 (No Routes Found)

可能原因與對策：

原因解決方案
目標分子太複雜增加 max_iterations: 500、max_time: 1800
規則覆蓋不足增加 top_rules: 100（嘗試更多規則）
Building blocks 太少使用更大的 building block 資料庫
max_depth 太淺增加到 max_depth: 8（允許更多步驟）
分子含罕見結構嘗試使用 evaluation_type: rdkit 而非 value network

11.2 搜尋太慢

原因解決方案
Building blocks 太多篩選到只保留常用的（~100K 條）
top_rules 太高降低到 top_rules: 30
使用 rollout evaluation改用 evaluation_type: gcn 或 random
CPU 瓶頸確認 PyTorch 有使用 GPU（--device cuda）

11.3 安裝問題

1# chython 編譯失敗 → 確認 C++ compiler
2apt install build-essential  # Ubuntu
3brew install gcc             # macOS
4
5# PyTorch 版本衝突 → 使用 extra 指定
6uv pip install "SynPlanner[cpu]"  # 或 cu126 / cu128
7
8# protobuf 版本衝突
9uv pip install "protobuf>=6.0"

11.4 v1.4.x → v1.5.0 遷移重點

  • Tree.nodes_depth[nid] → tree.nodes[nid].depth（所有 parallel dict 移到 Node 屬性）
  • Tree.stats 改為 dataclass，使用屬性存取而非 dict subscript
  • apply_reaction_rule 的 top_reactions_num 預設從 3 改為 5
  • load_reaction_rules 預設會驗證 atom mapping，拒絕 unmapped 規則
  • YAML config 中 key: (null) 現在會啟用步驟（以前會跳過）

附錄 A：完整 CLI 參考

 1# 資料管線
 2synplan reaction_mapping        --input --output [--workers] [--device] [--batch-size]
 3synplan reaction_standardizing  --config --input --output [--num_cpus] [--batch_size]
 4synplan reaction_filtering      --config --input --output [--num_cpus] [--batch_size]
 5synplan building_blocks_standardizing --input --output
 6synplan ord_convert             --input --output
 7
 8# 模型訓練
 9synplan rule_extracting         --config --input --output [--num_cpus] [--batch_size]
10synplan ranking_policy_training --config --policy_data --results_dir [--workers] [--logger]
11synplan filtering_policy_training --config --molecule_data --reaction_rules --results_dir
12synplan value_network_tuning    --config --targets --reaction_rules --building_blocks --policy_network
13
14# 搜尋與分析
15synplan planning                --config --targets --reaction_rules --building_blocks --policy_network
16synplan clustering              --targets --routes_file --cluster_results_dir
17
18# 其他
19synplan download_preset         [--preset synplanner-gps] [--save_to .]
20synplan download_all_data       [--save_to .]  # deprecated
21synplan --version
22synplan --help

附錄 B：Tutorials 導覽 (14 篇 Jupyter Notebooks)

#標題內容
00Welcome to ChythonChython 分子操作入門
01Coming from RDKitRDKit 使用者轉換指南
02Data Curation反應資料清理管線
03Rules Extraction反應規則提取
04Policy TrainingPolicy network 訓練
05Retrosynthetic PlanningMCTS 逆合成搜尋
06Tree Analysis搜尋樹分析與統計
07Clustering路線聚類
08Protection Scoring保護基評分
09Combined Ranking Filtering Policy組合 policy 訓練
10NMCS AlgorithmsNested Monte Carlo 演算法
11Planning with RDKit使用 RDKit 做評估
12Rule Analysis反應規則分析
13Priority RulesPriority rules 使用（v1.5.0 新增）

附錄 C：相關引用

Akhmetshin, T.; Zankov, D.; Gantzer, P.; Babadeev, D.; Pinigina, A.; Madzhidov, T.; Varnek, A. SynPlanner: An End-to-End Tool for Synthesis Planning. J. Chem. Inf. Model. 2025, 65 (1), 15–21. doi:10.1021/acs.jcim.4c02004

Gilmullin, A.; Akhmetshin, T.; Madzhidov, T.; Varnek, A. Route Clustering by Strategic Bonds. ChemRxiv, 2025. doi:10.26434/chemrxiv-2025-lnkz6-vz

Westerlund, A. M. et al. Toward Lab-Ready AI Synthesis Plans with Protection Strategies and Route Scoring. ChemRxiv, 2025. doi:10.26434/chemrxiv-2025-68ff6