deepmodeling / deepmodeling/deepmd-kit

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

Open
#5,922 0 comments 0 reactions 0 assignees View on GitHub
Docs
Dominant language
Python
Stars
2k
Forks
649
Avg merge
6d 18h
Merged PRs (30d)
15

Description

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](https://github.com/Luthaf/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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.