NequIP

NequIP 是一个用于构建 E(3) 等变原子间势的开源代码。

• 安装与使用
• 教程
• 预训练模型
• 亮点功能
• 扩展包
• 参考文献与引用
• 作者
• 社区、联系、问题与贡献

[!重要] nequip 软件包于 2025 年 4 月 23 日发布了 一次重大的向后不兼容更新，版本号为 v0.7.0。旧版本 v0.6.2 仍可在 GitHub 发布页面和 PyPI 上找到，可用于现有的配置文件。

安装与使用

安装说明和用户指南请参阅我们的 文档。

教程

学习如何使用 NequIP 的最佳方式是通过 教程笔记本。该笔记本完全在 Google Colab 的云端虚拟机上运行，您无需在本地安装或运行任何东西。

预训练模型

预训练模型可在 nequip.net 上找到。

亮点功能

以下是一些值得注意的功能，并附有详细信息的快速链接：

• 编译式训练 和 编译式推理
• 多 GPU 训练
• GPU 内核加速 与 OpenEquivariance 和 CuEquivariance（alpha 版）
• ASE 计算器集成 和 LAMMPS 集成 通过 pair_nequip_allegro 中的对势样式以及我们提供的 LAMMPS ML-IAP 集成。

扩展包

NequIP 软件框架设计灵活且可扩展：您可以构建自定义架构、实现新的训练技术，并通过扩展包在其基础上开发额外的方法。 如果您有兴趣开发自己的扩展包，请参阅 扩展包文档，并考虑 加入我们的 Zulip 讨论组，以进行开发者相关的讨论与合作。

NequIP 框架的一个著名扩展包是 allegro 包，它实现了严格局部等变的原子间势架构——Allegro（见《Nature》文章：https://www.nature.com/articles/s41467-023-36329-y）。更多扩展包可在 https://www.nequip.net/extensions 上找到。

参考文献与引用

无论整体还是部分使用本软件，都应明确注明并链接到本仓库。

如果您在学术工作中使用了此代码，请引用以下文献：

1. 描述 NequIP 软件框架的 预印本：

   Chuin Wei Tan, Marc L. Descoteaux, Mit Kotak, Gabriel de Miranda Nascimento, Seán R. Kavanagh, Laura Zichi, Menghang Wang, Aadit Saluja, Yizhong R. Hu, Tess Smidt, Anders Johansson, William C. Witt, Boris Kozinsky, Albert Musaelian.
   “高性能深度等变原子间势的训练与推理。”
   https://doi.org/10.48550/arXiv.2504.16068

同时建议引用：

2. 原始的 NequIP 论文（发表于《Nature Communications》）：

   Simon Batzner, Albert Musaelian, Lixin Sun, Mario Geiger, Jonathan P. Mailoa, Mordechai Kornbluth, Nicola Molinari, Tess E. Smidt, and Boris Kozinsky.
   “用于数据高效且精确的原子间势的 E(3) 等变图神经网络。”
   Nature Communications 第 13 卷第 1 期 (2022)：2453

3. 关于优化 LAMMPS 分子动力学模拟的 计算规模论文：

   Albert Musaelian, Anders Johansson, Simon Batzner, and Boris Kozinsky.
   “将深度等变模型的领先精度扩展到真实尺度的生物分子模拟中。”
   2023 年国际高性能计算、网络、存储与分析会议论文集，第 1–12 页。

4. NequIP 使用的等变神经网络包 e3nn，可通过其 预印本 和/或 代码 进行引用。

像 Allegro 这样的扩展包也有其自身的相关引用。

为了方便起见，我们在 CITATION.bib 文件中提供了若干相关论文的 BibTeX 条目。

作者

详情请参阅 AUTHORS.md。

社区、联系、问题与贡献

如果您发现 bug 或有功能建议，请在 Issues 中提交。 如果您有独立的问题或其他讨论主题，可以尝试访问我们的 GitHub Discussions。

欢迎活跃用户和感兴趣的开发者加入 NequIP 社区聊天服务器，该服务器基于优秀的 Zulip 软件搭建。 Zulip 的组织方式与您可能熟悉的 Slack 或 Discord 等聊天软件略有不同：请在发帖前阅读他们的 主题介绍。 请点击此处填写 NequIP 社区兴趣表单。

如果您想为代码做出贡献，请阅读 "Contributing to NequIP"。

您也可以通过电子邮件 allegro-nequip@g.harvard.edu 与我们联系。

NequIP 快速上手指南

NequIP 是一个用于构建 E(3)-等变原子间势（Interatomic Potentials）的开源代码库，支持高性能训练与推理，并广泛集成于 ASE、LAMMPS 等主流模拟软件中。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 macOS。
• Python 版本: Python 3.8 - 3.11。
• 硬件加速: 推荐使用 NVIDIA GPU 以获得最佳训练和推理性能（需安装对应的 CUDA 驱动）。
• 前置依赖:
  • pip (包管理工具)
  • git (版本控制工具)
  • (可选) Conda/Mamba 环境管理器（推荐用于隔离环境）

注意：2025 年 4 月发布的 v0.7.0 版本包含重大不兼容更新。如果您需要使用旧的配置文件，请选择 v0.6.2 版本。本指南默认基于最新稳定版。

安装步骤

建议使用虚拟环境进行安装，以避免依赖冲突。

1. 创建并激活虚拟环境

python -m venv nequip-env
source nequip-env/bin/activate  # Linux/macOS
# 或在 Windows 上: nequip-env\Scripts\activate

2. 安装 NequIP

您可以直接从 PyPI 安装最新版本：

pip install nequip

如果需要利用国内镜像源加速下载（如清华大学源）：

pip install nequip -i https://pypi.tuna.tsinghua.edu.cn/simple

若需使用特定旧版本（如 v0.6.2）以兼容旧配置：

pip install nequip==0.6.2

3. 验证安装

安装完成后，可通过以下命令检查版本：

python -c "import nequip; print(nequip.__version__)"

基本使用

学习 NequIP 最快捷的方式是通过官方提供的教程笔记本，或者参考以下核心工作流。

方式一：在线体验（无需本地安装）

NequIP 提供了完整的 Google Colab 教程，您可以在云端直接运行所有示例，无需配置本地环境。

• 教程地址: NequIP Tutorial on Colab

方式二：本地命令行工作流

典型的 NequIP 工作流程包括：数据准备 -> 配置编写 -> 模型训练 -> 势函数部署。

1. 准备数据集

确保您拥有符合 ASE 格式的训练数据（如 .extxyz 文件），包含原子结构、能量和受力信息。

2. 编写配置文件

创建一个 YAML 格式的配置文件（例如 config.yaml），定义网络架构、超参数和数据路径。以下是一个极简示例：

# config.yaml
seed: 12345
dataset:
  r_max: 5.0
  file: "data/train.extxyz"
model:
  num_basis: 8
  num_radial_cutoff: 6
  parity: true
  num_features: 32
  l_max: 2
train:
  batch_size: 16
  max_epochs: 100
  learning_rate: 0.01

3. 启动训练

使用 nequip-train 命令开始训练：

nequip-train config.yaml

训练过程中，模型权重和日志将自动保存到指定目录。

4. 在模拟软件中使用

训练完成的模型可轻松集成到分子动力学软件中：

• ASE (Python):

  from nequip.ase import NequIPCalculator
  calc = NequIPCalculator.from_deployed_model("models/best_model.pt")
  atoms.set_calculator(calc)
  

• LAMMPS: 通过 pair_nequip_allegro 风格或 ML-IAP 接口调用（需编译支持）。

---

更多高级功能（如多 GPU 训练、模型编译加速、自定义扩展包开发）请参阅 官方文档。