材料图库

官方文档

https://matgl.ai

简介

MatGL (材料图库) 是一个用于材料科学的图深度学习库。数学图是原子集合的自然表示。图深度学习模型已被证明在作为材料属性预测的代理模型时，能够持续提供卓越的性能。

MatGL建立在深度图库 (DGL) 和 PyTorch 之上，并对特定于材料的应用进行了适当的调整。目标是使 MatGL 成为开发、共享材料图深度学习模型的可扩展平台，包括材料3体图网络 (M3GNet) 及其前身 MEGNet。

这项工作是材料虚拟实验室（MAVRL）和英特尔实验室（圣地亚哥·米雷特，马塞尔·纳萨尔，卡梅洛·冈萨雷斯）之间的合作。

状态

以下总结了主要里程碑。请参阅变更日志以获取详细信息。

• v1.0.0（2024年2月14日）：实现了TensorNet和SO3Net。
• v0.5.1（2023年6月9日）：实现了模型版本控制。
• v0.5.0（2023年6月8日）：简化了模型的保存和加载。现在可以使用一行代码加载模型！
• v0.4.0（2023年6月7日）：接近原始TF实现的功能。现在可以重新训练M3Gnet通用势。
• v0.1.0（2023年2月16日）：M3GNet和MEGNet架构的初始实现已完成。请注意可能会有错误！

当前架构

在此，我们总结了MatGL中当前实现的架构。必须强调，这绝对不是一份详尽无遗的列表，我们预计MatGL的核心团队以及其他贡献者将在未来添加新的架构。

图：M3GNet/MEGNet示意图

M3GNet

材料三体图网络（M3GNet）是一种新的材料图神经网络架构，它在MEGNet中集成了三体相互作用。另一个区别是增加了原子坐标和晶体中的3x3晶格矩阵，这是通过自动微分获得张量量（如力、应力等）所必需的。作为一个框架，M3GNet具有多种应用，包括

• 原子间势的开发。与相同的训练数据，M3GNet的性能与最先进的机器学习原子间势（MLIPs）相似。然而，图表示的一个关键特征是其灵活性，可以扩展到不同的化学空间。M3GNet的一个关键成就是开发了一个通用IP，通过在材料项目中进行的松弛训练，可以在整个元素周期表中工作。
• 用于属性预测的代理模型。与先前的MEGNet架构一样，MEGNet可以用来开发代理模型进行属性预测，在许多情况下，其准确性优于或类似于其他最先进的机器学习模型。

有关详细的性能基准测试，请参阅参考文献部分。

MatGL使用DGL和Pytorch重新实现了M3GNet。与原始Tensorflow实现相比，一些关键改进包括

• 基于DGL的更直观的API和类结构。
• 通过PyTorch Lightning支持多GPU。

MEGNet

材料图网络（MEGNet）是DeepMind的图网络在材料科学中的应用实现。我们已经证明，它在分子和晶体中广泛属性的低预测误差方面取得了成功。新版本包括我们最近关于多保真材料属性建模的工作。图1显示了图网络的顺序更新步骤，其中使用来自每个其他的信息更新键、原子和全局状态属性，生成输出图。

其他模型

我们在matgl中还实现了其他模型。以下是一个非详尽的列表。

• TensorNet，一种利用笛卡尔张量表示的O(3)守恒消息传递神经网络架构。
• SO3Net，一个简约的SO(3)守恒神经网络。

安装

可以通过pip安装Matgl的最新稳定版本。

pip install matgl

对于最新开发版本，请克隆此仓库并使用以下命令安装：

pip install -e .

CUDA（GPU）安装

如果您打算使用CUDA（GPU）来加速训练，安装合适的PyTorch和DGL版本非常重要。以下是一些基本指令，但建议您在遇到任何问题时参考PyTorch文档和DGL文档。

pip install torch==2.2.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install dgl -f https://data.dgl.ai/wheels/cu118/repo.html
pip install dglgo -f https://data.dgl.ai/wheels-test/repo.html

使用

现在提供了针对材料项目形成能和多重保真带隙的预训练M3GNet通用势和MEGNet模型。

命令行（从v0.6.2开始）

CLI工具现在提供使用预训练模型进行快速松弛或预测的功能，以及其他简单的管理任务（例如，清除缓存）。以下是一些简单示例：

1. 进行松弛：

   mgl relax --infile Li2O.cif --outfile Li2O_relax.cif
   

2. 使用预训练的属性模型之一：

   mgl predict --model M3GNet-MP-2018.6.1-Eform --infile Li2O.cif
   

3. 清除缓存：

   mgl clear
   

对于全部选项，请使用mgl -h。

代码

只想直接使用模型的用户应使用新实现的matgl.load_model便捷方法。以下是一个预测CsCl形成能的示例：

from pymatgen.core import Lattice, Structure
import matgl

model = matgl.load_model("MEGNet-MP-2018.6.1-Eform")

# This is the structure obtained from the Materials Project.
struct = Structure.from_spacegroup("Pm-3m", Lattice.cubic(4.1437), ["Cs", "Cl"], [[0, 0, 0], [0.5, 0.5, 0.5]])
eform = model.predict_structure(struct)
print(f"The predicted formation energy for CsCl is {float(eform.numpy()):.3f} eV/atom.")

要获取可用的预训练模型列表：

import matgl
print(matgl.get_available_pretrained_models())

Pytorch Hub

预训练模型也可在Pytorch Hub上找到。要使用这些模型，只需安装matgl并使用以下命令：

import torch

# To obtain a listing of models
torch.hub.list("materialsvirtuallab/matgl", force_reload=True)

# To load a model
model = torch.hub.load("materialsvirtuallab/matgl", 'm3gnet_universal_potential')

模型训练

在PES训练中，训练、验证和测试集中能量的单位、力的单位和应力的单位（可选）与MatGL中使用的单位完全一致非常重要。

• 能量：具有单位eV的能量列表。
• 力：具有单位eV/Å的nx3力矩阵列表，其中n是每个结构中的原子数。n对于所有结构不需要相同。
• 应力：具有单位GPa的3x3应力矩阵列表（可选）

注意：对于应力，我们采用压缩应力给出负值的惯例。从VASP计算获得的应力（默认单位为kBar）应乘以-0.1，以便直接与模型一起使用。

教程

我们编写了教程，介绍如何使用MatGL。这些教程是从[Jupyter notebooks] jupyternb生成的，可以直接在Google Colab上运行。

资源

• API文档，包含所有类和方法。
• 开发者指南概述了matgl的关键设计元素，特别是针对希望训练和贡献matgl模型的开发者。
• AdvancedSoft已实现了LAMMPS接口，用于TF和MatGL版本的M3Gnet。

参考文献

目前正在撰写MatGL出版物。目前，请参阅CITATION.cff文件以获取引用信息。如果您使用任何预训练模型，请引用以下相关作品：

MEGNet

Chen, C.; Ye, W.; Zuo, Y.; Zheng, C.; Ong, S. P. Graph Networks as a Universal Machine Learning Framework for Molecules and Crystals. Chem. Mater. 2019, 31 (9), 3564–3572. DOI: 10.1021/acs.chemmater.9b01294.

多保真MEGNet

Chen, C.; Zuo, Y.; Ye, W.; Li, X.; Ong, S. P. 从多保真数据学习有序和无序材料的性质。 自然计算科学，2021，1，46–53. DOI: 10.1038/s43588-020-00002-x.

M3GNet

Chen, C., Ong, S.P. 适用于元素周期表的通用图深度学习原子间势。 自然计算科学，2023，2，718–728. DOI: 10.1038/s43588-022-00349-3.

常见问题解答

1. M3GNet-MP-2021.2.8-PES 与原始TensorFlow (TF) 实现不同！

   回答： M3GNet-MP-2021.2.8-PES 是经过改进数据和一些架构变更后的重新拟合模型。将TF版本的权重迁移到DGL/PyTorch是非平凡的。我们已经进行了合理的基准测试，以确保新的实现能够再现原始TF实现的大致误差特性（参见示例）。然而，并不期望它能完全再现TF版本。这个重新拟合的模型作为未来模型改进的基线。我们不认为有必要投入资源来完全再现TF版本。

2. 我在使用 matgl.load_model() 时遇到错误！

   回答： 最可能的原因是您有模型的缓存旧版本。我们经常重构模型以确保最佳实现。这通常可以通过将您的 matgl 更新到最新版本并使用以下命令清除缓存来解决：mgl clear。在下次运行时，将下载最新的模型。从v0.5.2版本开始，我们已实施了一个模型版本控制方案，该方案可以检测代码与模型版本冲突，并提醒用户此类问题。

3. 我应该使用哪些预训练模型？

   回答： 没有一个确定的答案。一般来说，架构和数据集越新，模型性能越有可能更好。但应注意，在更多样化的数据集上运行的模型可能会在特定系统上的性能上有所妥协。最好的办法是查看每个模型附带的自述文件，并在您感兴趣的系统中进行一些测试。

4. 我该如何为matgl做出贡献？

   回答： 对于代码贡献，请进行Fork并提交pull请求。您应该阅读开发者指南以了解一般的设计指南。我们也欢迎预训练模型的贡献，这些贡献也应通过PR提交。请遵循预训练模型文件夹的结构。特别是，我们期望所有模型都附带一个 README.md 和一个文档，说明其使用和关键性能指标。我们还期望贡献是关于新性质或系统，或者显著优于现有模型。我们将在未来开发一种替代的模型共享方式。

5. 您的模型没有一个能完成我所需要的。我可以在哪里得到帮助？

   回答： 请简要描述您的需求，联系Ong教授。对于简单问题，我们很乐意提供咨询并指出正确的方向。对于更复杂的问题，我们始终欢迎学术合作或项目。我们还为具有独特需求的公司提供咨询服务，包括但不限于定制数据生成、模型开发和材料设计。

致谢

这项工作主要得到了美国能源部科学办公室基础能源科学办公室材料科学与工程分部资助的材料项目的支持，合同编号为DE-AC02-05-CH11231：材料项目KC23MP。这项工作使用了极端科学和工程发现环境（XSEDE）的Expanse超级计算集群，该集群得到了国家科学基金会ACI-1548562号项目的支持。