docs(inference): document vesin neighbor list and nlist_backend for Python/ASE inference

Open
  • Is something wrong?
#5,922 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
75/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python, pytorch
Domain
documentation

Research direction

Start with doc/inference/python.md:61-79, then read deepmd/pt_expt/infer/deep_eval.py:185-310 and deepmd/pt_expt/utils/vesin_neighbor_list.py; inspect deepmd/calculator.py for ASE passthrough details. Update the neighbor-list section with verified nlist_backend behavior, vesin requirements, and graph-model scope, then confirm the documentation with the specified grep commands.

Written by the indexing model from the issue text.

Description

Docs

Parent issue: #5917 (checklist item 7)

Scope

23622361d (feat(pt_expt): pluggable NeighborList strategy + O(N) vesin neighbor list for Python/ASE inference) added:

  • deepmd/pt_expt/utils/vesin_neighbor_list.py — an O(N) neighbor list built on the vesin package;
  • a nlist_backend argument ("auto" / "vesin" / "native") on the pt-expt DeepEval (deepmd/pt_expt/infer/deep_eval.py:214, selection logic at :271-300), surfaced through deepmd.infer.DeepPot for .pt2/.pte models and the ASE calculator (verify passthrough in deepmd/calculator.py).

doc/inference/python.md:61-79 ("External neighbor list algorithm") is TensorFlow-only and mentions neither pt-expt nor vesin; vesin appears nowhere in doc/.

Implementation plan

doc/inference/python.md

Rework the final section; read deepmd/pt_expt/infer/deep_eval.py:185-310 and deepmd/pt_expt/utils/vesin_neighbor_list.py before writing.

  • Rename/extend the section to cover both mechanisms, keeping the existing TF content (heading e.g. "Neighbor list algorithm"; update the supported-backends note to TensorFlow {{ tensorflow_icon }} and PyTorch-Exportable {{ pytorch_icon }}).
  • Keep the existing TF neighbor_list= ASE example as its own subsection.
  • Add a pt-expt subsection documenting:
    • The default neighbor list is the native O(N²) pairwise search for non-graph-form models; nlist_backend selects the strategy: "auto" (use vesin when the package is installed — verify exact auto behavior), "vesin", or "native".
    • Example: dp = DeepPot("model.pt2", nlist_backend="vesin") (verify the public signature on deepmd.infer.DeepPot / how kwargs reach the pt-expt DeepEval).
    • vesin provides an O(N) cell-list neighbor search; requires the optional vesin package; document the failure mode when vesin is requested but not installed (verify the raised error).
    • If the ASE calculator exposes the knob (check deepmd/calculator.py), document it too; otherwise state ASE usage follows the same nlist_backend argument.
    • Note the knob is ignored for graph-form (NeighborGraph, --lower-kind graph) models, where the graph builder owns neighbor construction (see deep_eval.py:199 docstring note).

Constraints

  • Verify the exact parameter name/defaults/values and error behavior from the code; do not guess.
  • Note: this section is about Python/ASE inference only; LAMMPS neighbor lists are out of scope.

Verification

  • grep -n -i "vesin" doc/inference/python.md shows the new subsection.
  • grep -n "nlist_backend" doc/inference/python.md documents the three values.

Parent issue: #5917

Coding agent: opencode
opencode version: 1.18.9
Model: ustc/k3
Reasoning effort: max

Dominant language
Python
Stars
2.1k
Forks
663
Avg merge
3d 11h
Merged PRs (30d)
25

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from deepmodeling/deepmd-kit

All issues in deepmodeling/deepmd-kit

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.