NEPAdapters v1.0.3

🚀 NEPAdapters v1.0.3

本版本将新一代磁性势协议接入 NEPAdapters 正式路径，重点增加 nep4_spin3 的 CPU、CUDA 与 LAMMPS 支持，并继续完善 nep4_spin2、GPU 执行效率和跨平台 Python 打包。

✨ Spin3 协议与模型支持

• 新增 nep4_spin3：CPU 与 CUDA 后端使用同一套 O/C 协议和描述符布局；已覆盖并验证 O3-C2、O3-C3 和 O3-C4。
• 完整压缩配对：保留全部 4 × C² 投影系数，并生成 C × (C + 1) / 2 个对称通道配对，不使用仅对角近似。
• 逐元素 spin cutoff：spin_cutoff 可为统一值，也可按元素分别给出；异种元素对采用两端 cutoff 的对称组合。
• 显式模型契约：版本化 spin 模型统一解析 spin_basis_size、spin_l_max、spin_compress、spin_order 和 spin_soc，非法形状或缺失字段直接报错，不静默降级。
• ZBL 协议兼容：模型解析支持 nep4_spin2_zbl 与 nep4_spin3_zbl，并保持普通、typewise 和 flexible ZBL 的既有边界。

⚡ CUDA 与 LAMMPS

• Cooperative CUDA 路径：Spin3 C2、C3、C4 均进入 cooperative kernel 正式路径；C4 不再走单独的慢速实现。
• 统一 CPU/CUDA 信息流：描述符布局、投影维度和压缩通道规则由共享协议约束，减少后端间语义漂移。
• LAMMPS GPU 接入：现有 nep/gpu、nep/gpu/kk 和 nep/gpu/kk/device 插件可加载新版 spin 模型。
• 修复 newton off：修复 ghost 原子力缓冲未清零和 CPU 反向通信问题，避免跨步残留或漏加邻居贡献。

🪟 Python 与 Windows

• 修复 Windows 上包含中文或其他 Unicode 字符的模型路径加载。
• 新增 Windows wheel 的 Unicode 路径构建与安装回归测试。
• 预编译 wheel 计划覆盖 CPython 3.10–3.14：Linux/Windows x86_64 同时包含 CPU 与 CUDA 后端，macOS x86_64/arm64 包含 CPU 后端。
• Linux 和 Windows CUDA wheel 内置 CUDA Runtime；运行 CUDA 后端仍需兼容的 NVIDIA 驱动。

🧪 验证

• macOS CPU Release 测试 33/33 通过，包括 Spin3 O3-C2、O3-C3、O3-C4 oracle。
• Sai V100 CUDA/LAMMPS 测试 91/91 通过，包括 Spin3 CPU/CUDA oracle、协议与插件测试。
• 真实 LAMMPS nep/gpu/kk smoke 通过，energy、force、magnetic force 和 virial 均在既定容差内。
• Linux CPU CI 与 Windows Unicode wheel CI 已通过。
• 1.0.3 sdist 构建成功，包名和版本元数据已核对。

⚠️ 当前边界

• 本版本验证的是模型协议、后端数值 oracle 和 LAMMPS 接口；不同训练任务上的精度仍应由具体数据集独立评估。
• CUDA 后端遇到不支持的模型或执行错误时不会自动回退到 CPU。
• 官方 combined wheel 默认不包含 qNEP PPPM/cuFFT；Python wheel 不包含 LAMMPS 本体或插件。

python -m pip install --upgrade "nep-adapters[ase]==1.0.3"

Full Changelog: v1.0.2...v1.0.3

v1.0.2

🚀 NEPAdapters v1.0.2

本版本集中统一 CPU、CUDA 与 LAMMPS 的 NEP4 模型协议语义，补齐 CUDA 后端此前缺失的模型能力，并修复小周期盒子和邻居容量问题。

✨ 协议与模型支持

• 统一 NEP4 解析：CPU/CUDA 现在一致校验参数数量、取值范围、baseline 数量和 counted block；缺少必要的 spin 参数会直接报错。
• 类型语义：spin_dof_type 严格控制 spin 描述符中心和磁力输出，spin_env_type 控制可进入 spin 环境的邻居元素，并验证自由度类型是环境类型的子集。
• Cutoff 语义：结构 radial cutoff、spin cutoff 和候选邻居 cutoff 相互独立；支持结构 radial/angular type-dependent cutoff。
• CUDA 模型能力：补齐 universal、typewise 和 flexible ZBL，以及普通 NEP4 双隐藏层 ANN。
• 版本边界：明确拒绝已淘汰的 NEP3；本版本不加入 dipole、polarizability 和 temperature model。

🐛 修复与可靠性

• 修复 CUDA 在 rc_spin != rc_radial 时错误扩大普通结构描述符 cutoff 的问题。
• 修复 CUDA batch 在小周期盒子中遗漏周期自镜像邻居的问题，覆盖普通 NEP、spin NEP 和 qNEP。
• CPU batch 将模型声明的邻居容量作为初始 workspace；实际需求更大时自动扩容、重建邻居表并复用高水位容量，不再受固定 1000 或模型导出容量的硬限制。
• CPU batch、CPU LAMMPS 和 CUDA 对非 spin_dof_type 元素的磁力输出均严格为零。
• LAMMPS ordinary NEP 与 spin 路径复用统一后的 parser、model 和最大 cutoff 语义。

🧪 验证

• 本地 CPU 测试 28/28 通过。
• Sai V100 CPU/CUDA spin、普通 NEP 和 qNEP 测试 47/47 通过。
• 普通 NEP4 已与 GPUMD 参考实现完成跨后端数值一致性验证；CPU 达到双精度一致性，CUDA 的 energy、force 和 virial 误差处于单精度预期范围。

⚠️ 当前边界

• qNEP batch 已完成 CPU/CUDA 数值验证；LAMMPS/PPPM qNEP 集成仍不支持。
• dipole、polarizability 和 temperature model 不在 CUDA 支持范围内。
• LAMMPS 外部邻居路径使用 ghost atoms，不受本次 CUDA batch 小周期盒子缺陷影响。

python -m pip install --upgrade "nep-adapters[ase]==1.0.2"

Full Changelog: v1.0.1...v1.0.2

v1.0.1

🚀 NEPAdapters v1.0.1

本版本集中修复计算约定和运行边界，并提升 Python CPU batch、CUDA batch API 与 LAMMPS nep/cpu 的吞吐。

⚡ 性能改进

• CPU batch：复用 worker 与 scratch workspace，并支持多结构并行。32 原子 BCC Fe、NEP89 模型、32 核、2048 帧实测由 4109 提升至 16267 frame/s，加速 3.97×。
• CUDA batch：恢复多结构 fast path；RTX 4090 上相对 fallback loop 加速 37.85–89.51×。该结果仅适用于 CUDA batch API。
• LAMMPS CPU：复用邻居容量。Xeon Gold 6530、4000 原子、16 OpenMP 线程、单 MPI rank 实测由 2.77214 s 降至 2.55204 s，提升 8.62%。

🐛 修复与可靠性

• 修正 ASE stress 的符号、Voigt 顺序和体积归一化，使其与 GPUMD virial 约定一致。
• 增加 CPU/CUDA batch 输入与原子类型范围校验，并保留 CPU 原始 last-error。
• 修复 CUDA 零长度 staging、邻居容量增长和 Kokkos 非单位 inner stride 索引问题。
• 同一个 Python Model 的并发调用会安全串行化，避免共享 native workspace 数据竞争。
• 修复 IntelLLVM cell-list 错误向量化，Intel icpx 构建保留验证过的 -fno-vectorize 配置。

📦 构建与发布

• 新增 Linux CPU-only CI。
• 仓库根目录 VERSION 成为 CMake、Python 包、运行时和 LAMMPS 的版本号单一来源。
• 统一 macOS wheel 的 OpenMP runtime，并完善 wheel 内容和版本一致性检查。

⚠️ 升级提醒

• 旧版本通过 ASE calculator 得到的 stress 建议重新核对或生成。
• Python batch 仍要求全周期边界；小 batch 未达到并行阈值时，加速可能不明显。
• CUDA batch 的高倍加速不代表 LAMMPS 路径获得相同提升。

python -m pip install --upgrade "nep-adapters[ase]==1.0.1"

Full Changelog: v1.0.0...v1.0.1

v1.0.0

🚀 NEPAdapters v1.0.0

NEPAdapters 的首个正式版本，将 NepTrainKit 中的 NEP 运行时拆分为可独立安装、测试和发布的计算适配层。

✨ 主要功能

• 统一接口：提供 Python、C/C++ 和 LAMMPS 接口，后端必须显式选择；不可用或不支持时会明确报错，不会静默切换。
• CPU 后端：支持普通 NEP、qNEP、spin NEP、dipole、polarizability 和 DFT-D3。
• CUDA 后端：支持普通 NEP4/NEP5、qNEP direct 和 spin NEP，角向描述符扩展至 l_max=8。
• Python 与 ASE：支持 NumPy batch、ASE calculator、模型信息检查和 descriptor 输出。
• LAMMPS：提供 CPU nep/cpu 和 CUDA Kokkos nep/gpu/kk；nep/gpu 与 nep/gpu/kk/device 为兼容别名。

📦 安装与平台

支持 CPython 3.10–3.14：

• Linux x86_64：CPU + CUDA
• Windows x86_64：CPU + CUDA
• macOS x86_64 / arm64：CPU

python -m pip install "nep-adapters[ase]"

Linux 和 Windows wheel 已包含 CUDA Runtime，使用 CUDA 后端只需兼容的 NVIDIA 驱动。

🧪 验证

• CPU/CUDA 普通、spin 及 l_max=5..8 一致性测试通过。
• RTX 4090 CUDA Release 测试 29/29 通过。
• Windows CUDA wheel 已在 GTX 1050 Ti 上完成真实计算验证。
• CPU OpenMP、LAMMPS MPI、wheel 内容及隔离安装检查通过。

⚠️ 当前边界

• Python batch 要求全周期边界。
• CUDA 暂不支持 dipole、polarizability、DFT-D3、type-dependent cutoff、typewise/flexible ZBL 和双隐藏层 ANN。
• qNEP CUDA wheel 使用 direct reciprocal-space；LAMMPS CUDA Kokkos 暂不支持 qNEP。
• LAMMPS GPU 仅支持 CUDA Kokkos device 路径；spin MPI 的正式验证范围为单节点。

Full Changelog: https://github.com/MagTheoryLab/NEPAdapters/commits/v1.0.0