docs: refresh project landing pages - #5951
Conversation
Highlight pretrained models and the current DeePMD-kit feature set with Markdown-first repository and documentation landing pages. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe README and Sphinx landing page were rewritten as structured DeePMD-kit overviews. They now cover capabilities, workflows, installation, pretrained models, integrations, references, licensing, and documentation navigation. ChangesDocumentation homepage refresh
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@doc/index.rst`:
- Around line 243-255: Update the homepage to include a visible root navigation
entry covering Getting Started, User Guide, Tutorials and Publications,
Developer Guide, and Project Details. Remove or replace the hidden-only root
toctree declarations in doc/index.rst, preserving their existing section targets
and labels so all listed sections appear in the global navigation.
In `@README.md`:
- Around line 73-77: Update the README installation instructions so the default
command uses a pinned package-manager or container artifact instead of piping
the unpinned dp1s.deepmodeling.com script directly to bash. If retaining the
installer, reference a versioned artifact and document checksum or signature
verification before execution.
- Line 5: Update the tagline heading in README.md from H3 to H2, changing “###
From first-principles data to scalable molecular dynamics—through one open
framework” to use “##” so the document outline follows the H1.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ea56284b-d5e8-4099-8808-0477be7307e4
📒 Files selected for processing (2)
README.mddoc/index.rst
Keep the responsive picture element for light and dark logo variants while retaining Markdown for the rest of the README. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
There was a problem hiding this comment.
Pull request overview
Refreshes the repository and documentation landing pages to better highlight DeePMD-kit’s modern Deep Potential model portfolio and pretrained DPA workflows, while routing most calls-to-action to the hosted docs.
Changes:
- Replaces
README.mdwith a docs-forward landing page featuring pretrained models, a guided workflow overview, and updated navigation links. - Rebuilds
doc/index.rstinto a card-based Sphinx Design homepage with clearer “choose your path” navigation and curated highlights. - Adjusts Sphinx index to use hidden toctrees and modern section structure while keeping existing doc entry points.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| README.md | New Markdown-first repo homepage emphasizing pretrained DPA models, workflow overview, and hosted-docs navigation. |
| doc/index.rst | New Sphinx landing page using responsive cards/grids and reorganized entry points for key docs sections. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Restore the three general DeePMD-kit software references and DOI links on the documentation landing page while retaining the method-specific citation guide. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
Restore the DOI and live citation-count badges for all three general DeePMD-kit publications in the README. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
Restore the original download and status badges, keep the tagline out of the heading hierarchy, and preserve the documentation homepage's numbered global navigation. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
Remove the unpinned remote installer from the repository landing page and route readers to the maintained backend-specific installation guide. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (5)
README.md:45
- Same as above:
> [!TIP]is GitHub-specific and will display verbatim on PyPI/other Markdown renderers. Switching to a plain> **Tip:** ...keeps the callout readable everywhere.
> [!TIP]
> On supported descriptors and workloads, [model compression][compression] can
> deliver more than **10× inference speedup** and reduce memory usage by as much
> as **20×**. Actual gains depend on the model, system, and hardware.
README.md:177
> [!NOTE]is also GitHub-specific. If README.md is consumed outside GitHub (e.g., PyPI via the configured README metadata), this will render as literal[!NOTE]text rather than a callout. Use a plain blockquote label for portability.
> [!NOTE]
> Working with an AI coding or scientific agent? DeePMD-kit ships
> [official Agent Skills][agent-skills] for model selection, training,
README.md:24
- The GitHub-flavored admonition marker (
> [!IMPORTANT]) is not part of standard Markdown and renders as literal text on PyPI/other renderers (this repo publishes README.md to PyPI via scikit-build-corefancy_pypi_readme). Consider using a renderer-agnostic blockquote label so the emphasis survives everywhere.
This issue also appears in the following locations of the same file:
- line 42
- line 174
> [!IMPORTANT]
> DeePMD-kit turns quantum-mechanical reference data into fast, scalable
> interatomic potentials. It combines modern Deep Potential architectures,
> multiple machine-learning backends, adaptation workflows, and
> simulation-ready deployment in one open-source toolkit.
README.md:74
- The quick-install guidance currently promotes a
curl | bashpipeline as the “fastest installation path”. That pattern is inherently risky because it executes remote content without review; it would be safer to add an explicit note to review the script (or point to the installer details) before running.
DeePMD-kit requires Python 3.10 or later. Choose the supported package for your
README.md:57
- The Mermaid diagram will render on GitHub, but it won’t render on PyPI and some other Markdown targets (this repo publishes README.md to PyPI via
fancy_pypi_readme). Consider adding a short plain-text fallback immediately after the diagram, or replacing the Mermaid block with a simple Markdown list so the workflow remains readable everywhere.
```mermaid
flowchart LR
A["Reference data"] --> B["Train or adapt"]
B --> C["Test, compress, export"]
C --> D["Python and native APIs"]
Keep the repository homepage aligned with the maintained installation guide by restoring the official dp1s quick-install command. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
Keep the theme-aware README logo linked to the hosted logo usage guide instead of the general documentation landing page. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #5951 +/- ##
==========================================
+ Coverage 79.16% 79.23% +0.06%
==========================================
Files 1068 1073 +5
Lines 123852 125299 +1447
Branches 4522 4564 +42
==========================================
+ Hits 98053 99286 +1233
- Misses 24181 24371 +190
- Partials 1618 1642 +24 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
|
||
| | | Advantage | What it unlocks | | ||
| | --- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | 🧠 | **Modern model portfolio** | Start with efficient DeepPot-SE descriptors or move to [DPA-1, DPA-2, DPA-3, and DPA-4/SeZM][model-guide] for attention, message passing, large atomic models, and SO(3)-equivariant learning. | |
There was a problem hiding this comment.
| | 🧠 | **Modern model portfolio** | Start with efficient DeepPot-SE descriptors or move to [DPA-1, DPA-2, DPA-3, and DPA-4/SeZM][model-guide] for attention, message passing, large atomic models, and SO(3)-equivariant learning. | | |
| | 🧠 | **Modern model portfolio** | Start with efficient DeepPot-SE descriptors or move to [DPA][model-guide] for large atomic models. | |
There was a problem hiding this comment.
Applied. The "Modern model portfolio" row now links [DPA][model-guide] and mentions large atomic models, dropping the per-model enumeration.
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
| :link-type: doc | ||
| :shadow: md | ||
|
|
||
| Compare DeepPot-SE, DPA-1, DPA-2, DPA-3, DPA-4/SeZM, and specialized |
There was a problem hiding this comment.
| Compare DeepPot-SE, DPA-1, DPA-2, DPA-3, DPA-4/SeZM, and specialized | |
| Compare DeepPot-SE, DPA-1, DPA-2, DPA-3, DPA-4 and specialized |
There was a problem hiding this comment.
Applied. The card now reads "Compare DeepPot-SE, DPA-1, DPA-2, DPA-3, DPA-4, and specialized physics models."
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
There was a problem hiding this comment.
do not use dpa4/sezm, use dpa4 instead.
There was a problem hiding this comment.
Replaced every "DPA-4/SeZM" / "DPA-4 / SeZM" mention with "DPA-4" across doc/index.rst and README.md.
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
| The goal of Deep Potential is to employ deep learning techniques and realize an inter-atomic potential energy model that is general, accurate, computationally efficient and scalable. The key component is to respect the extensive and symmetry-invariant properties of a potential energy model by assigning a local reference frame and a local environment to each atom. Each environment contains a finite number of atoms, whose local coordinates are arranged in a symmetry-preserving way. These local coordinates are then transformed, through a sub-network, to so-called _atomic energy_. Summing up all the atomic energies gives the potential energy of the system. | ||
| - [DPA-3 water training](./examples/water/dpa3/input_torch.json) | ||
| - [DPA-4/SeZM water training](./examples/water/dpa4/input.json) | ||
| - [PyTorch multi-task training](./examples/water_multi_task/pytorch_example/input_torch.json) |
There was a problem hiding this comment.
| - [PyTorch multi-task training](./examples/water_multi_task/pytorch_example/input_torch.json) | |
| - [Multi-task training](./examples/water_multi_task/pytorch_example/input_torch.json) |
There was a problem hiding this comment.
Applied: the bullet now reads "Multi-task training".
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
| - C API to interface with the third-party packages. | ||
| potential = DeepPot("DPA-3.2-5M") | ||
| ``` | ||
|
|
There was a problem hiding this comment.
add a subsection here shortly describe how to finetune.
There was a problem hiding this comment.
Added a "Fine-tune a pretrained model" subsection with a dp pretrained download + dp train input.json --finetune <path> example and links to the fine-tuning guide and DPA-ADAPT.
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
| | Family | A strong starting point when you need | | ||
| | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | ||
| | **DeepPot-SE** | An efficient, established baseline with broad backend and deployment support. | | ||
| | **DPA-1** | Attention-based local representations and type embedding. | | ||
| | **DPA-2** | Multi-task pretraining, shared representations, and smooth conservative potentials. | | ||
| | **DPA-3** | Message passing over line-graph representations and broad chemical coverage. | | ||
| | **DPA-4 / SeZM** | SO(3)-equivariant learning, LoRA fine-tuning, optional ZBL bridging, spin support, and compiled `.pt2` deployment. | |
There was a problem hiding this comment.
information is not useful for beginners. better to remove.
actually, we do not need to list all the models. the dpa4 IS the model for large atomistic models , while dpa4c is for distillation.
There was a problem hiding this comment.
Removed the per-model "Choose a model family" table and replaced it with a short paragraph: DeepPot-SE as the default, DPA-4 as the model for large atomistic models, with a pointer to the model guide for comparison.
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
wanghan-iapcm
left a comment
wanghan-iapcm
left a comment
There was a problem hiding this comment.
This is a clear improvement and I want to say that first -- the old README had become a chronological artifact, and reorganising around what a reader is trying to do, with feature detail pushed to the hosted docs rather than duplicated in-repo, is the right call. Confining the change to two files to avoid conflicts is also appreciated.
I checked the substantive claims rather than the prose. Everything I could falsify holds: dp pretrained download DPA-3.2-5M and DeepPot("DPA-3.2-5M") are both real (deepmd/main.py, deepmd/pretrained/registry.py); "Python 3.10 or later" matches requires-python; the 10x/20x compression figures are verbatim from doc/freeze/compress.md; all 28 :doc: targets, every relative example path, and all 27 hosted-doc URLs resolve; sphinx_design is in the extensions list. I also specifically checked that the doc/index.rst rewrite drops nothing structural -- the toctrees and every .. _label are byte-identical to the base, so no page became unreachable.
Two things I would like you to look at, neither of them blocking. One is a claim the doc tree contradicts, the other is content that leaves the repository entirely. Both inline.
| ``` | ||
| ### Simulation and workflow integrations | ||
|
|
||
| - [LAMMPS], [i-PI][ipi], [ASE], [GROMACS], |
There was a problem hiding this comment.
GROMACS does not belong in this tier.
The rewrite introduces a distinction the old README did not have: this first bullet reads as the in-tree, maintained interfaces, and the line below it separates out "Ecosystem integrations for OpenMM, Amber, CP2K, ABACUS, DP-GEN, and MLatom". But doc/third-party/gromacs.md, which this PR does not touch, opens with:
:::{deprecated} v3.2.0
The official in-tree GROMACS patch was removed from DeePMD-kit in v3.2.0 and is no longer maintained.
:::
and goes on to say DeePMD-kit "may still be used with GROMACS through third-party integrations maintained outside this repository" -- which is precisely the second bullet's category. So the new grouping tells a reader that GROMACS has the same standing as LAMMPS and ASE, when the page it leads to says the opposite.
This is introduced here rather than inherited: the old README had a single flat list ("including LAMMPS, i-PI, AMBER, CP2K, GROMACS, OpenMM, and ABACUS") that made no maintenance claim either way. Adding the tiering is an improvement; GROMACS just landed on the wrong side of it.
Two mitigations I weighed and do not think close it: doc/third-party/index.rst still lists gromacs in the same toctree as the live pages, but a toctree is navigation, not a status claim; and the sentence below does point at the integration hub "for maintained interfaces ... and supported scope", which hedges but does not undo the grouping. Moving GROMACS to the ecosystem bullet should be all it needs.
There was a problem hiding this comment.
Moved GROMACS from the maintained-interface bullet to the ecosystem-integration bullet, consistent with its deprecation status in doc/third-party/gromacs.md.
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
| # Contributing | ||
| If DeePMD-kit contributes to published work, cite the general software paper | ||
| that matches the version used and the method-specific papers listed in | ||
| [CITATIONS.bib](./CITATIONS.bib): |
There was a problem hiding this comment.
This line is where a small content loss becomes visible.
The removed "Highlights in major versions" section carried the repository's only references to two foundational papers -- [1]: https://arxiv.org/abs/1707.01478 (the original Deep Potential paper) and [4]: https://aip.scitation.org/doi/full/10.1063/1.5027645 (DeePCG). I checked whether they survive anywhere: git grep -lI "1707.01478" and git grep -lI "5027645" each match README.md and nothing else, and neither DOI appears in CITATIONS.bib or under doc/. After this PR they are gone from the repo.
That makes this sentence's advice unfollowable for those two methods specifically: it directs the reader to the method-specific papers in CITATIONS.bib, which does not contain them.
The DeePCG one costs a little more than a citation. The deleted paragraph ("In addition to building up potential energy models, DeePMD-kit can also be used to build up coarse-grained models...") is the only place in the repository that mentions coarse-grained modelling at all -- git grep -i "coarse.grain" over doc/ and deepmd/ returns nothing. So a documented capability disappears along with its reference.
The other two footnotes are fine and I am not asking about them: [2] PhysRevLett.120.143001 is in CITATIONS.bib as Zhang_PhysRevLett_2018_v120_p143001, and [3] arXiv:1805.09003 survives in doc/model/train-se-e2-a.md. (Worth noting [1] and [2] are different papers, not a preprint/published pair -- the old README's own prose distinguishes them.)
Adding the two entries to CITATIONS.bib would close this without putting any of the removed prose back, which I assume is what you want.
Separately and much smaller, since it is the same section: the removed "See our v2 paper for details of all features until v2.2.3 / ... until v3.0" lines were the only text mapping each general software paper to the version range it covers, and doc/credits.rst does not supply it either. The instruction just above to cite "the general software paper that matches the version used" is now hard to act on from the README alone. A short parenthetical after each entry would do it.
There was a problem hiding this comment.
Restored the lost references: added the Deep Potential paper (arXiv:1707.01478) and the DeePCG paper (10.1063/1.5027645) to CITATIONS.bib, and added version-range parentheticals to each software-paper entry (initial version / until v2.2.3 / until v3.0).
Coding agent: opencode
opencode version: 1.18.9
Model: ustc/deepseek-v4-flash
Reasoning effort: max
- rename DPA-4/SeZM to DPA-4 - prune per-model table for beginners; note finetune subsection - move GROMACS to ecosystem integrations tier - restore lost citation entries (Deep Potential, DeePCG) in CITATIONS.bib - add version-range parentheticals to citation list Coding-Agent: opencode opencode-Version: 1.18.9 Model: ustc/deepseek-v4-flash Reasoning-Effort: max
for more information, see https://pre-commit.ci
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
Suppressed comments (1)
CITATIONS.bib:93
- The PR description says the change is isolated to
README.mdanddoc/index.rst, but this PR also modifiesCITATIONS.bib(adds new references). This can affect review scope and conflict risk for parallel documentation work.
@article{Han_CommunComputPhys_2018_v23_p629,
annote = {Deep Potential},
title = {
{Deep Potential: A General Representation of a Many-Body Potential Energy
Surface}
iProzd
left a comment
iProzd
left a comment
There was a problem hiding this comment.
The requested landing-page follow-ups are otherwise addressed: the DPA-4 naming, model-selection simplification, GROMACS tiering, and restored foundational citations all look good. One blocking issue remains in the new fine-tuning quick start: it dispatches the downloaded PyTorch checkpoint to the default TensorFlow backend.
| - Plugin mechanisms for external models. | ||
| ```bash | ||
| dp pretrained download DPA-3.2-5M | ||
| dp train input.json --finetune <path-to-downloaded-model> |
There was a problem hiding this comment.
This command selects TensorFlow by default (deepmd/main.py), while DPA-3.2-5M downloads as a PyTorch .pt checkpoint. As written, the copy-paste example dispatches to the wrong trainer and cannot fine-tune the advertised model. Please make the PyTorch route explicit (at minimum, dp --pt train ...) and align the remaining arguments with the documented DPA3 fine-tuning workflow, including the appropriate pretrained-script/branch choice when using this built-in multi-task checkpoint.
There was a problem hiding this comment.
Thanks, fixed in c440a4a. DPA-3.2-5M is a PyTorch multi-task checkpoint, so the example now uses dp --pt train and selects a task branch with --model-branch (listable via dp --pt show <path> model-branch).
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.
Suppressed comments (1)
CITATIONS.bib:103
- The PR description says the change is isolated to
README.mdanddoc/index.rst, but this PR also adds new entries toCITATIONS.bib. That’s a mismatch for reviewers and for conflict avoidance with other documentation work.
Please either (a) update the PR description/scope to explicitly include CITATIONS.bib changes, or (b) move these citation additions into a separate PR if you want to keep this one scoped to landing pages only.
@article{Han_CommunComputPhys_2018_v23_p629,
annote = {Deep Potential},
title = {
{Deep Potential: A General Representation of a Many-Body Potential Energy
Surface}
},
author = {Jiequn Han and Linfeng Zhang and Roberto Car and Weinan E},
journal = {Commun. Comput. Phys.},
year = 2018,
volume = 23,
number = 3,
pages = {629--639},
doi = {10.4208/cicp.OA-2017-0213},
url = {https://arxiv.org/abs/1707.01478},
}
Summary
README.mdanddoc/index.rstto avoid conflicts with other documentation work.Validation
ruff check .ruff format .git diff --checksphinx-designFixes #5240
Coding agent: Codex
Codex version: codex-cli 0.144.6
Model: gpt-5.6-sol
Reasoning effort: xhigh
Summary by CodeRabbit