docs: add docs about LAMMPS D3 dispersion #4875
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation about using LAMMPS D3 dispersion corrections with DeePMD-kit models. The documentation explains that it's more efficient to train models on plain DFT data without dispersion and add the dispersion correction during simulation using LAMMPS commands.
- Adds a new section to LAMMPS command documentation explaining D3 dispersion integration
- Includes practical examples of using
pair_style dispersion/d3with DeePMD models - Updates existing documentation to discourage training directly against dispersion-corrected data
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| examples/water/d3/README.md | Adds important note discouraging training against dispersion-corrected data |
| doc/third-party/lammps-command.md | Adds new D3 dispersion section with examples and reorganizes content structure |
| doc/model/pairtab.md | Adds note referencing the new D3 dispersion documentation |
| doc/index.rst | Updates citation with DeePMD-kit v3 reference |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Jinzhe Zeng <njzjz@qq.com>
Contributor
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughThe documentation was updated to add a new citation for the DeePMD-kit v3 paper and to clarify best practices for applying D3 dispersion corrections. Instructions and notes were added to multiple documentation files, emphasizing that dispersion corrections should be applied during simulation rather than during model training. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant DeePMD Model
participant LAMMPS
participant D3 Dispersion
User->>DeePMD Model: Train model (without dispersion correction)
User->>LAMMPS: Set up simulation with DeePMD model
User->>LAMMPS: Add pair_style dispersion/d3
LAMMPS->>D3 Dispersion: Apply D3 correction during simulation
LAMMPS->>User: Output results (with D3 correction applied)
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Note 🔌 MCP (Model Context Protocol) integration is now available in Early Access!Pro users can now connect to remote MCP servers under the Integrations page to get reviews and chat conversations that understand additional development context. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (27)
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
examples/water/d3/README.md (1)
3-6: Tighten wording and fix grammar in the IMPORTANT noteImprove readability and correctness; no technical content change.
> [!IMPORTANT] - > It is more efficiently to train a model using plain DFT calculations without the dispersion correction, and add the dispersion correction during the simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command). - > Train against data with dispersion directly is discouraged. + > It is more efficient to train models on plain DFT calculations (without dispersion corrections) and to add the dispersion correction during simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command). + > Training directly against dispersion‑corrected data is discouraged.doc/model/pairtab.md (1)
106-112: Polish the note’s wording (grammar/clarity)Small grammar fixes; no change in meaning.
-:::{note} -The above example shows a example of combining D3 dispersion. -However, it is more efficiently to train a model using plain DFT calculations without the dispersion correction, and add the dispersion correction during the simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command). -Train against data with dispersion directly is discouraged. -See the [D3 dispersion section](../third-party/lammps-command.md#d3-dispersion) for details. -::: +:::{note} +The above is an example of combining D3 dispersion. +However, it is more efficient to train models on plain DFT calculations (without dispersion corrections) and to add the dispersion correction during simulation via the LAMMPS [`pair_style dispersion/d3` command](https://docs.lammps.org/pair_dispersion_d3.html#pair-style-dispersion-d3-command). +Training directly against dispersion‑corrected data is discouraged. +See the [D3 dispersion section](../third-party/lammps-command.md#d3-dispersion) for details. +:::doc/third-party/lammps-command.md (2)
267-276: Minor wording fix in the examples lead-inTighten phrasing.
-In order of computing the 9-component per-atom stress +To compute the 9‑component per‑atom stress
294-303: Fix typo “detailes” → “details”Small editorial cleanup.
-`c_flux` is a global vector of length 6. The first three components are the $x$, $y$ and $z$ components of the full heat flux vector. The others are the components of the so-called convective portion, see [LAMMPS doc page](https://docs.lammps.org/compute_heat_flux.html) for more detailes. +`c_flux` is a global vector of length 6. The first three components are the $x$, $y$, and $z$ components of the full heat flux vector. The others are the components of the so-called convective portion; see the [LAMMPS doc page](https://docs.lammps.org/compute_heat_flux.html) for more details.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
doc/index.rst(1 hunks)doc/model/pairtab.md(1 hunks)doc/third-party/lammps-command.md(6 hunks)examples/water/d3/README.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2024-10-08T15:32:11.479Z
Learnt from: 1azyking
PR: deepmodeling/deepmd-kit#4169
File: examples/hessian/single-task/input.json:3-59
Timestamp: 2024-10-08T15:32:11.479Z
Learning: In the deepmd-kit project, having different `rcut` values for `repinit` and `repformer` is acceptable when they align with existing configurations, such as in `examples/water/dpa2/input_torch.json`.
Applied to files:
doc/model/pairtab.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (29)
- GitHub Check: Test Python (6, 3.9)
- GitHub Check: Test Python (6, 3.12)
- GitHub Check: Test Python (4, 3.9)
- GitHub Check: Test Python (4, 3.12)
- GitHub Check: Test Python (5, 3.12)
- GitHub Check: Test Python (2, 3.12)
- GitHub Check: Test Python (5, 3.9)
- GitHub Check: Test Python (2, 3.9)
- GitHub Check: Test Python (3, 3.9)
- GitHub Check: Test Python (1, 3.12)
- GitHub Check: Test Python (3, 3.12)
- GitHub Check: Test Python (1, 3.9)
- GitHub Check: Analyze (python)
- GitHub Check: Test C++ (false)
- GitHub Check: Test C++ (true)
- GitHub Check: Build wheels for cp311-macosx_arm64
- GitHub Check: Build wheels for cp311-macosx_x86_64
- GitHub Check: Build wheels for cp311-manylinux_x86_64
- GitHub Check: Build wheels for cp310-manylinux_aarch64
- GitHub Check: Build wheels for cp311-manylinux_x86_64
- GitHub Check: Build wheels for cp311-win_amd64
- GitHub Check: Analyze (c-cpp)
- GitHub Check: Build C library (2.14, >=2.5.0,<2.15, libdeepmd_c_cu11.tar.gz)
- GitHub Check: Build C++ (cuda, cuda)
- GitHub Check: Build C library (2.18, libdeepmd_c.tar.gz)
- GitHub Check: Build C++ (clang, clang)
- GitHub Check: Build C++ (cpu, cpu)
- GitHub Check: Build C++ (cuda120, cuda)
- GitHub Check: Build C++ (rocm, rocm)
🔇 Additional comments (1)
doc/third-party/lammps-command.md (1)
232-232: Section reorganization LGTMIntroducing “Combine with other commands” improves discoverability and structure.
Signed-off-by: Jinzhe Zeng <jinzhe.zeng@ustc.edu.cn>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## devel #4875 +/- ##
=======================================
Coverage 84.70% 84.70%
=======================================
Files 700 700
Lines 68146 68146
Branches 3542 3542
=======================================
+ Hits 57720 57722 +2
- Misses 9291 9292 +1
+ Partials 1135 1132 -3 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
wanghan-iapcm
approved these changes
Aug 11, 2025
7 tasks
ChiahsinChu
pushed a commit
to ChiahsinChu/deepmd-kit
that referenced
this pull request
Dec 17, 2025
This addresses deepmodeling#3099. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a new citation for the "DeePMD-kit v3" paper to the list of recommended references. * Clarified best practices for applying D3 dispersion corrections, advising users to train models without dispersion and apply corrections during simulation. * Introduced a new section in the documentation explaining how to combine DeePMD models with D3 dispersion in LAMMPS, including example commands. * Updated example README files with guidance on efficient model training and use of dispersion corrections. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Jinzhe Zeng <njzjz@qq.com> Signed-off-by: Jinzhe Zeng <jinzhe.zeng@ustc.edu.cn> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This addresses #3099.
Summary by CodeRabbit