FAIRChem 无机材料入门实战：用 UMA 势函数计算形成能、声子谱与弹性张量-平芜编程栈

FAIRChem 无机材料入门实战：用 UMA 势函数计算形成能、声子谱与弹性张量

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

本篇指南聚焦 FAIRChem（Open Catalyst Project 的机器学习化学工具库）在无机晶体材料领域的三大经典应用：利用预训练 UMA 模型结合 Materials Project（MP）兼容修正计算形成能、运行声子（Hessian）计算预测振动模式与热力学性质、以及通过自动化应变工作流计算弹性常数与体模量。文章以 docs/inorganic_materials/examples_tutorials/ 下的三篇教程为主体，结合fairchem-core的FAIRChemCalculator、FormationEnergyCalculator源码与 OMat24 数据集说明，为你提供可直接复制运行的端到端实战方案。

引言：无机材料性质预测的三个典型任务

无机材料研究通常围绕三个核心问题展开：体系在热力学上是否稳定（形成能）、在有限温度下是否稳定及热输运表现如何（声子谱）、在力学上如何响应形变（弹性张量）。这三个问题分别对应本仓库教程集中的三篇文档：

形成能计算：使用 UMA 模型配合 MP2020 风格修正，预测与 Materials Project 数据库可对比的形成能；
声子计算：通过有限位移法构建 Hessian 矩阵，得到振动模式、熵与有限温度稳定性；
弹性张量计算：基于应变-形变工作流求弹性常数与体模量。

三篇教程共用同一套技术栈：ASE 负责原子结构与优化器，quacc 提供高层工作流 recipe，fairchem-core 提供 ML 势函数（MLIP）的计算接口。下面先讲清这层基础，再逐一展开三个任务。

环境准备：安装 fairchem-core 并获取 UMA 模型访问权限

三篇教程的第一步完全一致，核心是两条：

安装依赖包：fairchem-core提供计算接口，按任务不同还需要数据包（如fairchem-data-omat提供 OMat24 兼容修正，fairchem-data-oc提供 OC 系列数据支持）：

# 形成能任务需要 omat 数据包 ! pip install fairchem-core fairchem-data-omat # 声子与弹性任务需要 oc 数据包与 cattsunami 应用包 ! pip install fairchem-core fairchem-data-oc fairchem-applications-cattsunami

获取 Hugging Face 门控（gated）模型访问权：UMA 系列模型权重托管在 Hugging Face 的facebook/UMA仓库中，需要先完成授权，否则会遇到 permissions/401 错误。步骤为：注册并登录 Hugging Face 账号 → 在facebook/UMA模型页申请访问 → 在设置页创建具有 "Read access to contents of all public gated repos you can access" 权限的 token → 通过命令行登录或设置环境变量完成认证：

# 方式一：命令行交互式登录 ! huggingface-cli login # 方式二：直接设置环境变量（MY_TOKEN 替换为你的真实 token） import os os.environ['HF_TOKEN'] = 'MY_TOKEN'

说明：quacc与ase同样为运行前置条件，教程示例默认这些依赖已就绪。Hugging Face 上可用的 UMA 模型清单由仓库中的 pretrained_models.json 定义，包括uma-s-1p1、uma-s-1p2、uma-s-1p2p1、uma-m-1p1等，本系列教程统一使用uma-s-1p2。

模型加载与计算器体系：FAIRChemCalculator 与 FormationEnergyCalculator

在进入三个任务之前，理解 fairchem-core 的计算器抽象很有必要，因为三篇教程的底层都由它驱动。

从模型名到预测单元：`from_model_checkpoint`

ase_calculator.py 中定义的FAIRChemCalculator是一个标准的 ASECalculator子类，核心入口是类方法from_model_checkpoint：

传入name_or_path（模型名或本地 checkpoint 路径）。若为模型名，则经 pretrained_mlip.py 中的get_predict_unit从 Hugging Face 下载权重（缓存目录默认~/.cache/fairchem），同时自动拉取两类参考能量文件——atom_refs（孤立原子参考能，用于单原子体系）与form_elem_refs（形成能元素参考，用于形成能计算）；
task_name决定预测头与能量键名，可选值在源码中明确为'omol'、'omat'、'oc20'、'odac'、'omc'之一（见 ase_calculator.py）。当模型对应多个数据集任务时必须显式指定，否则抛出RuntimeError；
inference_settings支持"default"、"turbo"（额外启用 TF32）、"batch"等字符串快捷配置，也可传入自定义InferenceSettings对象；
计算器内部通过AtomicData.from_ase完成 ASE Atoms 到图数据的转换，默认半径 6.0 Å、最大邻居 300（外部构图模式），并在calculate中把能量、力、应力、Hessian 等结果写入self.results。

计算器的使用方式

教程中形成能部分给出了两种用法：

经 quacc recipe 做结构弛豫（relax_job），拿到弛豫后的atoms；
直接构造计算器做单点计算：

calculator = FAIRChemCalculator.from_model_checkpoint("uma-s-1p2", task_name="omat") atoms.calc = calculator energy = atoms.get_potential_energy()

FAIRChemCalculator通过implemented_properties暴露模型支持的性质（energy/forces/stress/hessian 等），其中free_energy是energy的副本，用于兼容 ASE 中硬编码读取该键的优化器/例程（见 ase_calculator.py 的 docstring 说明）。

FormationEnergyCalculator：形成能的包装器

FormationEnergyCalculator（ase_calculator.py）是形成能任务的"最后一公里"。它的calculate流程清晰：

先调用被包装的基础计算器得到总能量；
若apply_corrections=True（对omat任务默认开启），调用fairchem.data.omat.entries.compatibility.apply_mp_style_corrections施加 MP 风格能量修正——该函数把 ASE Atoms 转成 pymatgenComputedStructureEntry，再交给OMat24Compatibility（继承自 pymatgen 的MaterialsProject2020Compatibility，但默认配置指向 OMat24 专用修正文件，见 compatibility.py）处理；
按化学式统计各元素数量，用element_references（来自predictor.form_elem_refs[task_name]）计算参考总能total_ref_energy；
形成能 =total_energy - total_ref_energy。

元素参考能缺失时会抛出ValueError: Missing reference energies for elements: ...明确告警。

任务一：形成能计算（Formation Energy）

计算原理与背景

用仅在 OMat24 上训练的模型预测形成能时，必须使用 OMat24 兼容的参考能与修正，以弥合 PBE 与 PBE+U 两类 DFT 计算混用带来的系统性偏差。本仓库采用拟合自 OMat24 DFT 计算的 MP2020 风格修正，即 Materials Project 的阴离子/GGA-GGA+U 混用方案。实现修正所需的数据与代码位于fairchem.data.omat包中：

修正数值表见 OMat24Compatibility.yaml：包括对过渡金属氧化物/氟化物（V、Cr、Mn、Fe、Co、Ni、W、Mo）的 GGA+U 混用修正（如 Fe 的 O 键合修正 -2.428 eV/atom），以及按阴离子分类的组分修正（oxide -0.657、peroxide -0.433、S -0.487、Cl -0.6 等），并附对应不确定度；
修正引擎见 compatibility.py 的apply_mp_style_corrections，支持correction_type="MP2020"或"OMat24"两种风格。

完整实战代码

from __future__ import annotations import pprint from ase.build import bulk from ase.optimize import FIRE from quacc.recipes.mlp.core import relax_job from quacc import flow from fairchem.core.calculate import FAIRChemCalculator, FormationEnergyCalculator # 构造一个体相 Cu 的 Atoms 对象 atoms = bulk("Cu") # 运行结构弛豫（含晶胞与原子位置） @flow def relax_flow(*args, **kwargs): return relax_job(*args, **kwargs) result = relax_flow( atoms, method="fairchem", name_or_path="uma-s-1p2", task_name="omat", relax_cell=True, opt_params={"fmax": 1e-3, "optimizer": FIRE}, ) # 取出弛豫后的 atoms atoms = result["atoms"] # 用 uma-s-1p2 创建计算器 calculator = FAIRChemCalculator.from_model_checkpoint("uma-s-1p2", task_name="omat") # 用 FormationEnergyCalculator 计算形成能 # 对 omat 任务，默认施加 MP2020 风格修正以兼容 OMat24 form_e_calc = FormationEnergyCalculator(calculator, apply_corrections=True) atoms.calc = form_e_calc form_energy = atoms.get_potential_energy()

关键参数说明：

参数	取值	含义
`method`	`"fairchem"`	指定 quacc 使用 fairchem 的 MLIP 后端
`name_or_path`	`"uma-s-1p2"`	使用的预训练模型名（也可填本地 checkpoint 路径）
`task_name`	`"omat"`	任务名，决定能量头与参考能来源
`relax_cell`	`True`	弛豫时同时优化晶胞（cell）与原子位置
`opt_params`	`{"fmax": 1e-3, "optimizer": FIRE}`	优化器收敛力阈值（eV/Å）与优化器类型（FIRE）

结果输出与对照：

pprint.pprint(f"Total energy: {result['results']['energy']} eV \n Formation energy {form_energy} eV")

result["results"]["energy"]是弛豫后的总能量（eV），form_energy是经元素参考与 MP 风格修正后的形成能（eV）。教程以 MgO（bulk("MgO")）为例，给出 Materials Project 中约 -3.038 eV/atom 的参考值（mp-1265 体系）作为对照。**注意：**由于 OMat24 训练数据采用的 DFT 设置与 MP 数据库不同，两者存在预期内的数值差异，应对比量级而非逐位相等。

任务二：声子计算（Phonon Calculations）

声子计算的意义

声子计算对无机材料科学至关重要，主要用于：

计算热导率；
理解材料的振动模式，进而得到熵与自由能；
预测材料在有限温度（如 300 K）下的稳定性。

有限位移法的工作流

教程中的phonon_flow采用标准有限位移法（finite displacement），完整流程共七步：

对晶胞与原子执行弛豫；
将原胞重复若干次放大到足够大的超胞，以捕获足够多的振动模式；
沿各方向微小平移每个原子，生成一系列有限位移结构；
对每个位移结构做单点能量/力计算；
汇总所有计算，通过数值二阶差分构建Hessian 矩阵；
对 Hessian 求特征值/特征向量，得到体系的振动模式（声子色散）；
基于振动模式分析热力学性质（熵、自由能等）。

前提假设：该分析假定所有振动模式是**简谐（harmonic）**的。这对低/中温材料是相当合理的近似，但在高温下会逐渐偏离实际。

完整实战代码

from __future__ import annotations from ase.build import bulk from quacc.recipes.mlp.phonons import phonon_flow # 构造一个体相 Cu 的 Atoms 对象 atoms = bulk("Cu") # 用 MLIP 势函数运行声子（Hessian）计算 result = phonon_flow( atoms, method="fairchem", job_params={ "all": dict( name_or_path="uma-s-1p2", task_name="omat", ), }, min_lengths=10.0, # 设置最小晶胞尺寸（此处为兼容有限的 GitHub runner 内存而调小） )

参数说明：

参数	取值	含义
`method`	`"fairchem"`	使用 fairchem MLIP 后端
`job_params["all"]`	`dict(name_or_path="uma-s-1p2", task_name="omat")`	对流水线中所有子任务统一指定模型与任务名
`min_lengths`	`10.0`	超胞各方向最小边长（Å）；调小可降低内存/算力开销，但会牺牲部分长波模式分辨率

结果解读：

print( f'The entropy at { result["results"]["thermal_properties"]["temperatures"][-1]:.0f} K is { result["results"]["thermal_properties"]["entropy"][-1]:.2f} kJ/mol' )

result["results"]["thermal_properties"]包含按温度网格展开的热力学性质：temperatures（温度数组）与entropy（对应熵值，kJ/mol）。此外phonon_flow的结果还包含声子模式/频率信息，可用于进一步分析有限温度稳定性或热导率。

任务三：弹性张量计算（Elastic Tensors）

弹性性质的意义

弹性性质回答"材料有多强、多容易形变"以及"在特定方向被压缩或拉伸时如何响应（如泊松比 Poisson ratio）"等问题。在 DFT 中，弹性常数计算通常相当耗时，而 MLIP 工作流可显著加速。

应变-形变工作流

教程使用 quacc 内置的elastic_tensor_flowrecipe，其流程为：

（可选）用 MLIP 弛豫晶胞；
施加应变生成若干形变晶胞；
对每个形变结构，用 MLIP 执行弛豫并（可选）做单点计算；
汇总全部计算，拟合得到材料的弹性性质（弹性常数张量、体模量等）。

该 recipe 的详细文档位于 quacc 的quacc.recipes.mlp.elastic_tensor_flow参考页（对应 quacc 源码中的quacc/recipes/mlp/elastic.py）。

完整实战代码

from __future__ import annotations from ase.build import bulk from quacc.recipes.mlp.elastic import elastic_tensor_flow # 构造一个体相 Cu 的 Atoms 对象 atoms = bulk("Cu") # 用 MLIP 势函数运行弹性性质计算 result = elastic_tensor_flow( atoms, job_params={ "all": dict( method="fairchem", name_or_path="uma-s-1p2", task_name="omat", ), }, )

注意：与声子任务不同，弹性任务把method="fairchem"放在job_params["all"]内部，两种写法效果一致——均为对该流水线的所有子任务统一指定 MLIP 后端、模型名与任务名。

结果解读：

result["elasticity_doc"].bulk_modulus

result["elasticity_doc"]是包含完整弹性信息的文档对象，.bulk_modulus给出体模量（bulk modulus），此外通常还可提取弹性常数张量C_ij、剪切模量等，用于评估材料的可压缩性与形变响应。

三个任务的共性要点与源码佐证

为什么使用 UMA 模型

UMA（Universal Materials Acceptor）是本仓库fairchem.core.models.uma模块下的主干模型系列，其小尺寸配置（K4L2 结构，4 层、128 隐藏通道、球面通道 128、lmax/mmax=2、截止半径由cutoff_radius控制）见 K4L2.yaml。本系列教程统一使用uma-s-1p2checkpoint，其权重、孤立原子参考能（iso_atom_elem_refs.yaml）与形成能元素参考（form_elem_refs.yaml）均从 Hugging Face 拉取（见 pretrained_models.json）。

任务名（task_name）的约定

三个任务统一使用task_name="omat"，其含义包括：

选择 UMA 模型的 omat 预测头，决定能量/力/应力的输出键名；
选择 OMat24 的元素参考能（form_elem_refs）用于形成能换算；
触发 OMat24 兼容修正（FormationEnergyCalculator对 omat 任务默认apply_corrections=True）。

若任务名非法或缺失，FAIRChemCalculator会分别抛出ValueError或RuntimeError并列出可选任务名（见 ase_calculator.py）。

结果传递模式

三个 recipe 都遵循同样的结果结构：result["results"]存放标量/数组性质（如energy、thermal_properties、elasticity_doc），result["atoms"]存放（弛豫后的）结构。这种统一约定让用户可以用几乎相同的代码骨架切换任务。

深入阅读：OMat24 数据集与相关资源

形成能与弹性任务依赖的 OMat24 是 UMA 模型的无机材料训练数据。其关键事实（详见 omat24.md）：

规模：训练集 1.07M 结构，验证集 1.02M 结构；
领域：无机体相材料；
标签：总能（eV）、力（eV/Å）、应力（eV/Å³）；
理论级别：DFT（PBE/PBE+U）；
基准兼容：与 Matbench-Discovery 基准测试集完全兼容（拆分不包含 WBM 数据集初始/弛豫结构中带有 protostructure 标签的结构）；
子数据集构成：rattled-1000/500/300（含 subsampled 变体）、aimd-from-PBE-1000/3000 的 NPT/NVT 轨迹、rattled-relax，共 10 余个子集；
读取方式：数据以AseLMDBDatabase（ASE DB 的 LMDB 实现）存储，可用fairchem.core.datasets.AseDBDataset按索引读取 Atoms 对象，也支持传入路径列表一次读取多个子集；
另有用于微调的 sAlex 数据集（Matbench-Discovery 兼容的 Alexandria 子采样版本）。

其他可深入阅读的仓库资源：

UMA 概述文档与 UMA 变更日志；
UMA 常见问题；
Matbench-Discovery 基准配置；
无机材料数据集总览；
无机材料教程索引。

结语

至此，你已完成 FAIRChem + UMA 在无机材料领域的三个经典实战：形成能（弛豫 + MP 风格修正）、声子谱（有限位移法 Hessian + 热力学性质）、弹性张量（应变工作流 + 体模量）。三者共用同一套 ASE/quacc/fairchem 技术栈，仅需替换 quacc 的 recipe 即可快速迁移，适合作为高通量无机材料性质筛选（与 Matbench-Discovery 等基准对标）的起点。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

FAIRChem 无机材料入门实战：用 UMA 势函数计算形成能、声子谱与弹性张量