FAIR-Chem ocp 仓库指南使用 Open-Catalyst-Dataset 旧版工具链复现 OC20 数据集生成流程【免费下载链接】ocpFAIR Chemistrys library of machine learning methods for chemistry项目地址: https://gitcode.com/GitHub_Trending/oc/ocp导读本文基于 src/fairchem/data/oc/README_legacy_OC20.md 展开系统讲解 Open Catalyst 2020OC20数据集吸附物–催化剂adsorbate–catalyst输入结构生成的完整流程从环境搭建、采样工作流、三种脚本调用方式到 bulk / adsorbate / precomputed surfaces 数据库的使用与去重策略。读完本文你将掌握如何用指定随机种子或枚举方式生成 VASP 输入文件并能对照当前仓库源码理解每一步的底层实现。说明本文讨论的README_legacy_OC20.md是当前 FAIR-Chem ocp 仓库中保留的历史文档用于复现 OC20 数据集当年的生成方式当前仓库的功能入口已演进为 structure_generator.py文中会同步给出新旧两套入口的对应关系。一、文档背景与适用边界README_legacy_OC20.md明确声明若要以当年生成 OC20 数据集的方式使用本仓库应使用 commit17e350及之前的版本。也就是说这篇文档描述的是旧版 Open-Catalyst-Dataset 仓库的行为——当时的命令行入口是sample_structure.py依赖较旧的 pymatgen、ASE 与 CatKit 组合。在当前 ocp 仓库中同一功能已经重构为面向库调用的核心模块core/ 下的Bulk、Adsorbate、Slab、AdsorbateSlabConfig四个类面向命令行的一体化入口structure_generator.py替代旧版sample_structure.py。两者的核心采样逻辑一脉相承随机/指定选择 bulk → 枚举或随机选择 surface → 在 surface 上放置 adsorbate → 写出 VASP 输入文件。二、环境搭建旧版复现路径旧文档给出了基于 conda 的安装步骤适用于复现 OC20 生成管线conda create -n vaspenv python3.9 conda activate vaspenv pip install pymatgen2020.4.2 ase3.19.1 pip install githttps://github.com/ulissigroup/CatKit.git catkit # 克隆本仓库后执行 pip install -e .关键点pymatgen2020.4.2与ase3.19.1是当年冻结的版本用于保证SlabGenerator、SpacegroupAnalyzer等 API 行为与 OC20 生成时一致CatKit 来自 ulissigroup 的 GitHub 仓库为当年吸附物放置提供辅助pip install -e .以开发模式安装便于直接修改采样脚本。当前仓库的替代安装方式见 README.md在新环境Python ≥ 3.9中执行pip install fairchem-data-oc随后运行python src/fairchem/core/scripts/download_large_files.py oc下载随包发布的 bulk / adsorbate 数据库。当前包内数据库文件位于 databases/pkls/bulks.pkl、adsorbates.pkl、solvents.pkl、ions.pkl路径常量定义见 pkls/init.py。三、采样工作流bulk → surface → adsorbate → config旧文档描述的核心工作流如下每一步的选择既可以随机采样也可以由用户指定选择 bulk 中的元素数量随机选择一个具有该元素数量的 bulk 结构从该 bulk 的所有对称不等价表面中随机选一个Miller 指数 ≤ 2随机选择一个 adsorbate在选中的表面上放置 adsorbate生成一个或多个吸附构型config为每个构型写出VASP 输入文件。OC20 输入结构采样工作流从元素数量选择、bulk 选择、表面枚举到 adsorbate 放置与 VASP 输入输出的完整链路原图来自 README_legacy_OC20.md。这一流程在当前仓库的源码中均有对应实现可逐层印证Bulkcore/bulk.py 的Bulk类支持四种初始化方式——直接传入ase.Atoms、按数据库索引、按src_id如mp-30、或随机采样Slabsurfacecore/slab.py 的Slab类内部调用pymatgen.core.surface.SlabGenerator与get_symmetrically_distinct_miller_indices枚举对称不等价表面min_slab_size7.0、min_vacuum_size20.0、max_broken_bonds0等参数与旧版脚本一致若底面与顶面不等价还会将底面翻转后纳入候选flip_structAdsorbatecore/adsorbate.py 的Adsorbate类支持传入 atoms、索引、SMILES如*CO或随机选择并从数据库中读取绑定原子索引binding_indicesAdsorbateSlabConfigcore/adsorbate_slab_config.py 负责把 adsorbate 放到 slab 的候选位点上支持random、heuristic、random_site_heuristic_placement三种模式。四、支持的三种脚本调用方式旧版 API旧版sample_structure.py支持以下三种用法参数与输出目录结构均有明确约定。用法 1随机采样单个体系按指定随机种子随机采样一个 adsorbate / bulk / surface / config 组合。bulk 数据库为{元素数量: 对应 bulk 列表}的字典结构。输出位于outputs/random0/surface/与outputs/random0/adslab/。python sample_structure.py --bulk_db bulk_db_nelems.pkl \ --adsorbate_db adsorbate_db.pkl \ --output_dir outputs/ --seed 0用法 2枚举指定 adsorbate × 指定 bulk 的全部表面与构型生成 adsorbate 10 在 bulk 20 全部可能表面上的所有吸附放置。输出目录为outputs/10_20_0/surface/、outputs/10_20_0/adslab0/、outputs/10_20_0/adslab1/……其中10_20_0表示adsorbate_index_bulk_index_surface_index。--bulk_indices支持逗号分隔多个 bulk 索引。python sample_structure.py --bulk_db bulk_db_flat.pkl \ --adsorbate_db adsorbate_db.pkl \ --output_dir outputs/ \ --enumerate_all_structures \ --adsorbate_index 10 --bulk_indices 20用法 3枚举指定 adsorbate × 指定 bulk × 指定 surface 的全部构型与用法 2 相同但额外用--surface_index锁定单一表面便于将用法 2 并行化切分python sample_structure.py --bulk_db bulk_db_flat.pkl \ --adsorbate_db adsorbate_db.pkl --output_dir outputs/ \ --enumerate_all_structures --adsorbate_index 10 \ --bulk_indices 20 --surface_index 0公共参数--precomputed_structures dir/使用预先算好的表面而不是从 bulk 现场枚举全部表面可显著提速--verbose输出更多调试信息。当前仓库的对应入口旧版脚本在当前仓库中已更名为 structure_generator.py命令行参数做了重新设计parse_args旧参数新参数说明--bulk_db--bulk_dbbulk 数据库路径必填--adsorbate_db--adsorbate_dbadsorbate 数据库路径--precomputed_structures--precomputed_slabs_dir预计算表面目录命中则跳过现场枚举bulk.py--enumerate_all_structures--heuristic_placements/--random_placements/--indices_file改为显式指定放置模式或索引文件--seed--seed随机种子structure_generator.py--surface_index--surface_index/--max_miller表面索引 / 最大 Miller 指数默认 2新入口还补充了--random_sites每个表面的随机位点数、--num_augmentations每个位点的随机旋转增强次数默认 1、--no_vasp只写 POSCAR、--chunks/--chunk_index多节点切分与--workers进程内多进程数等参数。批量模式通过--indices_file每行adsorbate_bulk_surface三个下划线分隔的索引配合多进程池运行structure_generator.py。输出目录结构为output_dir/bulk{idx}/surface{idx}/ads{idx}/{heur|rand|randsh}{n}/每个目录内含 VASP 输入文件与metadata.pkl见 StructureGenerator.run。五、OC20 数据集的实际生成规模与细节旧文档披露了 OC20 生成时的关键工程参数候选规模考虑最多 3 种元素的 bulk 材料共约1.5 万个 bulk 结构与82 个 adsorbate决策树分支从选定 bulk 采样一个表面最多需要考虑125 种不同的 Miller 指数计算在一个表面上放置 adsorbate 平均需要枚举约30 个位点产出与去重共生成约250 万个 adsorbatecatalyst 输入先做去重再送入 DFT 计算算力特征每个输入体系在单 CPU 核上生成超时上限 200 分钟随机种子OC20 采用用法 1 的随机采样方式随机种子范围为02500000python sample_structure.py --bulk_db bulk_db_nelems_2020may12.pkl \ --adsorbate_db adsorbate_db_2020may12.pkl \ --precomputed_structures precomputed_structure_info_oc20/ \ --output_dir outputs/ --seed 0从源码看这一决策树在 core/adsorbate_slab_config.py 中体现为位点采样random/random_site_heuristic_placement模式对表面原子做 Delaunay 三角剖分后在三角形内均匀采样位点heuristic模式则调用 pymatgen 的AdsorbateSiteFinder寻找 ontop / bridge / hollow 位点。放置时通过沿表面法线方向的缩放平移避免原子重叠_get_scaled_normal见 adsorbate_slab_config.py。六、bulk / adsorbate / 预计算表面数据库旧文档提供了生成 OC20 所使用的数据库及其 MD5 校验和托管于 Open Catalyst Project 的公开数据下载站点dl.fbaipublicfiles.com/opencatalystproject/data/input_generation/目录下Bulk 数据库按元素数量分组的字典用法 1 随机采样用bulk_db_nelems_2021sep20.pklMD54bb119062019c4624987fa1ac92bd837扁平列表用法 2/3 按索引取用约 1.1 万个 bulkbulk_db_flat_2021sep20.pklMD543df744a8366c25392e3072d445016b2索引 ↔ bulkMPID 与组成映射mapping_bulks_2021sep20.txt。Adsorbate 数据库最新版adsorbate_db_2021apr28.pklMD5975e00a62c7b634b245102e42167b3fb索引 ↔ adsorbateSMILES映射mapping_adsorbates_2020may12.txt。预计算表面precomputed_surfaces_2021sep20.tar.gz约 5.5 GBMD5f56fe10f380d945d46a1bfab136a4834解压后为precomputed_surfaces_2021june11/目录解压后约 18 GB内含 1.1 万个 pickle 文件文件名格式为从零开始的索引.pkl与 bulk 索引一一对应。版本一致性注意OC20 实际使用的是旧版 bulkbulk_db_nelems_2020may12.pklMD5b87281d01a2006586fa719a1d2ee2682其中包含 50 个重复 bulk 条目已在最新版移除与旧版 adsorbateadsorbate_db_2020may12.pklMD56c553a7c2009e11612c247ffb813fd74包含一处已在最新版修复的不一致。若要精确复现 OC20应使用旧版数据库而非最新版。当前仓库中预计算表面的批量生成脚本为 scripts/precompute_sample_structures.py其enumerate_surfaces_for_saving函数展示了与旧版一致的表面枚举细节SlabGenerator(min_slab_size7.0, min_vacuum_size20.0)、对底面翻转的flip_struct、以及SpacegroupAnalyzer对称性判断。七、去重策略决策树遍历的唯一字符串为保证送入 VASP 计算的输入互不重复OC20 采用如下去重策略为每个采样结果保存一个唯一字符串该字符串概括了其在采样决策树上的遍历路径作为元数据随结构一起存储生成新输入时将该字符串与历史输入比对从而剔除重复体系。这一路径即指纹的思路在当前仓库中体现为结构元数据的持久化Slab.get_metadata_dict保存bulk_id、millers、shift、top、oriented_bulkcore/slab.pyAdsorbateSlabConfig.get_metadata_dict额外记录smiles、site与xyz_anglescore/adsorbate_slab_config.py最终由 structure_generator.py 将元数据写入每个输出目录的metadata.pkl为后续去重与溯源提供依据。八、VASP 输入文件生成无论旧版还是新版入口最终都要写出 VASP 输入文件实现在 utils/vasp.pywrite_vasp_input_files基于 ASE 的Vaspcalculator 写出POSCAR/INCAR/KPOINTS/POTCARvasp.py_clean_up_inputs会检查晶胞矢量是否满足右手定则X × Y指向 Z不满足则交换 X/Y 顺序以保证 VASP 兼容vasp.pycalculate_surface_k_points按40 / 晶格常数估算 k 点网格x、y 方向取整且不小于 1z 方向为 1对应表面计算的惯例vasp.py默认 VASP 参数集定义于 utils/vasp_flags.py。若只想生成结构不想跑 DFT可使用--no_vasp仅保留 POSCAR删除 INCAR / KPOINTS / POTCAR。九、引用与许可OC20 数据集遵循 Creative Commons Attribution 4.0 License。若研究工作中使用了 OC20 数据集请引用以下论文README_legacy_OC20.md中给出misc{ocp_dataset, title{The Open Catalyst 2020 (OC20) Dataset and Community Challenges}, author{Lowik Chanussot* and Abhishek Das* and Siddharth Goyal* and Thibaut Lavril* and Muhammed Shuaibi* and Morgane Riviere and Kevin Tran and Javier Heras-Domingo and Caleb Ho and Weihua Hu and Aini Palizhati and Anuroop Sriram and Brandon Wood and Junwoong Yoon and Devi Parikh and C. Lawrence Zitnick and Zachary Ulissi}, year{2020}, eprint{2010.09990}, archivePrefix{arXiv} }总结README_legacy_OC20.md完整记录了 OC20 数据集输入结构的生成方法论三步式采样工作流、三种脚本调用 API、约 1.5 万 bulk × 82 吸附物 × 250 万去重后输入的生产规模、决策树路径指纹去重策略以及各版本数据库与校验和。当前 ocp 仓库将这套管线重构为Bulk/Adsorbate/Slab/AdsorbateSlabConfig四个核心类与structure_generator.py命令行入口采样逻辑与底层 pymatgen/ASE 依赖保持延续。无论是复现 OC20 还是构造自定义的吸附物–催化剂数据集本文介绍的流程、参数与源码对应关系都可以直接作为操作与排障依据。【免费下载链接】ocpFAIR Chemistrys library of machine learning methods for chemistry项目地址: https://gitcode.com/GitHub_Trending/oc/ocp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考