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許可發布和分發。