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
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.
The backend and branch selection are fixed, but the pretrained-script part of the original request is still unaddressed. The PT entrypoint passes change_model_params=use_pretrain_script to get_finetune_rules, so without --use-pretrain-script the selected DPA3 branch does not replace the descriptor/fitting configuration in input.json. This command therefore works as intended only when input.json already reproduces the selected branch architecture exactly; otherwise only compatible parameters can be reused and others may be skipped, reinitialized, or rejected. The README neither states that prerequisite nor links a matching DPA-3.2 fine-tuning input (and the preceding beginner example uses se_e2_a). Please either add --use-pretrain-script to this built-in-model quick start or provide and link an explicitly compatible input configuration.
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},
}
wanghan-iapcm
left a comment
wanghan-iapcm
left a comment
There was a problem hiding this comment.
Everything from both rounds is addressed. I checked against this head rather than the replies.
My two findings:
- GROMACS has moved out of the maintained-interface bullet into the ecosystem one, which is what its
deprecated v3.2.0status calls for. The first bullet is now LAMMPS, i-PI, ASE, JAX MD and nvalchemi, all of which do have live in-tree interfaces. - Both lost references are back, and restored better than I asked. I only pointed out that
arXiv:1707.01478and10.1063/1.5027645would vanish from the repository; adding them to CITATIONS.bib as proper entries -- with the published DOI10.4208/cicp.OA-2017-0213for the Deep Potential paper and the arXiv URL kept alongside, andannote = {coarse-grained model (DeePCG)}matching the file's convention -- is more useful than the bare preprint links the README used to carry. The version parentheticals ("describes the initial version", "covers features until v2.2.3", "until v3.0") also close the smaller point I raised in the same comment, so "cite the paper that matches the version used" is actionable again.
I also verified the new fine-tune snippet rather than assuming it, since it introduces CLI claims that did not exist before: --finetune and --model-branch are both on the train parser in deepmd/main.py, and dp --pt show <path> model-branch is valid -- model-branch is among the show subcommand's ATTRIBUTES choices, and that parser's own help text demonstrates the same invocation. Switching it to dp --pt with an explicit --model-branch is the right call for a multi-task checkpoint like DPA-3.2-5M; the generic dp train --finetune form would have sent people straight into a branch-selection error.
One thing left, inline -- a question rather than an objection.
Approving; this supersedes my earlier changes-requested review.
Remove the DPA-4 feature enumeration from the README's "Choose a model family" section so the hosted documentation homepage owns the detailed comparison, avoiding duplicated claims that could drift. The README now points to DPA-4 and defers to the model guide, while doc/index.rst keeps the per-family comparison table. Coding-Agent: opencode opencode-Version: 1.18.11 Model: ustc/deepseek-v4-flash Reasoning-Effort: max
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:94
- The PR description says the refresh is isolated to
README.mdanddoc/index.rst, but this PR also changesCITATIONS.bib(adds new entries). Please either update the PR description/scope accordingly or split/revert theCITATIONS.bibchanges to keep the PR conflict-minimal as described.
@article{Han_CommunComputPhys_2018_v23_p629,
annote = {Deep Potential},
title = {
{Deep Potential: A General Representation of a Many-Body Potential Energy
Surface}
},
Replace the <path-to-downloaded-model> placeholder with the concrete ~/.cache/deepmd/pretrained/models/DPA-3.2-5M.pt path that 'dp pretrained download DPA-3.2-5M' writes to, and mirror it in the dp --pt show model-branch hint. Coding-Agent: opencode opencode-Version: 1.18.11 Model: ustc/deepseek-v4-flash Reasoning-Effort: max
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. If the intent is to keep the change conflict-free, please either revert theCITATIONS.bibedits or update the PR description/scope to include this file so reviewers and downstream doc work can plan for the additional touchpoint.
@article{Han_CommunComputPhys_2018_v23_p629,
annote = {Deep Potential},
title = {
{Deep Potential: A General Representation of a Many-Body Potential Energy
Surface}
Add the DPA-4 performance graphic to the repository README and the documentation landing page. Authored by OpenClaw (model: custom-chat-jinzhezeng-group/gpt-5.6-terra)
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.
Suppressed comments (3)
README.md:30
- The PyPI long description is generated via
fancy-pypi-readmesubstitutions (seepyproject.toml), and the current substitution rewrites Markdown-style relative links to.../tree/master/.... That regex also matches the[alt](./doc/_static/dpa4-performance.webp)part of this Markdown image, so on PyPI the image URL will likely become a GitHub tree page and not render. Prefer an HTML<img src="...">here so the existingsrc="..."substitution rewrites it to.../raw/master/...for PyPI while keeping GitHub rendering unchanged.
CITATIONS.bib:93
- This PR description says the change is isolated to
README.mdanddoc/index.rst, but this commit also modifiesCITATIONS.bibby adding new entries. Either update the PR description/scope to include this file, or move these citation additions into a separate PR to match the stated isolation constraint.
@article{Han_CommunComputPhys_2018_v23_p629,
annote = {Deep Potential},
title = {
{Deep Potential: A General Representation of a Many-Body Potential Energy
Surface}
CITATIONS.bib:147
pages = 034101has a leading zero; BibTeX normalizes bare numeric tokens and may drop leading zeros, which would render the article number incorrectly. Quote or brace the value to preserve it.
pages = 034101,
Use the project spelling DPA4 in the newly added README and documentation landing-page image text. Authored by OpenClaw (model: custom-chat-jinzhezeng-group/gpt-5.6-terra)
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.
Suppressed comments (2)
doc/index.rst:25
doc/index.rstreferences a.webpimage. While HTML builds will typically render it, Sphinx LaTeX/PDF builders often cannot include WebP directly (depending on ImageMagick/webp delegates). Since this repo’s Sphinx config includes LaTeX settings, consider switching the asset to a PDF/LaTeX-friendly format (e.g., PNG) or adding a LaTeX-only fallback image via.. only:: html/.. only:: latex.
.. figure:: _static/dpa4-performance.webp
:alt: DPA4 delivers competitive energy and force accuracy at high throughput
:width: 100%
:align: center
DPA4 delivers competitive energy and force accuracy at high throughput.
CITATIONS.bib:103
- The PR description says the change is isolated to
README.mdanddoc/index.rst, but this PR also modifiesCITATIONS.bibby adding new bibliography entries. Please either update the PR description/scope to include this file, or split/revert the citation updates into a separate PR so the stated isolation remains accurate.
@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},
}
There was a problem hiding this comment.
The citation guide linked from the new landing page is presented as the canonical source for model- and feature-specific publications, but it does not cover all models already shipped by DeePMD-kit. In particular, the currently merged Deep Potential, DeePCG, DPA3, DPA4, and DeepPopulation documentation points to papers that are absent from doc/credits.rst; DPA3 and DPA4 are also model families prominently advertised on this landing page.
Please make the citation guide complete for the model families currently available in the repository, using CITATIONS.bib as the single bibliography source, and have the individual model pages link to that canonical entry. Models that have not yet been merged are naturally out of scope.
| @@ -33,7 +295,7 @@ DeePMD-kit is a package written in Python/C++, designed to minimize the effort r | |||
| .. toctree:: | |||
| :maxdepth: 3 | |||
| :numbered: | |||
There was a problem hiding this comment.
The rendered RTD preview now presents the same navigation twice: the curated landing-page cards/workflow above, followed here by five fully expanded root toctrees (including the 14-entry numbered User Guide and the complete Developer Guide). That long directory appendix defeats the new landing-page structure and duplicates navigation already available in the sidebar. The root toctrees are still needed to define the documentation hierarchy, but Sphinx :hidden: suppresses only their inline rendering while preserving that hierarchy and sidebar navigation. Please apply :hidden: consistently to these root toctrees so the cards remain the homepage navigation and the toctrees remain the single underlying navigation structure.
There was a problem hiding this comment.
I re-checked this against the current RTD preview from the perspective of the default agent document reader, which requests a page as Markdown rather than interacting with the rendered browser UI. That reader does not receive the site sidebar.
Validation method
- Fetched the current PR preview homepage (
https://deepmodeling--5951.org.readthedocs.build/projects/deepmd/en/5951/) through the default Markdown extractor. - Fetched two representative non-home pages through the same path:
model/index.htmlandmodel/dpa4.html. - Compared the extracted Markdown with the navigation sources in
doc/index.rstand with the preview's rendered-page structure; no source files were changed for this check.
Observed results
- All three requests returned HTTP 200 and Markdown content.
- The homepage Markdown contains the curated cards and then the root toctree material:
Getting Started, the numberedUser Guide,Tutorials and Publications,Developer Guide, andProject Details, including their descendants. This is currently the only complete site-wide navigation exposed to the default Markdown reader. - The
model/index.htmlMarkdown contains that page's own child list, but not the root navigation hierarchy. - The
model/dpa4.htmlMarkdown contains the page body and its in-page headings, but noUser Guide/Modelsidebar tree or other site-wide sidebar navigation. The rendered HTML may display a sidebar to a browser user, but that sidebar is not included in the Markdown extraction.
Therefore :hidden: would preserve the Sphinx/HTML navigation hierarchy for an interactive browser, but it would remove the only comprehensive navigation representation available to an agent using the default Markdown fetch path. In that usage mode, the landing-page cards are useful shortcuts but are not a substitute for a discoverable site map: they omit several top-level sections and do not expose the broader hierarchy.
So I do not think all root navigation should be hidden. A concise visible first-level directory would be preferable to the current recursively expanded appendix for human readers, but retaining a visible directory (or an equivalently complete explicit Markdown-readable navigation block) is necessary for agents.
Authored by OpenClaw 2026.7.1-2 (model: custom-chat-jinzhezeng-group/gpt-5.6-terra)
This seems to be out of scope for this PR. This PR is not aimed at |
njzjz-bot
left a comment
njzjz-bot
left a comment
There was a problem hiding this comment.
I verified the navigation concern from the default agent Markdown-fetch path and replied inline with the procedure and observed output. The browser sidebar is not present in that representation, so a complete Markdown-readable navigation block must remain available; a compact first-level directory would be preferable to the currently fully expanded one.
Authored by OpenClaw 2026.7.1-2 (model: custom-chat-jinzhezeng-group/gpt-5.6-terra)
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