test(pt_expt): document compiled neighbor type equivalence

[njzjz-bot]

Closes #5670 as a false positive.

Summary

• make the compiled-training merged-candidate contract explicit at the call site
• add an adversarial A/A/B neighbor-list regression that compares the lower-layer type split with an early type split
• preserve runtime behavior and the established global sum(sel)-candidate semantics

Why the reported divergence does not occur

• compiled dense training builds the global nearest sum(sel) candidates and forward_common_lower then calls model.format_nlist
• for non-mixed descriptors, format_nlist applies nlist_distinguish_types using the per-type sel layout
• build_neighbor_list with distinguish_types=True also globally truncates to sum(sel) before applying that same split, so changing the flag only changes the intermediate layout
• the new type-skewed regression proves False plus the lower split equals True, including the disputed farther type-1 case

This matches the maintainer conclusion on the same report in PR #5491:
#5491 (comment)

If the desired behavior is instead to retain a per-type-safe candidate superset before truncation, that is a separate cross-backend neighbor-list contract change affecting eager, inference, export, and compiled paths.

Why existing tests did not make this obvious

• compiled-versus-eager prediction and gradient consistency tests already cover final outputs, but their fixtures are not type-skewed
• there was no focused low-level test documenting that early and lower-layer type layouts are equivalent after the shared global truncation
• the scan therefore interpreted an intentional intermediate-layout flag as a final-neighbor semantic difference

Validation

• pytest source/tests/common/dpmodel/test_nlist.py -q: 11 passed
• ruff format .
• ruff check .
• git diff --check

The local pt_expt training module could not be collected because the installed libdeepmd_op_pt.so has a stale PyTorch ABI; this PR changes no executable behavior, and the backend-independent contract regression passes.

Coding agent: Codex
Codex version: codex-cli 0.144.4
Model: gpt-5.6-sol
Reasoning effort: xhigh

Summary by CodeRabbit

• Documentation

  • Added inline guidance clarifying neighbor-list handling and layout compatibility in compiled model execution.

• Tests

  • Added coverage verifying consistent neighbor-type layouts across alternate neighbor-list construction paths.
  • Added checks for neighbor indices, per-type formatting, and expected padding behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: a84696b5-c50f-4d64-a5fb-120beba0a7fa

📥 Commits

Reviewing files that changed from the base of the PR and between 6c3b985 and 7f5b037.

📒 Files selected for processing (2)

• deepmd/pt_expt/train/training.py
• source/tests/common/dpmodel/test_nlist.py

---

📝 Walkthrough

Walkthrough

The change documents the dense compiled-training neighbor-list contract and adds a regression test comparing deferred type splitting with direct type-specific neighbor-list construction.

Changes

Neighbor-list layout

Layer / File(s)	Summary
Layout contract and regression coverage deepmd/pt_expt/train/training.py, source/tests/common/dpmodel/test_nlist.py	Comments explain the type-agnostic candidate layout consumed by the lower model. Tests verify equivalent per-type layouts, neighbor indices, and padding for deferred and direct type splitting.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: enhancement, Python

Suggested reviewers: wanghan-iapcm

🚥 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 is concise and matches the main change: documenting compiled neighbor-type equivalence and adding a regression test.
Linked Issues check	✅ Passed	Issue #5670 is addressed by the added regression and call-site note proving the compiled path and early type split are equivalent.
Out of Scope Changes check	✅ Passed	The changes stay on-topic with comments and a regression test for compiled neighbor-list type handling.
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

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.32%. Comparing base (6c3b985) to head (7f5b037).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5860      +/-   ##
==========================================
- Coverage   78.58%   78.32%   -0.26%     
==========================================
  Files        1050     1050              
  Lines      120637   120638       +1     
  Branches     4356     4355       -1     
==========================================
- Hits        94801    94490     -311     
- Misses      24278    24586     +308     
- Partials     1558     1562       +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[njzjz]

Possible reviewers based on changed lines, exact file history, and exact-file review history:

• @wanghan-iapcm — 13 commits on changed files; 37 reviews on exact changed files (deepmd/pt_expt/train/training.py, source/tests/common/dpmodel/test_nlist.py).
• @iProzd — 11 reviews on exact changed files (deepmd/pt_expt/train/training.py).

No review request was made automatically.

Coding agent: Codex
Codex version: codex-cli 0.144.4
Model: gpt-5.6-sol
Reasoning effort: xhigh