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 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.
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)
Co-authored-by: Duo <50307526+iProzd@users.noreply.github.com> Signed-off-by: Jinzhe Zeng <njzjz@qq.com>
for more information, see https://pre-commit.ci
OutisLi
left a comment
OutisLi
left a comment
There was a problem hiding this comment.
The DPA-3.2-5M fine-tuning quick start is still incorrect on the current HEAD. --model-branch selects the pretrained source branch, but it does not replace the model configuration from that branch: the PT entrypoint passes change_model_params=use_pretrain_script, and --use-pretrain-script is false by default. The README supplies only a generic input.json (with the preceding beginner example using se_e2_a), so copying this command does not construct the selected DPA3 architecture; incompatible parameters may instead be skipped, reinitialized, or rejected. Please either add --use-pretrain-script to this quick-start command or provide and link an explicitly DPA-3.2-compatible input configuration. This re-anchors the earlier review thread that became outdated without the underlying issue being fixed.
OutisLi
left a comment
OutisLi
left a comment
There was a problem hiding this comment.
The citation completeness request remains unresolved. This is within the scope of the landing-page rewrite: the new README states that method-specific papers are listed in CITATIONS.bib, the new documentation landing page directs users to doc/credits.rst for the publications required by the models and features they use, and this PR already modifies CITATIONS.bib. Those claims are currently not true for the models already shipped in the repository. The newly added Deep Potential and DeePCG entries are not exposed by doc/credits.rst, while the merged DPA3, DPA4, and DeepPopulation model pages cite papers that are absent from both the canonical guide and, for the latter model families, CITATIONS.bib. Please complete the canonical citation guide for the model families already present in the repository and keep CITATIONS.bib as the single bibliography source. Unmerged models such as DPA4C are out of scope.
OutisLi
left a comment
OutisLi
left a comment
There was a problem hiding this comment.
The navigation issue remains unresolved. The concern about Markdown-only agent readers is valid, but it does not require rendering five recursively expanded root toctrees after the curated landing-page content. The current :maxdepth: 3 / :maxdepth: 5 blocks duplicate the cards and sidebar, produce a long directory appendix for human readers, and defeat the hierarchy this redesign is trying to establish.
A clean implementation can serve both audiences with two explicit layers:
- Keep the existing task-oriented
Choose your pathcards as the primary human entry point. - Add one compact
Documentation mapsection containing five first-level groups: Getting Started, User Guide, Tutorials and Publications, Developer Guide, and Project Details. Use ordinary:doc:links for the first-level destinations so the links remain visible to Markdown extraction. The User Guide can be one compact row/list of Backend, Installation, Data, Models, Training, Freeze, Test, Inference, DPA-ADAPT, CLI, Integrations, Agent Skills, NVNMD, Environment, and Troubleshooting; descendant pages remain owned by their section index pages. - Mark the canonical root toctrees
:hidden:. They continue to be the single Sphinx hierarchy and sidebar source, while the explicit first-level map is the stable reader-facing representation.
This preserves complete discoverability for agents without exposing the recursive navigation tree in the visual homepage, and avoids making the cards and expanded toctrees compete as two primary navigation systems.
Fix the DPA-3.2 fine-tuning quick start, replace expanded homepage toctrees with a compact documentation map, and complete the canonical citation guide for shipped model families. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
|
Addressed the remaining citation-completeness review in 40cda1a after verifying it against the current tree:
Validation included Pybtex parsing, citation-key/cross-reference consistency checks, mdformat, Ruff, Coding agent: Codex |
Keep from-scratch training as a first-class path and add the compressed DPA4 CPS-throughput figure to the landing pages. Coding-Agent: Codex Codex-Version: codex-cli 0.144.6 Model: gpt-5.6-sol Reasoning-Effort: xhigh
OutisLi
left a comment
OutisLi
left a comment
There was a problem hiding this comment.
The pretrained-first direction is reasonable, but the README must state the actual LoRA support boundary before this can be approved.
| > [!IMPORTANT] | ||
| > **A pretrained model can be your starting point, not just your end result.** | ||
| > Download a built-in DPA checkpoint, fine-tune the full model or a LoRA | ||
| > adapter on system-specific data, then test, export, and deploy it through the |
There was a problem hiding this comment.
The README presents LoRA as a general DPA fine-tuning option, but the current configuration exposes lora only for DPA4/SeZM, and the implementation restricts it to PyTorch single-task training; DPA1/DPA2/DPA3 checkpoints cannot use it. This distinction is important for both users and agents following the prominent pretrained workflow. Please qualify the generic LoRA claims on this page as DPA4/SeZM-only (and PyTorch single-task), and link the LoRA text to the DPA4 LoRA section; the current fine-tuning-guide link does not document LoRA.
There was a problem hiding this comment.
The same support-boundary wording is mirrored on the documentation landing page at doc/index.rst:13-14, :49, :84-85, and :159. Please update those occurrences together with the README so the two landing pages consistently state that LoRA fine-tuning is for DPA4/SeZM (PyTorch, single-task). This does not require removing the pretrained-first LoRA path; it only makes its model/backend scope explicit.
| Jinzhe Zeng and Mingyu Guo and Chengqian Zhang and Bowen Li and Hong Jiang | ||
| and Tong Zhu and Weile Jia and Linfeng Zhang and Han Wang | ||
| }, | ||
| title = {{A Graph Neural Network for the Era of Large Atomistic Models}}, |
There was a problem hiding this comment.
Please keep the canonical BibTeX title identical to the paper metadata. arXiv:2506.01686 is titled “Graph neural network model for the era of large atomistic models”; the current entry adds “A” and omits “model”. The authors, identifier, and year are otherwise correct.
There was a problem hiding this comment.
This comment is a false positive. However, the preprint should be suppressed by the published article here.
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