基于 UMA 预训练模型与 ODAC 数据集的 MOF 吸附能计算刚性框架与柔性形变分解实战指南【免费下载链接】ocpFAIR Chemistrys library of machine learning methods for chemistry项目地址: https://gitcode.com/GitHub_Trending/oc/ocp本指南以 FAIR Chemistry 开源仓库中 docs/dac/examples_tutorials/adsorption_energy.md 为核心教程系统讲解如何使用预训练的 UMA 通用势能模型通过FAIRChemCalculator计算金属有机框架MOF中 CO₂ 与 H₂O 的吸附能并深入处理 MOF 柔性导致的框架形变问题。读完本文你将掌握吸附能的严格定义、刚性框架下的单点能计算流程以及柔性框架下空 MOF 再弛豫与吸附能分解相互作用能 形变能的完整方法论并理解其背后的 ASE 计算器实现原理。一、吸附能的物理定义与 ODAC 数据集背景预训练的 ODAC 系列模型在各类 MOF 相关任务中具有很强的通用性。最基础也最具代表性的应用就是计算单个 CO₂ 分子在 MOF 结构中的吸附能。对于吸附能$E_{\mathrm{ads}}$其定义为吸附复合体系与各组分独立弛豫结构之间的能量差$$ E_{\mathrm{ads}} E_{\mathrm{MOFCO2}} - E_{\mathrm{MOF}} - E_{\mathrm{CO2}} \tag{1}$$其中等式右侧的每一项都代表对应化学体系在弛豫relaxed状态下的能量。该方法的完整技术细节可参见 OpenDAC 项目的方法学论文ACS Central Science, 2023, DOI: 10.1021/acscentsci.3c01629。ODAC23 / ODAC25 数据集要点docs/dac/datasets/odac23.md约 100 万条结构S2EF、约 1 万条结构IS2RE面向 CO₂ 吸附的 MOF 体系标签为总能量eV与原子力eV/Å理论级别为 VASP 实现的 PBED3许可协议为 CC BY 4.0。注意该数据集现已标记为Deprecated。docs/dac/datasets/odac25.md包含近 7000 万条 DFT 单点计算覆盖 CO₂、H₂O、N₂、O₂ 四种吸附质在近 1.5 万个 MOF 中的吸附理论级别同为 PBED3VASP是官方推荐的替代数据集。在 ODAC23 数据集中所有 MOF 结构都以其 CSDCambridge Structural Database代码标识例如 Mg-MOF-74 的 CSD 代码为OPAGIX。二、环境准备与预训练模型加载1. 安装依赖包首先安装 fairchem 核心包及配套的数据与工具包可使用 pip、uv 等工具! pip install fairchem-core fairchem-data-oc fairchem-applications-cattsunami2. 获取 UMA 门控模型访问权限UMA 模型权重托管在 Hugging Face 的facebook/UMA门控仓库中需要按以下步骤获取访问权限注册并登录 Hugging Face 账号在facebook/UMA模型页面申请访问权限在 Hugging Face 的 token 设置页面创建访问令牌权限选择 Permissions: Read access to contents of all public gated repos you can access通过huggingface-cli login或设置HF_TOKEN环境变量将令牌写入环境# 使用 huggingface-cli 登录 ! huggingface-cli login # 或者直接设置环境变量 import os os.environ[HF_TOKEN] MY_TOKEN如果忽略这一步加载模型时会遇到 permissions/401 错误。3. 加载预训练模型与 ASE 计算器预训练模型可以通过FAIRChemCalculator加载。在本教程中我们使用 UMA 模型来计算 CO₂ 吸附能from fairchem.core import FAIRChemCalculator, pretrained_mlip predictor pretrained_mlip.get_predict_unit(uma-s-1p2) calc FAIRChemCalculator(predictor, task_nameodac)这里有两个关键点值得展开其一uma-s-1p2是仓库官方注册的预训练模型名。在 src/fairchem/core/calculate/pretrained_models.json 中可以看到uma-s-1p2对应 Hugging Face 仓库facebook/UMA下的checkpoints/uma-s-1p2.pt并附带references/iso_atom_elem_refs.yaml原子参考能与references/form_elem_refs.yaml元素参考能。pretrained_mlip.get_predict_unit()实现在 src/fairchem/core/calculate/pretrained_mlip.py会从 Hugging Face 下载权重与参考能量文件到本地缓存目录然后通过load_predict_unit构建预测单元。其二task_nameodac指定了 UMA 的 MoLEMixture-of-Linear-Experts路由所需的 DFT 理论级别。根据 docs/core/uma.mdUMA 在不同数据集上训练了对应不同 DFT 理论级别的任务嵌入推理时必须显式指定其一omolwB97M-V/ORCA6、omatPBE/PBEU、oc20RPBE、odacPBED3/VASP、omcPBED3、oc25RPBED3、oc22PBEU。对于直接空气捕集DAC、碳捕集与封存、CO₂ 转化等应用应选择odac。UMA 的 odac 任务在训练时未见变化的电荷与自旋多重度模型输入固定为total_charge0、spin multiplicity0。三、刚性 MOF 中的 CO₂ 吸附Mg-MOF-74OPAGIX让我们将上述知识应用到 Mg-MOF-74——一种被广泛研究、以优异 CO₂ 吸附性能著称的 MOF。其结构由镁原子配合物与羧基化氧化苯环有机连接体构成。已有研究一致报道 Mg-MOF-74 的 CO₂ 吸附能约为-0.40 eV见文献 Chem. Sci., 2014, DOI: 10.1039/C4SC02064BChem. Sci., 2013, DOI: 10.1039/C3SC51319JJ. Phys. Chem. C, 2018, DOI: 10.1021/acs.jpcc.8b00938。我们的目标是验证仅使用 UMA 做一次简单的单点能计算能否复现接近该文献值的吸附能。教程从 ODAC23 数据集中提取了一个具体的OPAGIXCO2构型该构型在同类结构中吸附能最低仓库中对应的结构文件位于 docs/dac/examples_tutorials/structures/ 目录OPAGIX_w_CO2.cif吸附了 CO₂ 的 Mg-MOF-74 复合体系OPAGIX.cif空的 Mg-MOF-74co2.xyz孤立的 CO₂ 分子。先用 ASE 读取并可视化复合结构import matplotlib.pyplot as plt from ase.io import read from ase.visualize.plot import plot_atoms mof_co2 read(structures/OPAGIX_w_CO2.cif) mof read(structures/OPAGIX.cif) co2 read(structures/co2.xyz) fig, ax plt.subplots(figsize(5, 4.5), dpi250) plot_atoms(mof_co2, ax) ax.set_axis_off()计算吸附能的最后一步是把FAIRChemCalculator分别挂接到三个弛豫结构OPAGIXCO2、OPAGIX、CO2上。教程使用的结构已由 ODAC23 数据集完成弛豫为简化起见此处假设可以忽略进一步的弛豫下一节将展示如何突破这一假设mof_co2.calc calc mof.calc calc co2.calc calc E_ads ( mof_co2.get_potential_energy() - mof.get_potential_energy() - co2.get_potential_energy() ) print(fAdsorption energy of CO2 in Mg-MOF-74: {E_ads:.3f} eV)这里atoms.calc calc是 ASE 的标准用法将计算器赋给Atoms对象后get_potential_energy()会触发FAIRChemCalculator.calculate()把 ASE 原子结构转换为图数据并执行模型推理详见下文源码分析。四、柔性 MOF 中的吸附为什么需要额外步骤上述方法通常假设 MOF 是刚性的以简化计算。但实验与建模文献均表明MOF 柔性对准确刻画吸附化学至关重要特别是将 MOF 视为柔性体可以提升吸附容量。柔性可以分成两类固有柔性intrinsic flexibility与吸附质分子诱导的形变deformation induced by guest molecules。在 Open DAC 项目中考虑的是后者——在几何优化过程中允许 MOF 原子位置弛豫。下图展示了 CSD 代码为 WOBHEB 的 MOF 在加入缺陷后WOBHEB_0.11_0从 DFT 模拟中得到的水吸附情形。一个典型的吸附能计算只捕获紫色阴影部分——主体与客体之间的化学吸附与非键相互作用而当允许 MOF 弛豫时吸附能还包含绿色阴影标出的 MOF 形变能。为了把形变纳入考量式 (1) 中空 MOF 项必须使用能量最有利的 MOF 几何构型。将 MOF 原子坐标作为自由度后可能出现三种结果MOF 不发生形变弛豫后的空 MOF 与吸附态中 MOF 的能量相同MOF 形变为比其基态能量更不利的几何构型MOF 找到比空 MOF 弛豫结果能量更有利的新几何构型。第一种结果无需额外计算因为刚性假设成立。第二种结果代表物理上可逆的形变——移除客体分子后 MOF 会恢复到空的基态。第三种结果通常是客体分子打破了局部对称性所致。在 ODAC 数据集中还发现了同一 MOF 内同时出现结果 2 与结果 3 的情况。为保证找到能量最有利的空 MOF 几何构型应在 MOF吸附质弛豫之后额外执行一次空 MOF 弛豫移除客体分子从吸附态几何出发重新弛豫 MOF。如果所有形变都是可逆的MOF 会回到原始空几何构型否则应取能量最低最有利的 MOF 几何构型作为式 (1) 中的参考能量 $E_{\mathrm{MOF}}$。五、实例用 UMA 计算柔性 WOBHEB 中的 H₂O 吸附能教程的第一部分演示了如何使用 UMA 做单点吸附能计算。为了把 MOF 当作柔性体处理这里所有计算都基于几何优化得到的构型。以下示例对应上节图中所示的情形H₂O 在WOBHEB_0.11_0中的吸附。记号约定$E_{x}(r_{y})$ 表示由 $y$ 的几何优化确定的 $x$ 的能量。第 1 步弛豫空 MOF得到 $E_{\mathrm{MOF}}(r_{\mathrm{MOF}})$import ase.io from ase.optimize import BFGS mof ase.io.read(structures/WOBHEB_0.11.cif) mof.calc calc relax BFGS(mof) relax.run(fmax0.05) E_mof_empty mof.get_potential_energy() print(fEnergy of empty MOF: {E_mof_empty:.3f} eV)对应的初始结构文件为 WOBHEB_0.11.cif。BFGS是 ASE 内置的几何优化器fmax0.05表示力收敛阈值eV/Å弛豫过程中每一步都会调用calc计算能量与原子力——这正是 UMA 提供力预测的意义所在。第 2 步弛豫 MOF 吸附质得到 $E_{\mathrm{MOFH2O}}(r_{\mathrm{MOFH2O}})$mof_h2o ase.io.read(structures/WOBHEB_H2O.cif) mof_h2o.calc calc relax BFGS(mof_h2o) relax.run(fmax0.05) E_combo mof_h2o.get_potential_energy() print(fEnergy of MOF H2O: {E_combo:.3f} eV)对应的复合结构文件为 WOBHEB_H2O.cif。第 3 步从吸附态几何中分离 MOF得到 $E_{\mathrm{MOF}}(r_{\mathrm{MOFH2O}})$现在从弛豫后的 MOFH₂O 几何中隔离出 MOF 原子mof_h2o[:-3]即去掉末尾 3 个水分子原子。可以看到MOF 采纳了一个比空 MOF 能量高约 0.2 eV 的几何构型mof_adsorbed_state mof_h2o[:-3] mof_adsorbed_state.calc calc E_mof_adsorbed_state mof_adsorbed_state.get_potential_energy() print(fEnergy of MOF in the adsorbed state: {E_mof_adsorbed_state:.3f} eV)吸附态中 MOF 能量升高说明该体系对应前述结果 2吸附质诱导的可逆形变。第 4 步从 $r_{\mathrm{MOFH2O}}$ 几何出发重新弛豫空 MOFrelax BFGS(mof_adsorbed_state) relax.run(fmax0.05) E_mof_rerelax mof_adsorbed_state.get_potential_energy() print(fEnergy of re-relaxed empty MOF: {E_mof_rerelax:.3f} eV)MOF 在重新弛豫后回到了原始空参考能量证实该形变在物理上是真实的、由吸附质分子诱导的。对于结果 3这个重新弛豫能量会比原始空 MOF 弛豫更负更有利。因此式 (1) 中的空 MOF 参考能量取原始空 MOF 能量与重新弛豫 MOF 能量中的较小值E_mof min(E_mof_empty, E_mof_rerelax) # 获取吸附质参考能量 h2o mof_h2o[-3:] h2o.calc calc E_h2o h2o.get_potential_energy() # 计算吸附能 E_ads E_combo - E_mof - E_h2o print(fAdsorption energy of H2O in WOBHEB_0.11_0: {E_ads:.3f} eV)该吸附能与 DFT 结果-0.699 eV高度吻合。这一强吸附能同时来自 H₂O 的化学吸附与 MOF 形变下面我们将其分解为两个贡献。六、吸附能分解相互作用能 $E_{\mathrm{int}}$ 与形变能 $E_{\mathrm{MOF,deform}}$在假设 H₂O 分子刚性的前提下分别定义相互作用能 $E_{\mathrm{int}}$ 与 MOF 形变能 $E_{\mathrm{MOF,deform}}$$$ E_{\mathrm{int}} E_{\mathrm{MOFH2O}}(r_{\mathrm{MOFH2O}}) - E_{\mathrm{MOF}}(r_{\mathrm{MOFH2O}}) - E_{\mathrm{H2O}}(r_{\mathrm{MOFH2O}}) \tag{2}$$$$ E_{\mathrm{MOF,deform}} E_{\mathrm{MOF}}(r_{\mathrm{MOFH2O}}) - E_{\mathrm{MOF}}(r_{\mathrm{MOF}}) \tag{3}$$其中 $E_{\mathrm{int}}$ 描述的是吸附态 MOF 构型下主体-客体间的相互作用即吸附态几何下的纯吸附贡献$E_{\mathrm{MOF,deform}}$ 量化吸附态 MOF 与按本文工作流得到的能量最有利空 MOF 几何之间的形变幅度。可以证明$$ E_{\mathrm{ads}} E_{\mathrm{int}} E_{\mathrm{MOF,deform}} \tag{4}$$对WOBHEB_0.11中的 H₂O 吸附用代码验证如下E_int E_combo - E_mof_adsorbed_state - E_h2o print(fE_int: {E_int})E_mof_deform E_mof_adsorbed_state - E_mof_empty print(fE_mof_deform: {E_mof_deform})E_ads E_int E_mof_deform print(fE_ads: {E_ads})关键结论$E_{\mathrm{int}}$ 在 MOF 被假定为刚性时与 $E_{\mathrm{ads}}$ 等价。在本例中如果忽略吸附质诱导的形变将高估吸附能的大小绝对值偏大这正是柔性 MOF 吸附能计算必须引入形变校正的根本原因。七、源码级原理FAIRChemCalculator 如何工作FAIRChemCalculator的核心实现在 src/fairchem/core/calculate/ase_calculator.py它是 ASECalculator的子类本质上是MLIPPredictUnit的便捷封装。构造与任务校验构造时传入predict_unit预测单元与task_name。若task_name不在预测单元支持的dataset_to_tasks键集合内会抛出ValueError若预测单元只支持单一数据集可省略task_name否则必须显式指定。task_name的合法取值在 docs/core/common_tasks/ase_calculator.md 中列明omol、omat、oc20、odac、omc等。教程中的odac即对应此处的任务名。计算器通过AtomicData.from_ase内部封装为a2g偏函数把 ASE 结构转换为图数据图构建参数包括边半径默认 6.0 Å、邻居上限外部图生成时为 300等。计算与结果键calculate()中主要做了四件事校验输入空体系natoms0、零晶胞 PBC 等非法输入会抛出异常调用predictor.validate_atoms_data与Calculator.calculate处理 ASE 缓存与系统变更检测将Atoms经a2g转换为AtomicData并调用predictor.predict(data)批量推理把预测结果写入self.resultsenergy同时复制到free_energy供部分硬编码使用free_energy的 ASE 优化器/例程调用、forces、stressVoigt 六分量形式、hessian。一个值得注意的细节implemented_properties由预测单元对应任务的属性决定并总是追加free_energy。此外对于未训练 force/stress/hessian 头的任务可以通过InferenceSettings中的predict_untrained_*开关启用基于自动微分的梯度量预测。推理模式与性能选项pretrained_mlip.get_predict_unit()支持inference_settings参数详见 src/fairchem/core/calculate/pretrained_mlip.pydefaultmerge_mole compile快速路径TF32 关闭要求多次评估间体系组成、任务、电荷、自旋保持不变否则自动回退到非合并、非编译路径turbo与 default 相同的快速路径并额外启用 TF32在兼容硬件上提速但牺牲少量精度batch适合组成/任务/电荷/自旋异构的批量输入保持 MOLE 不合并、不编译。对系统规模较大如 1000 原子的预测可开启activation_checkpointing节省显存execution_modeumas-fast-gpu可对 uma-s 系列模型带来额外提速。这些选项与本教程的单点能/弛豫场景结合使用可以在保持精度的同时显著提升吞吐。八、总结与延伸阅读本文完整复现了从刚性 MOF 单点吸附能计算到柔性 MOF 形变校正的完整工作流先以 Mg-MOF-74OPAGIX验证 CO₂ 吸附能的单点计算方法再以 WOBHEB 的 H₂O 吸附为例展示空 MOF 再弛豫策略与吸附能分解$E_{\mathrm{ads}} E_{\mathrm{int}} E_{\mathrm{MOF,deform}}$最后从源码层面剖析了FAIRChemCalculator的内部机制。本教程由 Logan Brabson 与 Sihoon ChoiGeorgia Tech以及 OpenDAC 项目贡献。建议进一步阅读仓库内以下资料数据集说明docs/dac/datasets/odac23.md、docs/dac/datasets/odac25.md模型选择建议docs/dac/models.mdCO₂/H₂O 吸附推荐 UMAN₂/O₂ 吸附推荐基于 ODAC25 训练的 eSEN 模型UMA 任务与理论级别对照表docs/core/uma.mdASE 计算器与推理设置详解docs/core/common_tasks/ase_calculator.md计算器实现源码src/fairchem/core/calculate/ase_calculator.py配套测试见 tests/core/calculate/test_ase_calculator.py。【免费下载链接】ocpFAIR Chemistrys library of machine learning methods for chemistry项目地址: https://gitcode.com/GitHub_Trending/oc/ocp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考