docs(dpa4): final-review fix batch — stale docstrings, dead param, error-site wording

Six cosmetic/doc/dead-code fixes, zero behavior change:

- test_dpa4_call_graph.py: reword build_sparse_edges_from_nlist docstring
  to describe the graph-route edge contract instead of the deleted
  DescrptDPA4.call_with_edges API.
- edge_cache.py: drop the dead atype_flat parameter from
  _edge_cache_from_arrays (unused in the body); update both call sites
  (dpa4.py::_call_graph_impl, test_dpa4_dpmodel_parity.py).
- dpa4.py: correct _call_graph_impl's Returns docstring to the actual
  (n_out_nodes, 1, 1, channels) shape (callers flatten the SO(3)
  singleton axes), matching _call_graph_common's docstring.
- test_lammps_dpa4_pt2.py: reword the stale 'with-comm dispatch exercised
  at single-rank level' paragraph — DPA4 has no with-comm artifact at all.
- doc/model/dpa4.md: correct three occurrences of 'raises an error at
  pair-style setup' to 'raises an error at the first force evaluation'
  (the C++ raise fires in the compute dispatch, not at setup time).
- main.py: update --lower-kind help text from the stale 'currently dpa1
  with attn_layer=0' to a generic graph-eligible-models description.

Author: Han Wang

deepmd/dpmodel/descriptor/dpa4.py

@@ -1391,8 +1391,10 @@ def _call_graph_impl(
         Returns
         -------
         tuple[Array, Array]
-            Flat ``(n_out_nodes, channels)`` read-out in global precision and
-            the full multipole feature tensor ``x``.
+            Read-out with the SO(3) singleton axes still attached, shape
+            ``(n_out_nodes, 1, 1, channels)``, in global precision, and the
+            full multipole feature tensor ``x``. Callers (``_call_graph_common``
+            and its callers in turn) flatten the singleton axes.
         """
         xp = array_api_compat.array_namespace(edge_vec)
         device = array_api_compat.device(edge_vec)
@@ -1421,7 +1423,6 @@ def _call_graph_impl(
         # === Step 3. Build edge cache once (sparse edges) ===
         edge_cache = _edge_cache_from_arrays(
             type_ebed=type_ebed,
-            atype_flat=atype_flat,
             edge_index=edge_index,
             edge_vec=edge_vec,
             edge_mask=edge_mask,

deepmd/dpmodel/descriptor/dpa4_nn/edge_cache.py

@@ -230,7 +230,6 @@ def compute_edge_src_gate(
 def _edge_cache_from_arrays(
     *,
     type_ebed: Any,
-    atype_flat: Any,
     edge_index: Any,
     edge_vec: Any,
     edge_mask: Any,
@@ -258,8 +257,6 @@ def _edge_cache_from_arrays(
     ----------
     type_ebed
         Per-node type embedding with shape (N, C), where N=nf*nloc.
-    atype_flat
-        Flattened local atom types with shape (N,).
     edge_index
         Edge indices with shape (2, E).
     edge_vec

deepmd/main.py

@@ -363,8 +363,9 @@ def main_parser() -> argparse.ArgumentParser:
         choices=["nlist", "graph"],
         help="(Supported backend: PyTorch Exportable) Lower-level export form of the "
         "frozen .pt2: 'nlist' (default, dense neighbor-list lower) or 'graph' "
-        "(NeighborGraph edge-list lower; only for graph-eligible models, currently "
-        "dpa1 with attn_layer=0). 'graph' selects the C++ graph inference path.",
+        "(NeighborGraph edge-list lower; only for graph-eligible models, i.e. "
+        "descriptors implementing the NeighborGraph lower, e.g. DPA1/DPA2/DPA4). "
+        "'graph' selects the C++ graph inference path.",
     )
 
     # * test script ********************************************************************

doc/model/dpa4.md

@@ -437,8 +437,8 @@ pair_coeff * * O H
 features at every interaction block, but no export path (dense or
 graph-native) implements the cross-rank ghost-feature exchange yet, so no
 `.pt2` archive carries a with-comm artifact. A multi-rank LAMMPS run raises an
-error at pair-style setup instead of silently running without the cross-rank
-exchange. Use a single MPI rank (one process, optionally with one GPU) for
+error at the first force evaluation instead of silently running without the
+cross-rank exchange. Use a single MPI rank (one process, optionally with one GPU) for
 DPA4/SeZM until cross-rank support ships. The remainder of this subsection
 describes the intended multi-rank workflow for when that support lands.
 :::
@@ -504,8 +504,8 @@ error at freeze time instead of exporting a silently-dense-only artifact.
 Like the dense route (see [Multi-GPU (MPI)
 inference](#multi-gpu-mpi-inference) above), the graph route does not
 implement cross-rank ghost exchange, so a graph-frozen `.pt2` is single-rank
-only; multi-rank LAMMPS runs raise an error at pair-style setup for both
-lower kinds.
+only; multi-rank LAMMPS runs raise an error at the first force evaluation for
+both lower kinds.
 
 ## Embedding extraction
 
@@ -623,7 +623,7 @@ closed over the one-hop neighbor shell.
 - Export uses `.pt2` (AOTInductor); the TorchScript freeze path is not used.
 - Model compression is not supported.
 - Multi-rank (multi-GPU/MPI) LAMMPS inference is not currently supported and
-  fails fast at pair-style setup; run on a single MPI rank. See
+  fails fast at the first force evaluation; run on a single MPI rank. See
   [Multi-GPU (MPI) inference](#multi-gpu-mpi-inference).
 - The pt_expt graph-native inference route (`--lower-kind graph`) is
   single-rank only and unavailable for spin, charge/spin conditioning, or ZBL

source/lmp/tests/test_lammps_dpa4_pt2.py

@@ -27,10 +27,11 @@
 - virial / type_map / real-units / si-units variants mirror the dpa3
   single-rank set.
 
-Deferred (NOT covered): live multi-rank parity. DPA4 multi-rank
-inference is out of PR-3 scope and has no mpi runner script. The C++
-with-comm dispatch is exercised for DPA4 only at the single-rank level
-here; multi-rank DPA4 is left to a follow-up.
+Deferred (NOT covered): live multi-rank parity. DPA4's ``.pt2`` archive
+carries no with-comm artifact, so multi-rank LAMMPS inference fails fast
+at the first force evaluation instead of running (see the module-level
+note); there is no with-comm dispatch to exercise here, and no mpi runner
+script. Multi-rank DPA4 support is left to a follow-up.
 
 Tolerances match test_lammps_dpa3_pt2.py exactly (pytest.approx defaults
 for pe/forces; per-atom virial compared with pytest.approx).

source/tests/common/dpmodel/test_dpa4_call_graph.py

@@ -52,10 +52,11 @@ def build_sparse_edges_from_nlist(coord, nlist):
     """Extract the valid physical edges of a padded neighbor list.
 
     The padded layout keeps one slot per neighbor (``-1`` marks padding). The
-    sparse contract for :meth:`DescrptDPA4.call_with_edges` is one explicit edge
-    per kept slot, indexing the flattened frame-major node axis
-    (``node = f * nloc + i``). The edge vector points from the center toward the
-    neighbor, matching the padded path's ``r_j - r_i``.
+    graph-route edge contract -- edges packed into a :class:`NeighborGraph`
+    and consumed by ``call_graph`` -- is one explicit edge per kept slot,
+    indexing the flattened frame-major node axis (``node = f * nloc + i``).
+    The edge vector points from the center toward the neighbor, matching the
+    padded path's ``r_j - r_i``.
 
     Parameters
     ----------

source/tests/pt/model/test_dpa4_dpmodel_parity.py

@@ -2890,7 +2890,6 @@ def _dp_cache_from_padded(
     edge_mask = np.asarray(graph.edge_mask) & pair_keep_mask.reshape(-1)
     cache = _edge_cache_from_arrays(
         type_ebed=type_ebed,
-        atype_flat=np.zeros(nf * nloc, dtype=np.int64),
         edge_index=graph.edge_index,
         edge_vec=graph.edge_vec,
         edge_mask=edge_mask,