mace

锤

目录

• 锤
  • 目录
  • 关于狼牙棒
  • 文档
  • 安装
    • PIP安装
    • 来自来源的PIP安装
  • 用法
    • 训练
    • 评估
  • 教程
  • 实验跟踪的重量和偏见
  • 验证的基础模型
    • MACE-MP：材料项目力场
      • ASE中的示例用法
    • 梅斯：可转移的有机力场
      • ASE中的示例用法
    • Finetuning Foundation模型
  • 发展
  • 参考
  • 接触
  • 执照

关于狼牙棒

MACE提供了快速，准确的机器学习跨阶段潜能，并通过高阶模棱两可的消息传递。

该存储库包含Ilyes Batatia，Gregor Simm，David Kovacs和Gabor Csanyi和Friends的MACE参考实现（请参阅贡献者）。

也可用：

• JAX的狼牙棒，目前在评估时快的速度约2倍，但建议在Pytorch中进行培训以进行最佳性能。
• 用于构建任意3D点云的高阶层次图神经网络的MACE层。

文档

可提供部分文档，网址：https：//mace-docs.readthedocs.io

安装

1。要求：

• Python> = 3.7（对于OpenMM，使用Python = 3.9）
• pytorch> = 1.12 （float64的训练不受Pytorch 2.1的支持，但不支持2.2及以后的Pytorch 2.4.1。

确保安装Pytorch。有关安装说明，请参阅官方的Pytorch安装。为您的系统选择适当的选项。

来自PYPI的安装

这是安装MACE的推荐方法。

pip install --upgrade pip
pip install mace-torch

注意： PYPI上的同义软件包与此包装无关。

从源安装

git clone https://github.com/ACEsuit/mace.git
pip install ./mace

用法

训练

要训​​练MACE模型，您可以使用mace_run_train脚本，该脚本应该位于PIP放置二进制文件的通常位置（或者您可以明确运行python3 <path_to_cloned_dir>/mace/cli/run_train.py ）

mace_run_train 
    --name= " MACE_model " 
    --train_file= " train.xyz " 
    --valid_fraction=0.05 
    --test_file= " test.xyz " 
    --config_type_weights= ' {"Default":1.0} ' 
    --E0s= ' {1:-13.663181292231226, 6:-1029.2809654211628, 7:-1484.1187695035828, 8:-2042.0330099956639} ' 
    --model= " MACE " 
    --hidden_irreps= ' 128x0e + 128x1o ' 
    --r_max=5.0 
    --batch_size=10 
    --max_num_epochs=1500 
    --swa 
    --start_swa=1200 
    --ema 
    --ema_decay=0.99 
    --amsgrad 
    --restart_latest 
    --device=cuda 

要提供特定的验证集，请使用参数--valid_file 。要设置较大的批次大小以评估验证集，请指定--valid_batch_size 。

要控制模型的大小，您需要更改--hidden_irreps 。对于大多数应用程序，推荐的默认模型大小为--hidden_irreps='256x0e' （含义256个不变消息）或--hidden_irreps='128x0e + 128x1o' 。如果模型不够准确，则可以包括高阶功能，例如128x0e + 128x1o + 128x2e ，或将通道数量增加到256 。也可以使用--num_channels=128和--max_L=1键指定模型。

通常，首选将孤立的原子添加到训练集中，而不是像上面的示例那样通过命令行中的能量读取。要在培训集中标记它们，请在其信息字段中设置config_type=IsolatedAtom 。如果您不希望使用或不知道隔离原子的能量，则可以使用选项--E0s="average" ，该=使用最小二乘回归估计原子能。

如果启用了关键字--swa ，则训练时期的最后约20％（来自--start_swa时期）的损失能量会增加。此设置通常有助于降低能源误差。

可以使用关键字--default_dtype更改精度，默认值为float64 ，但float32给出了显着的加速（通常在训练中为X2倍数）。

关键字--batch_size和--max_num_epochs应根据训练集的大小进行调整。当训练数据的数量增加时，应增加批量的大小，并且时代的数量应减少。初始设置的启发式词是考虑梯度更新常数的数量为200 000，可以计算为 $ text {max-num-epochs}* frac { text {num-configs-training}}} { text {batch-size}} $ 。

该代码可以处理具有异质标签的训练集，例如包含具有压力和孤立分子的两个散装结构。在此示例中，要使代码忽略分子的压力，请附加到分子配置config_stress_weight = 0.0 。

苹果硅GPU加速

要使用Apple Silicon GPU加速度，请确保安装最新的Pytorch版本并指定--device=mps 。

多GPU培训

对于多GPU培训，请使用--distributed标志。这将使用Pytorch的DistributeDataParallal平行模块在多个GPU上训练模型。结合大型数据集的在线数据加载（见下文）。可以在mace/scripts/distributed_example.sbatch中找到一个示例slurm脚本。

YAML配置

可以使用YAML解析所有或一些参数的选项。例如，要使用上面的参数训练模型，您可以创建一个具有以下内容的yaml文件your_configs.yaml ：

 name : nacl
seed : 2024
train_file : train.xyz
swa : yes
start_swa : 1200
max_num_epochs : 1500
device : cpu
test_file : test.xyz
E0s :
  41 : -1029.2809654211628
  38 : -1484.1187695035828
  8 : -2042.0330099956639
config_type_weights :
  Default : 1.0

并附加到命令行--config="your_configs.yaml" 。命令行中指定的任何参数都将覆盖YAML文件中的任何参数。

评估

要在XYZ文件上评估您的MACE模型，请运行mace_eval_configs ：

mace_eval_configs 
    --configs= " your_configs.xyz " 
    --model= " your_model.model " 
    --output= " ./your_output.xyz " 

教程

您可以运行我们的COLAB教程，以迅速开始使用MACE。

我们也有一个更详细的COLAB教程：

• 梅斯培训和评估简介
• MACE主动学习和微调简介
• 狼牙棒理论和代码（高级）

大型数据集的在线数据加载

如果您有一个可能不适合GPU存储器的大数据集，建议您在CPU上进行预处理数据，并使用在线数据上加载来训练模型。为了预处理您的数据集指定为XYZ文件，运行preprocess_data.py脚本。这里举一个例子：

mkdir processed_data
python ./mace/scripts/preprocess_data.py 
    --train_file= " /path/to/train_large.xyz " 
    --valid_fraction=0.05 
    --test_file= " /path/to/test_large.xyz " 
    --atomic_numbers= " [1, 6, 7, 8, 9, 15, 16, 17, 35, 53] " 
    --r_max=4.5 
    --h5_prefix= " processed_data/ " 
    --compute_statistics 
    --E0s= " average " 
    --seed=123 

要查看所有选项和少量python ./mace/scripts/preprocess_data.py --help 。该脚本将在processed_data文件夹中创建许多HDF5文件，可用于培训。将有一个用于培训的文件夹，一个用于验证，一个用于测试集中每个config_type的单独的文件夹。训练模型使用run_train.py脚本如下：

python ./mace/scripts/run_train.py 
    --name= " MACE_on_big_data " 
    --num_workers=16 
    --train_file= " ./processed_data/train.h5 " 
    --valid_file= " ./processed_data/valid.h5 " 
    --test_dir= " ./processed_data " 
    --statistics_file= " ./processed_data/statistics.json " 
    --model= " ScaleShiftMACE " 
    --num_interactions=2 
    --num_channels=128 
    --max_L=1 
    --correlation=3 
    --batch_size=32 
    --valid_batch_size=32 
    --max_num_epochs=100 
    --swa 
    --start_swa=60 
    --ema 
    --ema_decay=0.99 
    --amsgrad 
    --error_table= ' PerAtomMAE ' 
    --device=cuda 
    --seed=123 

实验跟踪的重量和偏见

如果您想将狼牙棒带有重量和偏见来记录您的实验，只需安装

pip install ./mace[wandb]

并指定必要的关键字参数（ --wandb ， --wandb_project ， --wandb_entity ， --wandb_name ， --wandb_log_hypers ）

验证的基础模型

MACE-MP：材料项目力场

我们已经与材料项目（MP）合作，在MPTRJ数据集中选择了MP松弛轨迹的MPTRJ数据集中的1.6 M散装晶体上的通用MACE潜力。这些模型在https://github.com/acesuit/mace-mp上在GitHub上进行了释放。如果您使用它们，请引用我们的论文，其中还包含大量示例应用程序和基准测试。

警告

MACE-MP模型在VASP输出的MPTRJ RAW DFT能量上进行了训练，并且与MP的DFT能量或CHGNET的能量不直接可比，这些能量已应用于某些过渡金属氧化物，氟化物，GGA/GGA/GGA/GGA+U混合，已应用MP2020 Comparitible校正校正）和14种阴离子物种（阴离子校正）。有关更多详细信息，请参阅MP文档和MP2020 Compatibility.yaml。

ASE中的示例用法

 from mace . calculators import mace_mp
from ase import build

atoms = build . molecule ( 'H2O' )
calc = mace_mp ( model = "medium" , dispersion = False , default_dtype = "float32" , device = 'cuda' )
atoms . calc = calc
print ( atoms . get_potential_energy ())

梅斯：可转移的有机力场

有一个（小，中，大）可转移的有机力场。这些可用于模拟有机分子，晶体和分子液体，也可以用作在新数据集上进行微调的起点。这些模型是根据ASL许可证发布的。这些型号在https://github.com/acesuit/mace-off上在GitHub上进行了释放。如果您使用它们，请引用我们的论文，其中还包含详细的基准和示例应用程序。

ASE中的示例用法

 from mace . calculators import mace_off
from ase import build

atoms = build . molecule ( 'H2O' )
calc = mace_off ( model = "medium" , device = 'cuda' )
atoms . calc = calc
print ( atoms . get_potential_energy ())

Finetuning Foundation模型

为了获得MACE-MP-0基础模型之一，您可以将mace_run_train脚本与额外的参数一起使用--foundation_model=model_type 。例如，要在新数据集中填补小型模型，您可以使用：

mace_run_train 
  --name= " MACE " 
  --foundation_model= " small " 
  --train_file= " train.xyz " 
  --valid_fraction=0.05 
  --test_file= " test.xyz " 
  --energy_weight=1.0 
  --forces_weight=1.0 
  --E0s= " average " 
  --lr=0.01 
  --scaling= " rms_forces_scaling " 
  --batch_size=2 
  --max_num_epochs=6 
  --ema 
  --ema_decay=0.99 
  --amsgrad 
  --default_dtype= " float32 " 
  --device=cuda 
  --seed=3 

其他选项是“中等”和“大”，或基础模型的途径。如果您想对另一个模型进行捕获，则该模型将从提供的路径上加载--foundation_model=$path_model ，但是您需要提供与模型相匹配的完整的超参数（隐藏的IRREREP，R_MAX等）。

发展

该项目使用预先承诺来执行代码格式和提案。我们还使用black ， isort ， pylint和mypy 。我们建议通过在Python环境中安装dev软件包来设置开发环境：

pip install -e " .[dev] "
pre-commit install

第二行将pre-commit ，以自动运行代码检查COMMIT。我们已经设置了CI来检查此问题，但是我们强烈建议您在提交（并推动）之前运行这些命令，以避免不小心提交不良代码。

我们很乐意接受根据麻省理工学院许可证的拉请请求。请将许可文本复制/粘贴到您的拉请请求中。

参考

如果您使用此代码，请引用我们的论文：

 @inproceedings { Batatia2022mace ,
  title = { {MACE}: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields } ,
  author = { Ilyes Batatia and David Peter Kovacs and Gregor N. C. Simm and Christoph Ortner and Gabor Csanyi } ,
  booktitle = { Advances in Neural Information Processing Systems } ,
  editor = { Alice H. Oh and Alekh Agarwal and Danielle Belgrave and Kyunghyun Cho } ,
  year = { 2022 } ,
  url = { https://openreview.net/forum?id=YPpSngE-ZU }
}

@misc { Batatia2022Design ,
  title = { The Design Space of E(3)-Equivariant Atom-Centered Interatomic Potentials } ,
  author = { Batatia, Ilyes and Batzner, Simon and Kov{'a}cs, D{'a}vid P{'e}ter and Musaelian, Albert and Simm, Gregor N. C. and Drautz, Ralf and Ortner, Christoph and Kozinsky, Boris and Cs{'a}nyi, G{'a}bor } ,
  year = { 2022 } ,
  number = { arXiv:2205.06643 } ,
  eprint = { 2205.06643 } ,
  eprinttype = { arxiv } ,
  doi = { 10.48550/arXiv.2205.06643 } ,
  archiveprefix = { arXiv }
 }

接触

如果您有任何疑问，请通过[email protected]与我们联系。

对于错误或功能请求，请使用GitHub问题。

执照

MACE根据MIT许可发布和分发。