feat(dpa1): add compressible l=2 moments across PT backends (deepmodeling#5911)

## Summary

- Add compressible `l=2` moment features across the DPA1 PyTorch
backends.
- Extend the DPA1/SeAtten descriptor, Triton and CUDA graph kernels,
tabulation paths, and graph energy/force handling for the new moment
basis.
- Keep the regular PyTorch and `pt_expt` descriptor paths aligned with
the compressed implementation.
- Correct compressed DPA1/SeAtten evaluation with `exclude_types` by
honoring unsorted neighbor lists throughout tabulation.
- Update argument validation, documentation, serialization versioning,
and backend-specific tests for the new functionality.

## Motivation

The DPA1 compressed path previously lacked the `l=2` moment basis and
corresponding PT-backend coverage. This change supplies the missing
basis and propagates it through descriptor construction, compression,
graph execution, tabulation, and force/energy evaluation so compressed
and regular paths can represent the same angular information.

## Validation

- All pre-commit hooks passed.
- The focused pure-Python DPA1/DPModel tests passed (`12 passed`,
including 6 subtests).
- The selected compressed CPU custom-op tests passed (`29 passed`, 19
skipped).
- The extended component-basis CPU operator tests passed (`2 passed`,
including 6 subtests).
- The handwritten `l=2/3/4` CUDA VJP formulas were checked numerically
against PyTorch autograd with maximum absolute error below `9e-15`; CUDA
compilation/runtime was not available on the macOS review host.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added configurable `lmax` (1–4) for DPA1/SE-attention, expanding the
moment basis size (4/9/16/25) and enabling learnable higher-order
per-degree degree weighting.
* Updated CPU/CUDA/Triton fused descriptor paths to use the expanded
basis (`basis_dim`) and to thread the per-degree gain through
forward/backward computations.
* **Bug Fixes**
* Improved serialization/deserialization to preserve `lmax` and
higher-order degree-gain parameters reliably across reloads.
* **Documentation**
* Documented `lmax`/basis-dimension behavior and clarified higher-order
execution constraints and experimental high-`lmax` routing.
* **Tests**
* Added/extended unit and parity tests for higher `lmax`, serialization,
and coordinate-derivative validation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: OutisLi

deepmd/dpmodel/descriptor/dpa1.py

@@ -122,6 +122,9 @@ class DescrptSeAttenV2(DescrptDPA1):
             A list of strings. Give the name to each type of atoms.
     seed : int, Optional
             Random seed for initializing the network parameters.
+    lmax : int
+            Maximum angular degree of the Cartesian moment basis. Supported
+            values are 1 through 4.
     """
 
     def __init__(
@@ -158,6 +161,7 @@ def __init__(
         type_map: list[str] | None = None,
         # consistent with argcheck, not used though
         seed: int | list[int] | None = None,
+        lmax: int = 1,
     ) -> None:
         DescrptDPA1.__init__(
             self,
@@ -195,6 +199,7 @@ def __init__(
             type_map=type_map,
             # consistent with argcheck, not used though
             seed=seed,
+            lmax=lmax,
         )
         self.compress = False
 
@@ -204,7 +209,7 @@ def serialize(self) -> dict:
         data = {
             "@class": "Descriptor",
             "type": "se_atten_v2",
-            "@version": 3 if self.compress else 2,
+            "@version": 4 if obj.lmax != 1 else (3 if self.compress else 2),
             "rcut": obj.rcut,
             "rcut_smth": obj.rcut_smth,
             "sel": obj.sel,
@@ -246,6 +251,11 @@ def serialize(self) -> dict:
             "trainable": self.trainable,
             "spin": None,
         }
+        if obj.lmax != 1:
+            data["lmax"] = obj.lmax
+            data["@variables"]["degree_gain_raw"] = to_numpy_array(
+                obj.adam_degree_gain_raw
+            )
         if self.compress:
             type_embd_data = (
                 self.type_embd_data
@@ -282,7 +292,7 @@ def serialize(self) -> dict:
     def deserialize(cls, data: dict) -> "DescrptSeAttenV2":
         """Deserialize from dict."""
         data = data.copy()
-        check_version_compatibility(data.pop("@version"), 3, 1)
+        check_version_compatibility(data.pop("@version"), 4, 1)
         data.pop("@class")
         data.pop("type")
         variables = data.pop("@variables")
@@ -295,10 +305,16 @@ def deserialize(cls, data: dict) -> "DescrptSeAttenV2":
         # compat with version 1
         if "use_tebd_bias" not in data:
             data["use_tebd_bias"] = True
+        data.setdefault("lmax", 1)
         obj = cls(**data)
 
         obj.se_atten["davg"] = variables["davg"]
         obj.se_atten["dstd"] = variables["dstd"]
+        if obj.se_atten.lmax > 1:
+            obj.se_atten.adam_degree_gain_raw = np.asarray(
+                variables["degree_gain_raw"],
+                dtype=PRECISION_DICT[obj.se_atten.precision],
+            )
         obj.se_atten.embeddings = NetworkCollection.deserialize(embeddings)
         obj.se_atten.embeddings_strip = NetworkCollection.deserialize(embeddings_strip)
         obj.type_embedding = TypeEmbedNet.deserialize(type_embedding)

deepmd/dpmodel/descriptor/se_atten_v2.py

@@ -70,6 +70,7 @@ def _forward_fake(
     type_embedding: torch.Tensor,
     average: torch.Tensor,
     inverse_stddev: torch.Tensor,
+    degree_gain: torch.Tensor,
     table: torch.Tensor,
     gate_table: torch.Tensor,
     type_one_side: int,
@@ -86,12 +87,14 @@ def _forward_fake(
     rcut_smooth: float,
     protection: float,
     neighbors: float,
+    basis_dim: int,
 ) -> tuple[torch.Tensor, ...]:
     del (
         source,
         destination_row_ptr,
         average,
         inverse_stddev,
+        degree_gain,
         gate_table,
         type_one_side,
         smooth,
@@ -117,7 +120,7 @@ def _forward_fake(
             width,
             3,
         ),
-        edge_vec.new_empty(node_count, 4, width),
+        edge_vec.new_empty(node_count, basis_dim, width),
     )
 
 
@@ -131,6 +134,7 @@ def _backward_fake(
     atype: torch.Tensor,
     average: torch.Tensor,
     inverse_stddev: torch.Tensor,
+    degree_gain: torch.Tensor,
     table: torch.Tensor,
     gate_table: torch.Tensor,
     type_one_side: int,
@@ -155,6 +159,7 @@ def _backward_fake(
         atype,
         average,
         inverse_stddev,
+        degree_gain,
         table,
         gate_table,
         type_one_side,
@@ -218,9 +223,9 @@ def _cpu_forward(*args: Any) -> tuple[torch.Tensor, ...]:
         edge_mask,
         destination_order,
         destination_row_ptr,
-        *tail[:11],
+        *tail[:12],
         True,
-        *tail[11:],
+        *tail[12:],
     )
 
 
@@ -245,9 +250,9 @@ def _cpu_backward(*args: Any) -> torch.Tensor:
         edge_mask,
         destination_order,
         destination_row_ptr,
-        *tail[:8],
+        *tail[:9],
         True,
-        *tail[8:],
+        *tail[9:],
     )
 
 
@@ -329,6 +334,11 @@ def dpa1_canonical_compress_energy_force(
     compress_data = desc.compress_data[0].contiguous()
     gate_table = desc.type_embd_data.contiguous()
     inverse_stddev = torch.reciprocal(se.stddev[:, 0, :]).contiguous()
+    degree_gain = (
+        se.adam_degree_gain_raw.to(torch.float32).contiguous()
+        if se.adam_degree_gain_raw is not None
+        else compress_data.new_empty(0)
+    )
     from torch.fx.experimental.proxy_tensor import (
         disable_proxy_modes_tracing,
     )
@@ -346,6 +356,7 @@ def dpa1_canonical_compress_energy_force(
         type_embedding,
         se.mean[:, 0, :].contiguous(),
         inverse_stddev,
+        degree_gain,
         compress_data,
         gate_table,
         int(se.type_one_side),
@@ -362,6 +373,7 @@ def dpa1_canonical_compress_energy_force(
         float(se.rcut_smth),
         float(se.env_protection),
         float(se.nnei),
+        (int(se.lmax) + 1) ** 2,
     )
 
     *hidden, head = fit.nets[0].layers
@@ -426,6 +438,7 @@ def dpa1_canonical_compress_energy_force(
         atype,
         se.mean[:, 0, :].contiguous(),
         inverse_stddev,
+        degree_gain,
         compress_data,
         gate_table,
         int(se.type_one_side),