企业官网建设流程全解析

CatTSunami 数据集完全指南：OC20 NEB DFT 轨迹文件结构与 ML 加速 NEB 实战

【免费下载链接】ocpFAIR Chemistry's library of machine learning methods for chemistry项目地址: https://gitcode.com/GitHub_Trending/oc/ocp

CatTSunami 是 FAIR Chemistry 面向表面催化反应开发的高通量 NEB（nudged elastic band）帧集合枚举框架，本文以其验证数据集文档 DATASET.md 为骨架，系统讲解 OC20 NEB 轨迹压缩包的目录组织、文件名编码规则、轨迹内部帧结构与读取方法，并结合 CatTSunami README 与核心源码，给出基于 ASE +FAIRChemCalculator从零运行 ML 加速 NEB 的完整可运行方案。读完本文，你将能够独立解析任意一条 OC20 NEB 轨迹文件，提取未优化与已优化帧集，并复现论文中"ML 先跑 NEB、DFT 单点验算"的完整工作流。

一、数据集概览：三类反应、932 条收敛轨迹

根据 CatTSunami README，验证数据集包含932 条收敛的 DFT NEB 计算，覆盖三种表面催化反应类别：

作者共执行了2827 次 DFT NEB 计算（包含未收敛的体系），其中 932 条收敛并进入验证集；未收敛体系同样以 ASE 轨迹形式归档在 "All Trajectories" 压缩包中。数据压缩包信息如下：

下载后解压即可得到本文要解析的轨迹文件集合，这也是后续运行 ML NEB 与模型验证的输入数据。

二、压缩包目录结构：按反应类别组织

解压 tar 包后得到3 个子目录：dissociations、desorptions和transfers。正如其名，每个目录存放对应反应类别下已收敛的 DFT 轨迹。每条轨迹是一个独立的.traj文件（ASE 格式），代表一条从反应物到产物的 NEB 反应路径。

每条轨迹文件对应一次具体反应的 NEB 计算，其命名承载了完整的体系身份信息，理解命名规则是正确索引数据集的第一步。

三、轨迹文件名解剖：7 段编码规则

以一个典型文件名为例：

desorption_id_83_2409_9_111-4_neb1.0.traj

按_与-切分，每一段含义如下（编号对应文档原始定义）：

1. desorption—— 反应类型。另外两种可能是dissociation与transfer，与压缩包内的三个子目录一一对应。
2. id—— 该材料属于in-domain（域内）验证划分；若为ood则表示 out-of-domain（域外）。
3. 83—— 任务 id（task id）。文档明确指出不包含有用信息，可忽略。
4. 2409—— 所用 bulk 在 ocdata bulk pickle 文件中的bulk 索引。该索引可追溯到底层材料结构来源。
5. 9——反应索引。每种反应类型对应仓库中的一个反应 pickle 文件（见下文第四节），这里指该 pickle 文件中的第 9 条反应（0 起始计数）。
6. 111-4—— 前三位是密勒指数，即(1,1,1)表面；最后一位4是shift 值，表示枚举中使用的是第 4 个平移（shift）配置。
7. neb1.0—— NEB 弹簧常数k值。完整数据集中统一使用1.0，因此该段不用于区分不同轨迹，仅保留信息完整性。

提示：结合第 5 段（反应索引）与仓库中的反应数据库 pickle 文件，可以精确还原该轨迹对应的化学反应式与断裂/形成键信息，具体机制见第五节。

四、轨迹文件内部结构：重复的帧集合

与常见的"一文件一构型"不同，NEB 轨迹文件保存的是重复出现的帧集合（repeating frame sets）。NEB 计算本身包含 N 次迭代，而每一次迭代都会把完整的 10 帧（含首尾）写入轨迹——尽管首尾帧在 NEB 中并不参与优化，它们依然被逐迭代保存。

因此轨迹文件的长度满足：

轨迹帧总数 = 迭代次数 N × 10

其中 10 帧的构成为：8 个在 NEB 过程中被优化的中间帧 + 1 个初始帧 + 1 个末帧。

文档给出的读取示例：

from ase.io import read traj = read("desorption_id_83_2409_9_111-4_neb1.0.traj", ":") unrelaxed_frames = traj[0:10] # NEB 优化前的初始帧集合 relaxed_frames = traj[-10:] # NEB 优化后的最终帧集合

由于每次迭代都写入完整帧集，traj[0:10]取出的是优化前的原始插值帧，traj[-10:]取出的是最后一次迭代（已收敛）的优化帧——这正是 NEB 的起点与终点，也是后续做 ML 推理或 DFT 单点验证的标准入口。仓库 tutorial 目录 中还提供了一条sample_traj.traj示例轨迹，可配合 notebook 直接练习上述切片操作。

五、反应数据库：从文件名追溯到化学反应

文件名第 5 段引用的"反应 pickle 文件"位于仓库 databases 目录：

• desorptions_9Aug23.pkl
• dissociation_reactions_22May24.pkl
• transfers_5Sept23.pkl

这些数据库由 reaction.py 中的Reaction类加载。每条记录以字典形式存储，例如从desorptions_9Aug23.pkl读出的第一条：

{'reaction': '*CO -> CO(g)', 'reaction_type': 'desorption', 'reactant': 5, 'product': 5, 'idx_mapping': [{0: 0, 1: 1}], 'edge_indices': [(0, 1)], 'broken_edge': []}

Reaction类根据reaction_type分支解析记录，为后续帧生成提供关键信息：

• dissociation / transfer：reactant1/2、product1/2在吸附物数据库中的索引、idx_mapping（对称性映射）、edge_indices_initial/final（初始/最终键边表）；
• desorption：reactant、product与edge_indices，idx_mapping由get_desorption_mapping动态生成（恒等映射）。

idx_mapping与edge_indices是衔接"数据集"与"帧生成"的桥梁：AutoFrame枚举框架依赖它们判断反应物键是否完整、产物键是否正确，以及是否需要因吸附物对称性重排原子索引（详见第七节）。

六、为什么不提供 LMDB：OCP 与 NEB 的边界

文档明确说明：该数据集没有准备 lmdb 格式。原因在于 NEB 计算无法被 OCP（Open Catalyst Project）训练/推理管线直接支持——OCP 的数据管线面向单帧能量/力/应力回归，而 NEB 是 ASE 层面的多帧路径优化算法。

因此正确的使用方式是：使用 ASE 原生的 OCP 计算类（即 fairchem 的FAIRChemCalculator）配合 ASE 的 NEB 基础设施，把 fairchem 预训练模型当作一个提供能量与力的 ASE calculator 接入 NEB 优化循环。

七、实战：用 ASE + FAIRChemCalculator 运行 ML 加速 NEB

这是 DATASET.md 给出的核心用法，此处结合源码做完整注释：

from ase.io import read from ase.optimize import BFGS from fairchem.core import pretrained_mlip, FAIRChemCalculator from ase.mep import DyNEB # 1. 读取一条轨迹，取 NEB 优化前的 10 帧作为起点 traj = read("desorption_id_83_2409_9_111-4_neb1.0.traj", ":") images = traj[0:10] # 2. 加载预训练模型，得到 MLIPPredictUnit predictor = pretrained_mlip.get_predict_unit("uma-s-1p1") # 3. 用 ASE 的 DyNEB（动态 NEB）构造带弹簧的路径对象 neb = DyNEB(images, k=1) # 4. 为每一帧挂上 fairchem 的 ASE calculator for image in images: image.calc = FAIRChemCalculator(predictor, task_name="oc20") # 5. 先用宽松收敛标准跑普通 NEB optimizer = BFGS( neb, trajectory=f"test_neb.traj", ) conv = optimizer.run(fmax=0.45, steps=200) # 6. 收敛后开启 climbing image 精修过渡态 if conv: neb.climb = True conv = optimizer.run(fmax=0.05, steps=300)

关键 API 的源码级说明

• pretrained_mlip.get_predict_unit("uma-s-1p1")：从 pretrained_mlip.py 加载预训练模型。uma-s-1p1注册在 pretrained_models.json 中，首次调用会从 Hugging Face 下载权重到本地缓存目录（默认~/.cache/fairchem）。
• FAIRChemCalculator(predictor, task_name="oc20")：定义于 ase_calculator.py，是一个标准的 ASECalculator子类。task_name决定输出能量键名与元素参考能量来源；对 UMA 检查点，合法取值包括oc20、odac、omc、omol、omat等，这里选择oc20与 OC20 NEB 数据集保持一致。
• DyNEB(images, k=1)：ASE 的动态 NEB，自动调整中间帧间距；k为弹簧常数，与文件名中的neb1.0对应。
• 两阶段收敛策略：第一阶段fmax=0.45、steps=200先获得路径整体收敛；随后neb.climb = True开启爬坡模式（CI-NEB），以fmax=0.05、steps=300精修过渡态，这是论文验证流程的标准做法。

完整验证工作流

仓库在 run_validation 中提供了批量验证脚本 run_validation.py 及 run_validation.sh：

python run_validation.py \ --checkpoint_path "<path-to-checkpoint>" \ --trajectory_path "<path-to-OC20NEB-trajs>" \ --k 1 \ --output_file_path "<path-to-your-output>" \ --batch_size 8 \ --delta_fmax_climb 0.4 \ --get_ts_sp \ --vasp_command "<vasp-command>" \ --fmax 0.05 \ --mapping_file_path "mapping_files/dissociation_mapping.pkl"

该脚本的核心流程与第七节完全一致：读取映射文件（desorption/dissociation/transfer_mapping.pkl，路径位于 mapping_files）、加载预训练模型、构造FAIRChemCalculator、用DyNEB + BFGS跑两阶段 NEB。脚本额外支持：

• --get_ts_sp：对 ML 定位的过渡态帧调用 VASP 做 DFT 单点（通过vasp_interactive与VaspInteractive），得到E_TS_SP用于与 DFT 参考值对比；
• 结果量化：脚本按"ML 与 DFT 势垒误差 ≤0.05/0.1 eV 的成功率"与"收敛率"两类指标汇总（get_results_ml/get_results_sp），输出并保存results.parquet。

这正是 CatTSunami 验证新模型的标准协议：ML 快速枚举与弛豫 + 过渡态 DFT 单点校验。

八、延伸：AutoFrame 帧集合枚举框架

数据集本身即来源于论文中的自动帧生成流程，其实现位于 autoframe.py，按反应类型分为三个类：

三个类共享基类AutoFrame的去重（only_keep_unique_systems）与对称性处理（get_most_proximate_symmetric_group、reorder_adsorbate）逻辑。生成路径后，interpolate_and_correct_frames→unwrap_atoms→interpolate完成三步：跨 PBC 的最短路径解包（get_shortest_path）、按键图深度优先遍历重排吸附物（traverse_adsorbate_*）、以及带原子重叠修正的线性插值（interpolate中 100 轮迭代避碰）。is_edge_list_respected则用共价半径判定吸附物内部成键是否符合反应定义的边表，保证插值轨迹不产生意外断键。

理解这一框架有助于回答"数据集轨迹从哪来"：每条.traj都始于Reaction定义的反应式，经由 AutoFrame 枚举出的多组初末帧，再经过 DFT NEB 收敛而成。

九、小结

本文围绕 DATASET.md 完整解析了 OC20 NEB 验证数据集：三类反应子目录的组织方式、desorption_id_83_2409_9_111-4_neb1.0.traj七段命名编码、N × 10的帧重复结构，以及"无 LMDB、须走 ASE"的使用约束。在此基础上，给出了基于get_predict_unit+FAIRChemCalculator+DyNEB/BFGS的 ML 加速 NEB 完整代码与批量验证脚本，并延伸到 AutoFrame 枚举框架的源码原理。

对希望评估新 ML 模型在过渡态任务上表现的开发者，标准路径是：下载 Converged Trajectories 压缩包 → 按文件名与反应数据库定位感兴趣的反应 → 用本文第七节代码跑 ML NEB → 用run_validation.py对照 DFT 参考势垒统计成功率。该数据集亦可直接用于微调或评估 fairchem-core 中的任意预训练模型，作为催化过渡态预测任务的基准。

【免费下载链接】ocpFAIR Chemistry's library of machine learning methods for chemistry项目地址: https://gitcode.com/GitHub_Trending/oc/ocp