1
gcw_xUvjaUyi/aimnet2-wb97m-d3-npu
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

AIMNet2 (isayevlab/aimnet2-wb97m-d3) 昇腾 NPU 推理适配

isayevlab/aimnet2-wb97m-d3 是 AIMNet2 通用机器学习 分子间作用势 (Universal Machine-Learning Interatomic Potential),在 wB97M-D3 泛函级别训练。 输入为分子几何(原子序数 + 3D 坐标,标准 xyz 文件),输出为预测的电子总能量(单位 eV,同时给出 Hartree),可选输出原子受力与原子电荷。

本仓库将其适配到 昇腾 Ascend 910 NPU(torch_npu,固定使用 npu:0)。代码中不含任何 CUDA 语句;模型与输入张量全部运行在 npu:0 上,并在入口处对 NPU 初始化做了 try-except 保护。

特性

  • 架构:AIMNet2(Atomic Environment Vectors 径向+角度特征 + 3 个 interaction/update block), 4 个 ensemble 成员权重已缓存,默认加载 ensemble_0。
  • 能量分解:神经网络原子能量 + 原子偏移 + 内嵌短程库仑 (SRCoulomb) + 外置长程库仑 (FULL Coulomb, simple) + D3BJ 色散(纯 PyTorch 实现)。
  • 双模式:CLI 单次推理 + FastAPI HTTP 服务。
  • 元素支持:H, B, C, N, O, F, Si, P, S, Cl, As, Se, Br, I(模型 implemented_species)。

目录结构

aimnet2-wb97m-d3-npu/
├── inference.py              # 单文件推理脚本 (CLI + FastAPI 双模式)
├── sample.xyz                # 示例输入: 水分子 H2O
├── sample_methane.xyz        # 示例输入: 甲烷 CH4
├── README.md
├── requirements.txt
├── .gitignore                # 忽略 model_weights/, logs/ 等
└── model_weights/            # 权重缓存 (自动下载, 不入库)
    └── isayevlab__aimnet2-wb97m-d3/

环境依赖

  • Python 3.11
  • torch + torch_npu(昇腾 CANN 环境,torch.npu.is_available() == True)
  • aimnet(AIMNet2 官方实现,pip install aimnet)
  • safetensors, huggingface_hub(权重加载)
  • fastapi, uvicorn, python-multipart(HTTP 服务)
pip install -r requirements.txt

说明:官方 aimnet 计算器依赖 nvalchemiops 的 Warp/CUDA 邻域核,在 NPU 上不可用。 本适配改用纯 PyTorch 稠密邻接矩阵(小/中分子精确)与纯 PyTorch D3BJ 色散 (aimnet.modules.DFTD3._compute_energy_torch),并打了一个 NPU 兼容补丁 (nse 电荷均衡避免原地修改张量),从而在 NPU 上端到端可运行。

权重缓存

权重默认从 HuggingFace 镜像 (hf-mirror.com) 下载到本地缓存:

./model_weights/isayevlab__aimnet2-wb97m-d3/

启动时优先加载本地缓存,命中则跳过下载;未命中才下载。缓存包含 config.json 与 ensemble_0.safetensors ~ ensemble_3.safetensors(4 个 ensemble 成员,各约 8.8 MB)。 该目录已被 .gitignore 忽略,不会推送到代码仓库。

使用方式

1. CLI 单次推理

python3 inference.py --xyz sample.xyz            # 水分子, 输出能量 (eV + Hartree)
python3 inference.py --xyz sample.xyz --forces   # 额外输出原子受力 (eV/A)
python3 inference.py --xyz sample.xyz --charge 0 --ensemble 0
python3 inference.py --smiles "O"                # 可选, 需要 rdkit (本环境通常未安装)

标准 xyz 格式:

3
H2O water molecule (Angstrom)
O     0.000000   0.000000   0.000000
H     0.957200   0.000000   0.000000
H    -0.239987   0.926627   0.000000

输出示例(水分子,实测,npu:0):

[result] 总能量 (Total Energy):
    energy_ev      = -2081.049728 eV
    energy_hartree = -76.477167 Hartree
[result] 原子电荷 (charges, e):
    -0.6948  0.3474  0.3474
[result] 原子受力 (forces, eV/A):
    O     0.00381    0.00491   -0.00000
    H     0.06078   -0.05098   -0.00000
    H    -0.06459    0.04607   -0.00000

合理性参考:水 H2O 在 wb97m-d3 级别总能量约 -76.4 ~ -76.5 Hartree;甲烷 CH4 约 -40.5 Hartree。

2. FastAPI HTTP 服务

uvicorn inference:app --host 0.0.0.0 --port 8102

POST /predict 支持两种请求体:

(a) multipart 上传 xyz 文件(字段名 xyz):

curl -s -X POST http://127.0.0.1:8102/predict \
  -F "xyz=@sample.xyz;type=chemical/x-xyz"

(b) JSON body:

curl -s -X POST http://127.0.0.1:8102/predict \
  -H "Content-Type: application/json" \
  -d '{"atoms":[8,1,1],"coords":[[0,0,0],[0.9572,0,0],[-0.239987,0.926627,0]],"forces":true}'

返回 JSON(实测响应):

{
  "model": "isayevlab/aimnet2-wb97m-d3",
  "ensemble_member": 0,
  "device": "npu:0",
  "natoms": 3,
  "energy_ev": -2081.0497283387995,
  "energy_hartree": -76.47716693028184,
  "charges": [-0.6948, 0.3474, 0.3474],
  "atoms": ["O", "H", "H"],
  "forces": [[0.00381, 0.00491, -0.0], [0.06078, -0.05098, -0.0], [-0.06459, 0.04607, -0.0]]
}

NPU 适配说明

  1. 无 CUDA:全文件无 .cuda() / cuda: 等 GPU 专用调用。
  2. 固定设备 npu:0:模型与输入张量迁移至 npu:0。
  3. NPU 初始化保护:入口 init_npu() try-except,导入 torch_npu 失败或 npu:0 不可用时 打印清晰错误并优雅退出。
  4. 算子工作绕:
    • nvalchemiops 邻域核 (Warp) 在 NPU 上报 Invalid device identifier: npu:0 → 改用纯 PyTorch 稠密邻接矩阵。
    • 官方 D3 走 nvalchemiops 核 → 改用 DFTD3._compute_energy_torch(纯 PyTorch)。
    • nse 电荷均衡原地修改 mol_sizes 触发 NPU autograd 报错 → 非原地补丁。
  5. 精度:NPU 上 float64 会被编译器转成 float,故能量与 CPU 相比有 ~0.005 eV 的微小差异,属正常。

验证结果

  • CLI(python3 inference.py --xyz sample.xyz --forces):成功,npu:0,H2O 能量 -2081.049728 eV / -76.477167 Hartree,见 logs/cli.log。
  • FastAPI(uvicorn 8102,multipart + JSON 两种请求):成功,返回上述 JSON,见 logs/api.log。
  • 截图:assets/agent_workflow.png、assets/npu_device_call.png、assets/model_result.png。

引用

@article{anstine2025aimnet2,
  title={AIMNet2: A Neural Network Potential to Meet your Neutral, Charged, Organic, and Elemental-Organic Needs},
  author={Anstine, Dylan and Zubatyuk, Roman and Isayev, Olexandr},
  journal={Chemical Science},
  year={2025},
  doi={10.1039/D4SC08572H}
}

License

MIT