fairchem 由 FAIR 化学团队开发

fairchem 是 FAIR 化学团队的集中式存储库，包含了其在材料科学和量子化学领域的所有数据、模型、演示及应用成果。

:warning: FAIRChem 2.0 版本与 1.0 版本相比存在重大变更，不兼容我们之前的预训练模型和代码。 如果您希望使用 1.0 版本中的旧模型或代码，您需要安装 1.0 版本， 具体方法请参见 此处。

[!CAUTION] 使用 OMat24 训练的 UMA 模型以及传统无机块体模型采用的是 DFT 和 DFT+U 总能量标签进行训练。 这些模型与 Materials Project 的计算结果并不兼容。如果您仅将 UMA 或仅基于 OMat24 训练的模型用于此类计算， 可以在 OMat24 Hugging Face 仓库 中找到针对参考单质化合物的 OMat24 特定计算， 以及 MP2020 风格的阴离子和 GGA/GGA+U 混合校正。请勿在使用 OMat24 训练模型时采用 MP2020 校正或 MP 参考化合物。 在计算诸如形成能、相图上能量等能量差值并与 Materials Project 中的计算结果进行比较时，需格外注意， 因为 DFT 假势的不同以及磁性基态可能存在的差异。

最新消息

2026年3月 - UMA-1.2 发布！速度提升约50%，在 Open Molecules 测试集上的准确率提高约40%，并扩展了对催化剂（氧化物和界面）、分子及聚合物的数据覆盖！

2025年10月 - 查看我们的无缝多节点、多 GPU 以及 LAMMPS 接口，以运行大规模动力学模拟！

阅读我们的最新发布文章！

了解关于 UMA 模型和 OMol25 数据集 发布的信息。

体验演示！

如果您想探索模型的功能，请访问我们的 教育演示

安装

尽管不是必需的，但我们强烈建议使用包管理器和虚拟环境来安装，例如 uv，它比单独使用 pip 更快，且在解决依赖关系方面表现更好。

使用 pip 安装 fairchem-core

pip install fairchem-core

如果您希望参与贡献或对代码进行修改，可以克隆仓库并以编辑模式安装：

git clone git@github.com:facebookresearch/fairchem.git

pip install -e fairchem/packages/fairchem-core[dev]

快速入门

使用预训练模型最简单的方式是通过 ASE 的 FAIRChemCalculator。 只需选择适合特定领域预测的任务名称，即可利用单一的 uma 模型完成化学和材料科学中的多种应用。

从预训练模型实例化计算器

请确保您拥有 Hugging Face 账户，并已申请访问 UMA 模型仓库 的权限，同时使用访问令牌登录 Hugging Face。 您可以使用以下命令保存身份验证令牌：

huggingface-cli login

模型通过其名称引用，以下是当前支持的模型：

模型名称	描述
uma-s-1p2	UMA 小型模型的最新版本，在大多数基准测试中仍保持 SOTA 水平，且速度最快（激活参数/总参数：6.6M/290M）
uma-s-1p1	UMA 小型模型的早期版本，同样在大多数基准测试中保持 SOTA 水平（激活参数/总参数：6.6M/150M）
uma-m-1p1	在各项指标上均属一流的 UMA 模型，但速度较慢且内存占用较高（激活参数/总参数：50M/1.4B）

为您的应用设置任务并进行计算

• oc20: 适用于催化领域
• oc22: 仅限 1p2 版本，适用于氧化物催化
• oc25: 仅限 1p2 版本，适用于（电）催化
• omat: 适用于无机材料
• omol: 适用于分子和聚合物
• odac: 适用于 MOF
• omc: 适用于分子晶体

在催化表面上优化吸附物种，

from ase.build import fcc100, add_adsorbate, molecule
from ase.optimize import LBFGS
from fairchem.core import pretrained_mlip, FAIRChemCalculator

predictor = pretrained_mlip.get_predict_unit("uma-s-1p2", device="cuda")
calc = FAIRChemCalculator(predictor, task_name="oc20")

# 将您的体系设置为 ASE atoms 对象
slab = fcc100("Cu", (3, 3, 3), vacuum=8, periodic=True)
adsorbate = molecule("CO")
add_adsorbate(slab, adsorbate, 2.0, "bridge")

slab.calc = calc

# 设置 LBFGS 动力学对象
opt = LBFGS(slab)
opt.run(0.05, 100)

对无机晶体进行弛豫，

from ase.build import bulk
from ase.optimize import FIRE
from ase.filters import FrechetCellFilter
from fairchem.core import pretrained_mlip, FAIRChemCalculator

predictor = pretrained_mlip.get_predict_unit("uma-s-1p2", device="cuda")
calc = FAIRChemCalculator(predictor, task_name="omat")

atoms = bulk("Fe")
atoms.calc = calc

opt = FIRE(FrechetCellFilter(atoms))
opt.run(0.05, 100)

运行分子动力学 (MD)

注意：pretrained_mlip.get_predict_unit() 目前使用一个种子来设置 numpy 随机数生成器的全局状态。为了在每次运行以下代码时获得不同的轨迹，我们需要按照如下方式设置随机种子：

from ase import units
from ase.io import Trajectory
from ase.md.langevin import Langevin
from ase.build import molecule
from fairchem.core import pretrained_mlip, FAIRChemCalculator

seed = np.random.randint(0, np.iinfo(np.int32).max, dtype=int)
predictor = pretrained_mlip.get_predict_unit("uma-s-1p2", device="cuda", seed=seed)
calc = FAIRChemCalculator(predictor, task_name="omol")

atoms = molecule("H2O")
atoms.calc = calc

dyn = Langevin(
    atoms,
    timestep=0.1 * units.fs,
    temperature_K=400,
    friction=0.001 / units.fs,
)
trajectory = Trajectory("my_md.traj", "w", atoms)
dyn.attach(trajectory.write, interval=1)
dyn.run(steps=1000)

计算自旋能隙，

from ase.build import molecule
from fairchem.core import pretrained_mlip, FAIRChemCalculator

predictor = pretrained_mlip.get_predict_unit("uma-s-1p2", device="cuda")

# 单重态 CH2
singlet = molecule("CH2_s1A1d")
singlet.info.update({"spin": 1, "charge": 0})
singlet.calc = FAIRChemCalculator(predictor, task_name="omol")

# 三重态 CH2
triplet = molecule("CH2_s3B1d")
triplet.info.update({"spin": 3, "charge": 0})
triplet.calc = FAIRChemCalculator(predictor, task_name="omol")

triplet.get_potential_energy() - singlet.get_potential_energy()

多 GPU 推理与 LAMMPS

如果您有多块 GPU（或多个节点），我们只需通过一个参数（workers=N）即可在后台为您处理所有并行计算。例如，您可以运行以下包含 8000 个原子的 MD 模拟，性能约为每秒 10 步（使用 8 块 H100 GPU），比单 GPU 推理快约 10 倍！目前的基准测试表明，在真实的 MD 场景中，我们可以以每天约 1 纳秒的速度运行 uma-s 模型，处理超过 10 万个原子的体系（更多内容即将发布）。此功能也兼容 LAMMPS，可用于执行大规模 MD 模拟。有关详细信息，请参阅我们的 文档。这需要安装 Ray 包，并且包含 extras 组件。

pip install fairchem-core[extras]

from ase import units
from ase.md.langevin import Langevin
from fairchem.core import pretrained_mlip, FAIRChemCalculator
import time

from fairchem.core.datasets.common_structures import get_fcc_crystal_by_num_atoms

seed = np.random.randint(0, np.iinfo(np.int32).max, dtype=int)
predictor = pretrained_mlip.get_predict_unit(
    "uma-s-1p2", inference_settings="turbo", device="cuda", workers=8, seed=seed,
)
calc = FAIRChemCalculator(predictor, task_name="omat")

atoms = get_fcc_crystal_by_num_atoms(8000)
atoms.calc = calc

dyn = Langevin(
    atoms,
    timestep=0.1 * units.fs,
    temperature_K=400,
    friction=0.001 / units.fs,
)
# 预热 10 步
dyn.run(steps=10)
start_time = time.time()
dyn.attach(
    lambda: print(
        f"步数: {dyn.get_number_of_steps()}, 能量: {atoms.get_potential_energy():.3f} eV, "
        f"QPS: {dyn.get_number_of_steps()/(time.time()-start_time):.2f}"
    ),
    interval=1,
)
dyn.run(steps=1000)

许可证

fairchem 采用 MIT 许可证。不同应用领域的模型/检查点许可证可能有所不同。

fairchem 快速上手指南

fairchem 是 Meta FAIR Chemistry 团队开源的材料科学与量子化学工具库，集成了最新的数据、模型（如 UMA 系列）及应用接口。本指南将帮助您快速在本地环境中部署并使用预训练模型进行化学计算。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL2 或 Docker)
• Python 版本: 3.10 或更高版本
• GPU 支持: 推荐使用 NVIDIA GPU 并安装对应的 CUDA 驱动（用于加速推理）
• Hugging Face 账号: 访问 UMA 模型仓库 需要注册账号并申请访问权限。

注意：fairchem v2 版本与 v1 不兼容。如果您需要使用旧版模型或代码，请单独安装 v1.10.0 版本。

安装步骤

推荐使用 uv 等现代包管理器以获得更快的依赖解析速度，也可以使用标准的 pip 进行安装。

1. 基础安装

直接通过 pip 安装核心包：

pip install fairchem-core

2. 开发者模式安装（可选）

如果您需要修改源码或贡献代码：

git clone git@github.com:facebookresearch/fairchem.git
pip install -e fairchem/packages/fairchem-core[dev]

3. 启用高级功能（可选）

若需使用多 GPU 并行推理或 LAMMPS 接口，请安装额外依赖包：

pip install fairchem-core[extras]

4. 配置模型访问权限

在使用预训练模型前，需登录 Hugging Face：

huggingface-cli login

请确保您已按照提示输入 Access Token，并且该账号已获得 UMA 模型的访问授权。

基本使用

fairchem 最便捷的用法是通过 FAIRChemCalculator 结合 ASE (Atomic Simulation Environment) 进行调用。您只需选择对应的任务名称（如催化、无机材料、分子等），即可加载预训练的 UMA 模型。

示例：催化表面吸附物弛豫

以下示例演示如何加载 uma-s-1p2 模型，并在铜表面弛豫一个 CO 吸附物。

from ase.build import fcc100, add_adsorbate, molecule
from ase.optimize import LBFGS
from fairchem.core import pretrained_mlip, FAIRChemCalculator

# 1. 加载预训练模型预测单元
# 可选模型：uma-s-1p2 (最快), uma-m-1p1 (精度最高)
predictor = pretrained_mlip.get_predict_unit("uma-s-1p2", device="cuda")

# 2. 初始化计算器，指定任务类型
# 任务选项：oc20 (催化), omat (无机材料), omol (分子), odac (MOFs) 等
calc = FAIRChemCalculator(predictor, task_name="oc20")

# 3. 构建 ASE Atoms 对象
slab = fcc100("Cu", (3, 3, 3), vacuum=8, periodic=True)
adsorbate = molecule("CO")
add_adsorbate(slab, adsorbate, 2.0, "bridge")

slab.calc = calc

# 4. 执行结构弛豫
opt = LBFGS(slab)
opt.run(0.05, 100)

print(f"Final energy: {slab.get_potential_energy()} eV")

其他常见任务速查

• 无机晶体弛豫: 设置 task_name="omat"，配合 FrechetCellFilter 使用。
• 分子动力学 (MD): 设置 task_name="omol"，结合 ase.md.langevin.Langevin 使用。
• 自旋态计算: 在 atoms.info 中设置 spin 和 charge 属性，同样使用 task_name="omol"。

提示：对于大规模系统（如 8000+ 原子）或多 GPU 环境，可在 get_predict_unit 中设置 workers=N 和 inference_settings="turbo" 以显著提升推理速度。