Skip to content

feat(pt_expt): auto-select O(N) NeighborGraph builder by default#5903

Open
Shaurya2k06 wants to merge 1 commit into
deepmodeling:masterfrom
Shaurya2k06:feat/pt_expt-auto-neighbor-graph-builder
Open

feat(pt_expt): auto-select O(N) NeighborGraph builder by default#5903
Shaurya2k06 wants to merge 1 commit into
deepmodeling:masterfrom
Shaurya2k06:feat/pt_expt-auto-neighbor-graph-builder

Conversation

@Shaurya2k06

@Shaurya2k06 Shaurya2k06 commented Jul 24, 2026

Copy link
Copy Markdown

Closes #5902

Summary

  • Add a shared resolve_auto_graph_builder(device) policy for the carry-all NeighborGraph builders: CUDA prefers nv then vesin then dense; CPU prefers vesin then dense (ase stays explicit-only).
  • Flip the pt_expt model-level default (None / "auto") from hard-coded "dense" to that ladder, and use the same helper in DeepEval (default "auto") and compiled training's eager _forward_graph.
  • Keep builders outside traced/compiled regions: export and training compile still use synthetic dense graph inputs, so .pt2 artifacts are unchanged.

Why existing tests missed this

Builder dispatch already had vesin/nv vs dense energy/force parity, but nothing asserted that the model/DeepEval default would pick an O(N) builder when available, and compiled training still hardcoded dense while claiming to match the eager default-flip. The new resolver unit tests pin the availability ladder; the extended dispatch and DeepEval tests pin value-transparency of None/"auto" against the resolved concrete builder.

Validation

  • ruff check / ruff format --check on touched files
  • pytest focused suite: 20 passed, 1 skipped (nv CUDA-only)
    • source/tests/pt_expt/utils/test_neighbor_graph_method.py
    • source/tests/pt_expt/model/test_graph_builder_dispatch.py
    • DeepEval auto/vesin graph .pt2 parity
    • nlist-artifact reject of explicit non-default neighbor_graph_method

Summary by CodeRabbit

  • New Features

    • Added automatic neighbor-graph selection for inference and model execution.
    • Automatically chooses the best available backend based on device and runtime support, with safe fallbacks.
    • Added support for explicitly selecting the automatic graph-building mode.
  • Bug Fixes

    • Ensured automatic, dense, and available accelerated graph builders produce consistent results.
    • Improved validation and error messages for neighbor-graph method selection.
  • Tests

    • Added coverage for backend selection, fallback behavior, and numerical parity across graph-building methods.

Replace the hard-coded None→dense default with a shared availability-
probing ladder (CUDA: nv→vesin→dense; CPU: vesin→dense) used by the
model default-flip, DeepEval, and compiled training's eager builder.

Signed-off-by: shaurya2k06 <shaurya2k06@gmail.com>
Copilot AI review requested due to automatic review settings July 24, 2026 12:09
@dosubot dosubot Bot added the new feature label Jul 24, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@coderabbitai

coderabbitai Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

neighbor_graph_method now defaults to "auto" and resolves to nv, vesin, or dense based on device and availability. DeepEval, model construction, and graph training use the shared dispatch policy, with tests covering backend parity and resolver behavior.

Changes

NeighborGraph auto selection

Layer / File(s) Summary
Automatic builder resolution
deepmd/pt_expt/utils/neighbor_graph_method.py, deepmd/pt_expt/utils/*_graph_builder.py
Adds device-aware selection among nv, vesin, and dense, with updated backend documentation.
Inference and model dispatch
deepmd/pt_expt/infer/deep_eval.py, deepmd/pt_expt/model/make_model.py, deepmd/pt_expt/train/training.py
Changes the default to "auto", updates validation and dispatch, and uses automatic graph construction in the GRAPH training path.
Resolver and builder parity validation
source/tests/pt_expt/utils/test_neighbor_graph_method.py, source/tests/pt_expt/model/test_graph_builder_dispatch.py, source/tests/pt_expt/infer/test_graph_deepeval.py
Tests availability-based resolution, parity across available builders, and default/explicit auto inference results against dense output.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DeepEval
  participant CM
  participant resolve_auto_graph_builder
  participant NeighborGraphBuilder
  DeepEval->>resolve_auto_graph_builder: resolve "auto" for device
  CM->>resolve_auto_graph_builder: resolve None or "auto" for device
  resolve_auto_graph_builder-->>DeepEval: nv, vesin, or dense
  resolve_auto_graph_builder-->>CM: nv, vesin, or dense
  DeepEval->>NeighborGraphBuilder: build graph with resolved method
  CM->>NeighborGraphBuilder: build graph with resolved method
Loading

Possibly related PRs

Suggested labels: enhancement

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: auto-selecting the default NeighborGraph builder in pt_expt.
Linked Issues check ✅ Passed The PR implements the shared auto-selection ladder, applies it to model defaults and DeepEval, and adds parity/trace-safety tests.
Out of Scope Changes check ✅ Passed The changes stay focused on NeighborGraph auto-selection, dispatch, docs, and tests, with no unrelated scope added.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with 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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🧹 Nitpick comments (1)
source/tests/pt_expt/model/test_graph_builder_dispatch.py (1)

146-158: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert dispatch, not only parity.

All backends are intentionally value-equivalent, so this passes if None/"auto" incorrectly falls back to dense. Mock or spy on the resolver/concrete builder and assert that the resolved backend is invoked.

🤖 Prompt for 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.

In `@source/tests/pt_expt/model/test_graph_builder_dispatch.py` around lines 146 -
158, Update test_none_and_auto_match_resolved_builder to spy on or mock the
resolver/concrete graph builder, then assert that the backend resolved for None
and "auto" is actually invoked. Retain the existing output-parity assertions,
but ensure the test fails if either input silently falls back to dense.
🤖 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 `@deepmd/pt_expt/utils/vesin_graph_builder.py`:
- Around line 11-15: Update the documentation describing the shared
resolve_auto_graph_builder default ladder to state that vesin is selected for
CPU or CUDA fallback only when vesin.torch is importable; otherwise document
that dense is selected.

---

Nitpick comments:
In `@source/tests/pt_expt/model/test_graph_builder_dispatch.py`:
- Around line 146-158: Update test_none_and_auto_match_resolved_builder to spy
on or mock the resolver/concrete graph builder, then assert that the backend
resolved for None and "auto" is actually invoked. Retain the existing
output-parity assertions, but ensure the test fails if either input silently
falls back to dense.
🪄 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: d02887c0-8595-4f4e-a31f-c9bc7c3749a5

📥 Commits

Reviewing files that changed from the base of the PR and between 8f2a3f1 and c612f05.

📒 Files selected for processing (9)
  • deepmd/pt_expt/infer/deep_eval.py
  • deepmd/pt_expt/model/make_model.py
  • deepmd/pt_expt/train/training.py
  • deepmd/pt_expt/utils/neighbor_graph_method.py
  • deepmd/pt_expt/utils/nv_graph_builder.py
  • deepmd/pt_expt/utils/vesin_graph_builder.py
  • source/tests/pt_expt/infer/test_graph_deepeval.py
  • source/tests/pt_expt/model/test_graph_builder_dispatch.py
  • source/tests/pt_expt/utils/test_neighbor_graph_method.py

Comment on lines +11 to +15
for ``nf == 1`` inference and CPU use. On CPU (and on CUDA when ``nv`` is
unavailable) it is selected by the shared
:func:`~deepmd.pt_expt.utils.neighbor_graph_method.resolve_auto_graph_builder`
default ladder; otherwise prefer ``nv`` (:mod:`.nv_graph_builder`) for batched
multi-frame GPU work, which batches all frames in one kernel. Export and

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

State the vesin availability condition.

The ladder selects vesin on CPU or CUDA fallback only when vesin.torch is importable; otherwise it selects dense. Add that condition so the documented policy matches resolve_auto_graph_builder.

🤖 Prompt for 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.

In `@deepmd/pt_expt/utils/vesin_graph_builder.py` around lines 11 - 15, Update the
documentation describing the shared resolve_auto_graph_builder default ladder to
state that vesin is selected for CPU or CUDA fallback only when vesin.torch is
importable; otherwise document that dense is selected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Auto-select the optimal NeighborGraph builder (nv/vesin/dense) by device and availability

2 participants