MatterSim 是一种跨元素、温度和压力的深度学习原子级模型。

文档

本 README 提供快速入门指南。如需更全面的信息，请参阅 MatterSim 文档。

安装

先决条件

• Python >= 3.10

从 PyPI 安装

[!TIP] 虽然不是强制要求，但我们建议在安装 MatterSim 之前创建一个干净的 conda 环境，以避免潜在的包冲突。您可以通过以下命令创建并激活 conda 环境：

# 创建环境
conda create -n mattersim python=3.10

# 激活环境
conda activate mattersim

要安装 MatterSim，请使用以下命令。请注意，下载依赖项可能需要一些时间：

pip install mattersim

如果您希望安装最新版本的软件包，可以运行以下命令：

pip install git+https://github.com/microsoft/mattersim.git

从源代码安装

1. 下载 MatterSim 的源代码并切换到该目录

git clone git@github.com:microsoft/mattersim.git
cd mattersim

2. 安装 MatterSim

[!WARNING] 我们强烈建议用户使用 mamba 或 micromamba 来安装 MatterSim，因为在解析 environment.yaml 中的依赖关系时，conda 的速度可能会显著变慢。

要安装软件包，请在文件夹根目录下运行以下命令：

mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .

预训练模型

我们目前在 pretrained_models 文件夹中提供了两个基于 M3GNet 架构的预训练 MatterSim-v1 模型：

1. MatterSim-v1.0.0-1M：模型的迷你版本，运行速度更快。
2. MatterSim-v1.0.0-5M：模型的较大版本，精度更高。

这些模型是使用在 MatterSim 论文 中介绍的工作流程生成的数据进行训练的，该论文深入解释了 MatterSim 模型背后的方法论。

更多高级且完全支持的 MatterSim 预训练版本以及额外的材料功能，可在 Azure Quantum Elements 中获得。

使用

[!TIP] macOS 用户注意： 如果您使用的是搭载 Apple Silicon 的 macOS，请注意 MPS 后端可能存在数值不稳定性。为避免这些问题，我们建议在 Mac 上使用 CPU 设备运行 MatterSim。

一个最小测试

import torch
from loguru import logger
from ase.build import bulk
from ase.units import GPa
from mattersim.forcefield import MatterSimCalculator

device = "cuda" if torch.cuda.is_available() else "cpu"
logger.info(f"Running MatterSim on {device}")

si = bulk("Si", "diamond", a=5.43)
si.calc = MatterSimCalculator(device=device)
logger.info(f"Energy (eV)                 = {si.get_potential_energy()}")
logger.info(f"Energy per atom (eV/atom)   = {si.get_potential_energy()/len(si)}")
logger.info(f"Forces of first atom (eV/A) = {si.get_forces()[0]}")
logger.info(f"Stress[0][0] (eV/A^3)       = {si.get_stress(voigt=False)[0][0]}")
logger.info(f"Stress[0][0] (GPa)          = {si.get_stress(voigt=False)[0][0] / GPa}")

在此版本中，我们提供了两个检查点：MatterSim-v1.0.0-1M.pth 和 MatterSim-v1.0.0-5M.pth。默认加载的是 1M 版本。要切换到 5M 版本，可手动设置 MatterSimCalculator 的 load_path，如下所示：

MatterSimCalculator(load_path="MatterSim-v1.0.0-5M.pth", device=device)

微调

[!TIP] MatterSim 提供了一个微调脚本，可用于在自定义数据集上对预训练的 MatterSim 模型进行微调。有关详细信息，请参阅 MatterSim 文档。

一个最小的微调示例

torchrun --nproc_per_node=1 src/mattersim/training/finetune_mattersim.py --load_model_path mattersim-v1.0.0-1m --train_data_path tests/data/high_level_water.xyz

参考文献

我们恳请使用 MatterSim 1.0.0 版本的用户引用我们在 arXiv 上发布的预印本：

@article{yang2024mattersim,
      title={MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures},
      author={Han Yang and Chenxi Hu and Yichi Zhou and Xixian Liu and Yu Shi and Jielan Li and Guanzhi Li and Zekun Chen and Shuizhou Chen and Claudio Zeni and Matthew Horton and Robert Pinsler and Andrew Fowler and Daniel Zügner and Tian Xie and Jake Smith and Lixin Sun and Qian Wang and Lingyu Kong and Chang Liu and Hongxia Hao and Ziheng Lu},
      year={2024},
      eprint={2405.04967},
      archivePrefix={arXiv},
      primaryClass={cond-mat.mtrl-sci},
      url={https://arxiv.org/abs/2405.04967},
      journal={arXiv preprint arXiv:2405.04967}
}

[!IMPORTANT] 我们恳请用户在学术论文或技术报告中报告结果时，明确指定确切的模型版本和检查点（例如 MatterSim-v1.0.0-1M），而不是笼统地称其为 MatterSim。精确的版本控制对于确保结果的可重复性至关重要。例如，“本研究使用 MatterSim-v1.0.0-1M 进行”就是一个很好的例子。

局限性

MatterSim-v1 专门设计用于块体材料的原子级模拟。超出此范围的应用或解释应谨慎对待。例如，当使用该模型进行涉及表面、界面或受长程相互作用影响的性质的模拟时，结果可能在定性上准确，但不适合定量分析。在这种情况下，我们建议对该模型进行微调，使其更好地适应具体应用。

商标

本项目可能包含项目、产品或服务的商标或标识。
对微软商标或标识的授权使用须遵守并严格执行微软商标与品牌指南。
在本项目的修改版本中使用微软商标或标识时，不得造成混淆或暗示微软的赞助关系。
任何第三方商标或标识的使用均应遵循该第三方的相关政策。

负责任的人工智能透明度文档

负责任的人工智能透明度文档可在此处找到：[MODEL_CARD.md]。

研究人员与开发者

MatterSim 目前仍在积极开发中，我们欢迎社区参与。如果您对该模型的研究方向感兴趣、有建设性意见或需要报告问题，请随时通过电子邮件 ai4s-materials@microsoft.com 与我们联系。

MatterSim 快速上手指南

MatterSim 是一个跨元素、温度和压力的深度学习原子模型，适用于体相材料的原子模拟。

环境准备

• 操作系统：支持 Linux、macOS（Apple Silicon 用户建议使用 CPU 以避免数值不稳定）和 Windows。
• Python 版本：必须 >= 3.10。
• 推荐工具：建议使用 conda、mamba 或 micromamba 创建独立的虚拟环境，以避免依赖冲突。

安装步骤

方法一：通过 PyPI 安装（推荐）

首先创建并激活 conda 环境：

# 创建环境
conda create -n mattersim python=3.10

# 激活环境
conda activate mattersim

安装 MatterSim（下载依赖可能需要一些时间）：

pip install mattersim

如需安装最新的开发版本：

pip install git+https://github.com/microsoft/mattersim.git

方法二：从源码安装

如果您需要修改源码或使用最新功能，请按以下步骤操作：

1. 克隆仓库并进入目录：

git clone git@github.com:microsoft/mattersim.git
cd mattersim

2. 使用 mamba 安装依赖（强烈推荐，因为 conda 解析依赖较慢）：

mamba env create -f environment.yaml
mamba activate mattersim
uv pip install -e .

基本使用

以下是一个最小化的测试示例，用于计算硅（Si）晶体的能量、受力和应力。默认加载 MatterSim-v1.0.0-1M（轻量版）模型。

注意：macOS Apple Silicon 用户若遇到数值不稳定问题，请将 device 设置为 "cpu"。

import torch
from loguru import logger
from ase.build import bulk
from ase.units import GPa
from mattersim.forcefield import MatterSimCalculator

# 自动检测 CUDA，若无则使用 CPU
device = "cuda" if torch.cuda.is_available() else "cpu"
logger.info(f"Running MatterSim on {device}")

# 构建硅晶体结构
si = bulk("Si", "diamond", a=5.43)
si.calc = MatterSimCalculator(device=device)

# 输出计算结果
logger.info(f"Energy (eV)                 = {si.get_potential_energy()}")
logger.info(f"Energy per atom (eV/atom)   = {si.get_potential_energy()/len(si)}")
logger.info(f"Forces of first atom (eV/A) = {si.get_forces()[0]}")
logger.info(f"Stress[0][0] (eV/A^3)       = {si.get_stress(voigt=False)[0][0]}")
logger.info(f"Stress[0][0] (GPa)          = {si.get_stress(voigt=False)[0][0] / GPa}")

切换模型版本

默认加载的是 1M 版本。如需使用更精确但较大的 5M 版本（MatterSim-v1.0.0-5M），请手动指定 load_path：

MatterSimCalculator(load_path="MatterSim-v1.0.0-5M.pth", device=device)