MACE偶极模型训练与预测

本例用16个真实DFT标注的H₂O构型训练 AtomicDipolesMACE。它根据原子位置预测分子偶极，适合学习属性模型的数据和接口；它不提供能量或力，不能单独驱动分子动力学。

1 先用已经训练好的模型预测#

下载本组完整输入、真实DFT标签、三个教学模型、轨迹和绘图脚本。

python3 -m zipfile -e mace-response-practical-wave315-*.zip .
cd mace-response-practical
bash run.sh

bash run.sh从保存的数值生成results/figures/下五张图，不重复DFT、训练或MD。以下Python操作在mace/0.3.16环境中执行；推断、训练与动力学请在已分配的计算资源内运行，登录节点用于编辑和提交。

module purge
module load mace/0.3.16

bash run.sh evaluate
cat results/test/VALIDATION.json
head -n 5 results/test/dipole-predictions.csv

这个入口同时评估三种已训练模型，输出完整数值PREDICTIONS.npz、逐分子偶极CSV和误差JSON。不会触发训练，也不重新计算DFT。

2 准备训练配置#

本例采用10训练、3验证、3独立测试构型。标签准备和单位转换见数据教程。configs/dipole.yml完整内容：

train_file: ../../data/train.xyz
valid_file: ../../data/valid.xyz
energy_key: REF_energy
forces_key: REF_forces
dipole_key: REF_dipole
polarizability_key: REF_polarizability
charges_key: REF_charges
total_charge_key: REF_total_charge
E0s: average
batch_size: 5
valid_batch_size: 3
max_num_epochs: 200
default_dtype: float64
seed: 20261108
ema: true
ema_decay: 0.99
swa: false
num_workers: 0
device: cuda
log_dir: logs
model_dir: models
checkpoints_dir: checkpoints
results_dir: results
lr: 0.005
weight_decay: 5.0e-10
config_type_weights: '{''Water'':1.0}'
r_max: 4.0
hidden_irreps: 16x0e+16x1o+16x2e
MLP_irreps: 16x1o
num_interactions: 2
correlation: 2
max_ell: 2
max_L: 2
clip_grad: 10.0
patience: 200
scheduler_patience: 30
eval_interval: 1
save_cpu: true
compute_stress: false
name: water-dipole
model: AtomicDipolesMACE
loss: dipole
error_table: DipoleRMSE
dipole_weight: 100.0
polarizability_weight: 100.0
energy_weight: 1.0
forces_weight: 10.0
num_radial_basis: 8
num_cutoff_basis: 5

hidden_irreps是消息传递特征，MLP_irreps是读出层，二者不要求相同。本模型偶极读出用16x1o。MACE0.3.16原生命令行使用num_radial_basis和num_cutoff_basis，不要直接照搬Python构造器中名字不同的参数。

E0s: average是同组成数据的拟合基线；H₂O固定化学计量不足以唯一确定孤立H、O原子能，不要将这个配置解释为单原子DFT能。纯偶极任务主要使用偶极损失，文件里保留的能量/力权重不是说此模型也输出能量和力。

3 提交训练并查看结果#

sbatch train.slurm dipole
squeue -u "$USER"
# 训练结束后
ls work/train/dipole/models
tail -n 30 train-*.log

train.slurm仅复制train.xyz和valid.xyz，在新的work/train/dipole/执行：

mace_run_train --config train.yml

实际示例使用一张P100、两个CPU线程、float64、200轮、16通道、两次相互作用、4 Å截断及固定种子。完成后CPU可读模型为work/train/dipole/models/water-dipole.model。训练存在随机性，新的模型不要求与附件权重逐字节相同，应比较独立误差。

训练曲线来自真实原生逐轮记录，训练线是当轮各batch损失平均；三个模型的损失组成、单位和权重不同，不能用图的高低直接给模型排名。

4 用ASE读取三个偶极分量#

python - <<'PYCODE'
import numpy as np
from ase.io import read
from mace.calculators import MACECalculator
a = read('qualified/data/test.xyz', index=0)
# 预测时去掉参考标签，避免把已有数值误当成预测
for key in list(a.info):
    if key.startswith('REF_'): del a.info[key]
for key in list(a.arrays):
    if key.startswith('REF_'): del a.arrays[key]
a.set_initial_charges(np.zeros(len(a)))
a.calc = MACECalculator(model_paths='models/dipole.model',
    model_type='DipoleMACE', device='cpu', default_dtype='float64')
mu = a.get_dipole_moment()
print('dipole [e A]:', mu)
print('dipole [Debye]:', mu * 4.803204271875351)
PYCODE

训练名AtomicDipolesMACE与计算器类型DipoleMACE不同，按示例匹配。换成自己新训练的模型时，修改model_paths。调用get_potential_energy()不会把纯偶极模型变成势函数。原子偶极分解也不等同于唯一可观测的Bader电荷。

5 看实际测试误差，而不只看训练曲线#

独立测试3个构型的整分子偶极向量RMSE为0.00288451535 Debye，计算方式是先对每个分子的三个分量求平方和，再对构型平均开方，不是仅比较偶极大小，也不是每原子误差。

本例训练标签是e·Å。原生控制台有些格式固定显示mDebye/atom文字但只缩放原始误差，因此使用附件独立脚本按实际标签单位转成Debye，不能直接把原生打印的单位文字当成转换。

将结构作任意刚体旋转R后，应有mu_new=R@mu_old；中性分子整体平移不应改变总偶极。附件脚本实际检查了三分量旋转、平移以及CPU/P100完整输出，最大跨设备属性差在浮点舍入量级。本组数据的低误差仅适用于给定分子和结构范围，不证明液态水、带电体系或断键过程的精度。