Skip to content

refactor(md): unify classical potential ESolvers - #8314

Merged
mohanchen merged 21 commits into
deepmodeling:developfrom
19hello:refactor/unify-md-potential-esolver
Nov 16, 2026
Merged

mohanchen merged 21 commits into
deepmodeling:developfrom
19hello:refactor/unify-md-potential-esolver

Conversation

@19hello

@19hello 19hello commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Reminder

  • I have read AGENTS.md and docs/developers_guide/agent_governance.md.
  • No linked issue; this refactor was requested directly by a developer.
  • Focused unit tests and runtime case checks are included below.
  • Exact verification commands and results are listed below.
  • User-visible behavior and core-module impact are described below.
  • No governance exception is requested.

Linked Issue

No issue linked; developer-requested ESolver refactor.

Unit Tests and/or Case Tests for my changes

Commands run on the final branch:

  • cmake -S . -B build_parallel_md1_current -DBUILD_TESTING=ON — passed.
  • cmake --build build_parallel_md1_current -j12 --target MODULE_MD_LJ_potential MODULE_MD_SNAP_potential MODULE_MD_DP_potential MODULE_MD_NEP_potential MODULE_MD_fire MODULE_MD_verlet MODULE_MD_nhc MODULE_MD_msst MODULE_MD_lgv — passed (the LJ target was rebuilt after consolidating its tests).
  • OMP_NUM_THREADS=1 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^MODULE_MD_(LJ_potential|SNAP_potential|DP_potential|NEP_potential|func|run|fire|verlet|nhc|msst|lgv)$' — 11/11 passed.
  • cmake -S . -B build_abacus_nep_gnu -U ENABLE_RAPIDJSON -DBUILD_TESTING=ON — passed with DeePMD and NEP enabled.
  • cmake --build build_abacus_nep_gnu -j12 --target MODULE_MD_DP_potential MODULE_MD_NEP_potential — passed.
  • OMP_NUM_THREADS=1 LD_LIBRARY_PATH=/home/fy19/abacus-develop/.venv-deepmd/lib/python3.10/site-packages/deepmd_kit.libs:/home/fy19/abacus-develop/.venv-deepmd/lib/python3.10/site-packages/tensorflow LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 ctest --test-dir build_abacus_nep_gnu --output-on-failure -R '^MODULE_MD_(DP|NEP)_potential$' — 2/2 passed.
  • cmake --build build_abacus_nep_gnu -j12 --target abacus_basic_para — passed.
  • python3 tools/03_code_analysis/agent_governance_check.py --base origin/develop --head HEAD --format text — passed, warnings only; global dependency count decreased by 20 references.
  • git diff --check origin/develop...HEAD — passed.

For each isolated case directory below, ran the same final build_abacus_nep_gnu/abacus_basic_para binary with OMP_NUM_THREADS=1, the DeePMD library path, and system OpenBLAS preloaded. All exited successfully:

Case Final energy (eV) Reference (eV)
tests/04_FF/03_LJ_FIRE -2.286459049577894 -2.286459049577894
tests/04_FF/102_SNAP_base -0.6215021265460468 -0.62150213
tests/04_FF/101_NEP_HfO2 -243.9772424704461 -243.9772424704458
tests/04_FF/50_DP_Al -2008.606467021707 -2008.606467021982

Checks not run on the final branch: multi-rank DeePMD MDCell, because the installed DeePMD-kit lacks a communication-capable InputNlist constructor. LJ, NEP and SNAP two-rank runtime checks passed before the latest develop merge and were not repeated after it.

What's changed?

  • Introduce one esolver_forcefields adapter for LJ, DeePMD, NEP and SNAP energy/force/stress handling.
  • Move each potential's implementation into source_md/module_lj, module_dp, module_nep and module_snap.
  • Keep the potential interface small: initialize(BaseCell&, const Input_para&) and compute(BaseCell&, energy, force, stress). MDCell implementations write atom forces directly.
  • Update CMake and legacy Makefile source lists, and move touched MD tests into the flat source_md/unittests layout.
  • Preserve LJ/DeePMD/NEP STRU.cif output; pass output directory and log stream explicitly into LJ instead of reading globals inside it.

Governance Notes

  • INPUT/docs changes: no INPUT parameter changes; no documentation update needed for this internal refactor. The shared adapter standardizes potential energy/final-energy log formatting, including SNAP.
  • Core module impact: source_esolver owns only dispatch and result reporting; potential calculation logic lives in source_md. Remaining global reads are at the factory/test boundary; the PR-level global dependency budget is reduced by 20.
  • Exceptions requested: none.

CI follow-up (2026-11-13)

  • Fixed the relocated MD fixture header include; locally rebuilt MODULE_MD_func and passed its CTest target.
  • Made MODULE_MD_SNAP_potential create its model files under testing::TempDir(), removing its source-tree path dependency. Locally rebuilt the target and passed OMP_NUM_THREADS=1 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^MODULE_MD_SNAP_potential$'. The subsequent CI Module_MD Unittests step passed.
  • The unified solver now prints final SNAP energy at full precision (std::setprecision(16)), while the existing 105/106 regression references retained the prior six-decimal LAMMPS value. Both calculations reported 54.90956145 eV and 18.30318715 eV/atom; the difference from the rounded reference exceeded the existing 1e-7 eV threshold. Updated only these two energy references to the reported precision. The independent six-decimal LAMMPS value remains documented, and force/stress references and thresholds are unchanged.
  • cmake --build build_parallel_md1_current -j12 --target abacus_basic_para — passed. OMP_NUM_THREADS=1 LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 bash ../integrate/Autotest.sh -a /home/fy19/abacus-develop/build_parallel_md1_current/abacus_basic_para -n 4 -r '^(105_SNAP_quad|106_SNAP_scf)$' -j 1 from tests/04_FF — passed (8/8 property checks). Sandbox MPI launch could not create sockets; an unrestricted first run exposed the local BLAS gotoblas symbol mismatch, resolved by preloading the system OpenBLAS for this verification run.
  • python3 tools/03_code_analysis/agent_governance_check.py --staged and git diff --cached --check — passed for both follow-up commits. Full CI rerun for the final commit 1401e74bb passed: Integration Test and Unit Test (including Module_MD Unittests and 04_FF), CUDA Test, both Build Test workflows, Pyabacus Build and Test, ASE Plugin Test, Precommit, and Agent Governance.

Review follow-up (2026-11-15)

  • Renamed the shared solver to the requested lowercase esolver_forcefields; the filename, class, factory, CMake, and legacy Makefile entries match. No INPUT behavior changed, so no user documentation change is needed.
  • Corrected MDCell energy and virial reductions in LJ, DP, NEP, and SNAP to use each cell's communicator through ModuleBase::CommunicationDomain; the old world reduction could mix independent cells. Added an MPI LJ regression using MPI_COMM_SELF on four world ranks. This is a focused MPI unit test: Autotest cannot construct an MDCell on an isolated communicator.
  • Forward-declared ModuleBase::matrix in source_md/potential.h; module_lj/lj.h includes the full header because it stores matrix values. LJ, DP, and NEP now log the absolute STRU.cif path after writing.
  • Verification: cmake --build build_parallel_md1_current -j12 --target abacus_basic_para passed; OMP_NUM_THREADS=1 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^MODULE_MD_(LJ|SNAP|DP|NEP)_potential$' passed 4/4; OMP_NUM_THREADS=1 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^MODULE_MD_LJ_potential_mpi_np4$' passed 1/1 outside the sandbox; OMP_NUM_THREADS=1 LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^04_FF$' passed 1/1 outside the sandbox. The local executable reported ABACUS version v3.11.0-beta13 with the same OpenBLAS preload. cmake --build build_abacus_nep_gnu -j12 --target MODULE_MD_DP_potential MODULE_MD_NEP_potential and its focused CTest run passed 2/2 before the final call-site-only cleanup.
  • python3 tools/03_code_analysis/agent_governance_check.py --base origin/develop --head HEAD --format text passed with warnings only; global dependency references remain down by 20. The new LJ header needs the complete matrix type for value members. git diff --check origin/develop...HEAD passed.

CI follow-up (2026-11-15)

  • The first review-fix CI run built and passed Module_MD Unittests, but 04_FF failed in five LJ cases because CifParser::write creates STRU.cif only on world rank 0 while the new absolute-path confirmation called realpath on every rank. Nonzero ranks could check the path before the file existed. Commit 177d13553 limits path resolution and confirmation to the writing rank; it does not change the CIF contents or physics.
  • After this fix, cmake --build build_parallel_md1_current -j12 --target abacus_basic_para and OMP_NUM_THREADS=1 LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^04_FF$' passed locally. This is the existing Autotest integration suite; no new integration driver was needed. Final CI rerun for 177d13553 passed: Integration Test and Unit Test (including Module_MD Unittests and 04_FF), CUDA Test, both Build Test workflows, Pyabacus Build and Test, ASE Plugin Test, Precommit, and Agent Governance.

Develop sync (2026-11-15)

  • Merged origin/develop at 173620a12e into the PR branch as da8e889ac without conflicts or force-push. The incoming change concerns DFT+U and does not alter this PR's force-field code.
  • cmake --build build_parallel_md1_current -j12 --target abacus_basic_para MODULE_MD_LJ_potential MODULE_MD_SNAP_potential MODULE_MD_DP_potential MODULE_MD_NEP_potential MODULE_MD_LJ_potential_mpi MODULE_PW_dftu_base_test — passed.
  • OMP_NUM_THREADS=1 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^(MODULE_MD_(LJ|SNAP|DP|NEP)_potential|MODULE_PW_dftu_base_test)$' — MD 4/4 passed; DFT+U initially failed due to the local BLAS gotoblas symbol mismatch. Repeating the DFT+U test with LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 passed 1/1.
  • OMP_NUM_THREADS=1 LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^(MODULE_MD_LJ_potential_mpi_np4|04_FF)$' — passed 2/2 outside the sandbox.
  • git diff --check origin/develop...HEAD and python3 tools/03_code_analysis/agent_governance_check.py --base origin/develop --head HEAD --format text — passed; governance warnings only.

Header naming follow-up (2026-11-16)

  • Renamed source/source_md/potential.h to forcefield.h, updated its include guard and all direct includes. This commit only renamed the header; the subsequent class rename is described below. Neither change affects INPUT or user-facing documentation.
  • The four implementation headers must include forcefield.h because they derive from the complete ModuleMD::Potential type; these are replacements for their previous potential.h includes, not additional dependencies.
  • cmake --build build_parallel_md1_current -j12 --target abacus_basic_para MODULE_MD_LJ_potential MODULE_MD_SNAP_potential MODULE_MD_DP_potential MODULE_MD_NEP_potential — passed. OMP_NUM_THREADS=1 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^MODULE_MD_(LJ|SNAP|DP|NEP)_potential$' — passed 4/4. python3 tools/03_code_analysis/agent_governance_check.py --staged — passed with warnings only; git diff --cached --check — passed.

Base class naming follow-up (2026-11-16)

  • Renamed the MD force-field base class ModuleMD::Potential to ModuleMD::ForceField in forcefield.h; updated all four derived classes, the ESolver adapter/factory, and the affected LJ tests. The concrete class names and numerical algorithms are unchanged. This is an internal C++ interface rename; no INPUT or user-facing documentation change is needed.
  • cmake --build build_parallel_md1_current -j12 --target abacus_basic_para MODULE_MD_LJ_potential MODULE_MD_SNAP_potential MODULE_MD_DP_potential MODULE_MD_NEP_potential MODULE_MD_LJ_potential_mpi — passed.
  • OMP_NUM_THREADS=1 LD_PRELOAD=/usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblas.so.0 ctest --test-dir build_parallel_md1_current --output-on-failure -R '^(MODULE_MD_(LJ|SNAP|DP|NEP)_potential|MODULE_MD_LJ_potential_mpi_np4|04_FF)$' — passed 6/6 outside the sandbox.
  • python3 tools/03_code_analysis/agent_governance_check.py --staged — passed with a documentation-review warning; git diff --cached --check — passed.

@mohanchen mohanchen added MD & LAM MD and Larege Atomic Models Refactor Refactor ABACUS codes The Absolute Zero Reduce the "entropy" of the code to 0 labels Nov 13, 2026
Comment thread source/source_esolver/CMakeLists.txt Resolved

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The refactor changes the reduction domain for MDCells created with a custom communicator; the normal Run_MD world-communicator path does not trigger this issue. Inline feedback also covers two nonblocking cleanup items.

Static review of 1401e74bbf25c669f080872cbb32d3da7d4d37b6 against fcd57f6db2660a2d82bd66dfbc93d78e802600c5. git diff --check passed. No build or runtime/MPI checks were run; CI verification was unavailable, and the extra SNAP reference digits were not regenerated.

Comment thread source/source_md/module_lj/lj.cpp Resolved
Comment thread source/source_md/potential.h Resolved
Comment thread source/source_md/module_lj/lj.cpp Resolved
Comment thread source/source_md/forcefield.h Resolved
@mohanchen
mohanchen merged commit 4e9f163 into deepmodeling:develop Nov 16, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

MD & LAM MD and Larege Atomic Models Refactor Refactor ABACUS codes The Absolute Zero Reduce the "entropy" of the code to 0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants