refactor(model): express analytical bridging as an explicit linear_ener composition (deepmodeling#5964)

Close deepmodeling#5948.

A bridged model IS a linear composition, but it was spelled as a
`bridging_method` flag on a non-composite model type. The type you
requested was not the type you got, and every builder that accepted the
flag re-implemented the composition (and drifted; see deepmodeling#5947).

## Canonical spelling

```json
"model": {
  "type": "linear_ener", "weights": "sum", "type_map": ["Ni", "O"],
  "models": [
    {"type": "dpa4", "descriptor": {"...": "..."}, "fitting_net": {"...": "..."}},
    {"type": "inner_potential", "mode": "zbl", "r_inner": 0.8, "r_outer": 1.2}
  ]
}
```

## Changes, by issue task

1. **`inner_potential` is a config-level model type.** Registered in
argcheck (`mode`, `r_inner`, `r_outer`), so it can be named as a
`linear_ener` child. It is buildable only inside a composition.
2. **The composition derives the descriptor coupling.** The linear
builder writes the learned sibling descriptor's
`inner_clamp_r_inner`/`_outer` from the `inner_potential` child at build
time. The radii are written once; one source of truth.
3. **`pair_exclude_types` belongs to the composition.** The canonical
builders do no promotion; the composition-level key governs both
children by construction. The legacy promotion semantics of the pt
`type: "dpa4"` builder survive only inside the sugar expansion, so the
two bridged routes of deepmodeling#5947 can no longer diverge (the ~80 eV builder
disagreement is gone: both spellings of the flag now expand
identically). Full deletion of the non-bridged promotion stays with
deepmodeling#5947's deprecation cycle.
4. **`bridging_method` is sugar with ONE owner.**
`deepmd.utils.bridging.expand_bridging_method` expands the flag into the
canonical form at every backend's `get_model` entry. The non-composite
builders (`get_standard_model`, `get_sezm_model`) fail fast on the flag
instead of composing — or, as pt's standard route used to do, silently
dropping it.
5. **pt and pt_expt land together.** dpmodel gains a real `linear_ener`
config builder (it previously had none); its child-parsing core is
shared with pt_expt. pt realizes the canonical form through its existing
`SeZMModel` implementation, so pt checkpoints and physics are unchanged.

Native-scheme spin combines with the canonical form: a top-level `spin`
section on a `linear_ener` config wraps the composition as
`NativeSpinEnergyModel` (dpmodel/pt_expt) or routes to the SeZM spin
builder (pt).

## Both spellings are supported, by design

The concise `type: "dpa4"` + `bridging_method` form is the **recommended
user interface** (it is shorter, and existing inputs/checkpoints keep
working with no migration). The explicit `linear_ener` +
`inner_potential` form is the **canonical internal semantics**: all
builders construct only it, so the concise form is pure rewriting and
cannot drift. `examples/water/dpa4/input-zbl.json` keeps the concise
form; `doc/model/dpa4.md` documents the concise form first and shows the
explicit equivalent.

## Tests

- `source/tests/common/test_bridging.py` (new): 16 normalizer unit tests
— key routing, promotion, mismatch error, spin passthrough, rejections,
inactive-flag passthrough.
- `source/tests/common/dpmodel/test_zbl_bridging.py`: canonical-vs-sugar
tests — identical energy (exact equality) and identical serialized wire
dict, plus shape rejections and the standard-builder fail-fast.
- `source/tests/pt/model/test_get_model_bridging.py` (new): canonical →
`SeZMModel` with identical serialization to the sugar form; rejections
(`weights != "sum"`, non-DPA4 sibling, two inner children); plain
`linear_ener` unaffected.
- `source/tests/pt_expt/model/test_get_model_bridging.py`: updated to
the new contract (flag on `type: standard` now composes through
`get_model`); canonical composition, canonical native-spin, serialize
parity, builder fail-fasts.
- Suites run locally and green: dpmodel common (1127 passed), pt_expt
`test_zbl_bridging` / `test_get_model_bridging` / `test_get_model_dpa4`
/ `test_linear_model`, pt sezm model + spin + linear suites, consistency
`test_linear_ener`, `test_examples`.

## Known limitations

- **pt is a mapping, not a composition.** The pt backend implements
bridging inside `SeZMModel`, so its linear builder maps the canonical
config back onto `SeZMModel` constructor arguments. Physics and
checkpoint format are byte-identical to the flag form (pinned by a
serialize-equality test), but pt's internal ownership still differs from
dpmodel/pt_expt.
- **pt is stricter on split exclusion scopes.** A canonical config whose
learned child sets `descriptor.exclude_types` different from the
composition's `pair_exclude_types` raises in pt (SeZM mismatch check)
while dpmodel/pt_expt accept the two scopes independently (deepmodeling#5947
territory).
- The non-bridged `descriptor.exclude_types` promotion in
`get_sezm_model` (pt, pt_expt) is untouched; removing it is deepmodeling#5947's
staged deprecation.
- No end-to-end `dp train` run or GPU `.pt2` export with a canonical
config in this PR; construction, argcheck, serialization, and energy
parity are unit-tested. Two locally failing AOTI freeze tests are the
known pre-existing torch 2.11 CPU-SIMD inductor bug (they pass with
`cpp.simdlen = 1`; master fails identically).
- Multi-task `shared_dict` combined with an `inner_potential` child is
rejected, not supported.


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

* **New Features**
* Added linear-energy compositions combining learned, descriptor-based,
pair-tabulated, and analytical inner-potential models.
* Added native-spin support and configurable clamping radii for these
compositions.
* Added automatic ZBL bridging expansion with validation, shared
exclusions, and equivalent shorthand/canonical configurations.
* Added support for bridged models in inference, checkpoint freezing,
serialization, and model updates.

* **Documentation**
* Updated DPA4 ZBL bridging guidance, recommended configurations, and
compatibility details.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Han Wang <wang_han@iapcm.ac.cn>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

deepmd/dpmodel/model/dp_linear_model.py

@@ -22,6 +22,9 @@
 from deepmd.dpmodel.model.make_model import (
     make_model,
 )
+from deepmd.utils.data_system import (
+    DeepmdDataSystem,
+)
 
 DPLinearModel_ = make_model(LinearEnergyAtomicModel, T_Bases=(NativeOP, BaseModel))
 
@@ -45,3 +48,48 @@ def __init__(
     ) -> None:
         DPModelCommon.__init__(self)
         DPLinearModel_.__init__(self, *args, **kwargs)
+
+    @classmethod
+    def update_sel(
+        cls,
+        train_data: DeepmdDataSystem,
+        type_map: list[str] | None,
+        local_jdata: dict,
+    ) -> tuple[dict, float | None]:
+        """Update the selection and perform neighbor statistics.
+
+        Updates each learned child in place, skipping analytical
+        (``inner_potential``) and pair-table children, and aggregates the
+        minimum neighbor distance (twin of the pt_expt implementation).
+
+        Parameters
+        ----------
+        train_data : DeepmdDataSystem
+            data used to do neighbor statistics
+        type_map : list[str], optional
+            The name of each type of atoms
+        local_jdata : dict
+            The local data refer to the current class
+
+        Returns
+        -------
+        dict
+            The updated local data
+        float
+            The minimum distance between two atoms
+        """
+        local_jdata_cpy = local_jdata.copy()
+        type_map = local_jdata_cpy["type_map"]
+        min_nbor_dist = None
+        for idx, sub_model in enumerate(local_jdata_cpy["models"]):
+            if sub_model.get("type") == "inner_potential":
+                # analytical child: no descriptor, no selection to update
+                continue
+            if "tab_file" not in sub_model:
+                sub_model, temp_min = DPModelCommon.update_sel(
+                    train_data, type_map, local_jdata_cpy["models"][idx]
+                )
+                local_jdata_cpy["models"][idx] = sub_model
+                if min_nbor_dist is None or temp_min <= min_nbor_dist:
+                    min_nbor_dist = temp_min
+        return local_jdata_cpy, min_nbor_dist

deepmd/dpmodel/model/model.py

@@ -31,6 +31,9 @@
 from deepmd.dpmodel.model.spin_model import (
     SpinModel,
 )
+from deepmd.utils.bridging import (
+    expand_bridging_method,
+)
 from deepmd.utils.spin import (
     Spin,
     normalize_spin_use_spin,
@@ -58,50 +61,67 @@ def get_standard_model(data: dict) -> BaseModel:
     data : dict
         The data to construct the model.
     """
-    data = copy.deepcopy(data)
-    # Analytical bridging (e.g. ZBL): the radii feed the DESCRIPTOR's
-    # InnerClamp/BridgingSwitch (mirrors pt's builder); the method builds the
-    # atomic model's InnerPotential below.
     bridging_method = str(data.get("bridging_method", "none"))
-    bridging_enabled = bridging_method.lower() not in ("none", "")
-    if bridging_enabled:
-        data["descriptor"]["inner_clamp_r_inner"] = data.get("bridging_r_inner", 0.5)
-        data["descriptor"]["inner_clamp_r_outer"] = data.get("bridging_r_outer", 0.8)
-    model = _model_factory.get_standard_model(data)
-    if not bridging_enabled:
-        return model
-
-    descriptor = model.atomic_model.descriptor
-    atom_exclude_types = data.get("atom_exclude_types", [])
-    pair_exclude_types = data.get("pair_exclude_types", [])
-    # Composition, not a flag (first-principles design): the analytical
-    # bridging term is its own atomic model, summed with the learned one by the
-    # existing linear composition machinery.
-    from deepmd.dpmodel.atomic_model.inner_potential import (
-        InnerPotentialAtomicModel,
-    )
-    from deepmd.dpmodel.atomic_model.linear_atomic_model import (
-        LinearEnergyAtomicModel,
-    )
+    if bridging_method.lower() not in ("none", ""):
+        raise ValueError(
+            "`bridging_method` is not supported for a standard model: "
+            "analytical bridging builds a linear composition, not a "
+            "standard model. Route the config through `get_model` (which "
+            "expands the flag), or spell the composition explicitly with "
+            '`type: "linear_ener"` and an `inner_potential` sub-model.'
+        )
+    return _model_factory.get_standard_model(data)
+
+
+def get_linear_model(data: dict) -> BaseModel:
+    """Build a linear energy model from a ``linear_ener`` config.
+
+    Children with a ``descriptor`` build as standard learned atomic
+    models; ``pairtab`` children build as pair-tabulation atomic models;
+    an ``inner_potential`` child builds the analytical bridging term. The
+    composition is the ONE owner of the bridging coupling: it derives the
+    learned sibling descriptor's ``inner_clamp_r_inner``/``_outer`` from
+    the ``inner_potential`` child's ``r_inner``/``r_outer``, so the radii
+    are written once in the config (issue #5948, task 2).
+
+    A top-level ``spin`` section (scheme ``native``) wraps the composed
+    atomic model as a :class:`NativeSpinEnergyModel`, with ``use_spin``
+    injected into every learned child's descriptor.
+
+    Parameters
+    ----------
+    data : dict
+        The model configuration.
+    """
     from deepmd.dpmodel.model.dp_linear_model import (
         LinearEnergyModel,
     )
 
-    zbl_atomic = InnerPotentialAtomicModel(
-        type_map=data["type_map"],
-        mode=bridging_method,
-        rcut=descriptor.get_rcut(),
-        sel=descriptor.get_sel(),
-    )
-    composed = LinearEnergyAtomicModel(
-        models=[model.atomic_model, zbl_atomic],
-        type_map=data["type_map"],
-        weights="sum",
-        # Both exclusions belong to the composition: its children share one
-        # graph, so "excluded" must cover the analytical term too.
-        atom_exclude_types=atom_exclude_types,
-        pair_exclude_types=pair_exclude_types,
-    )
+    data = copy.deepcopy(data)
+    spin = None
+    if "spin" in data:
+        spin_cfg = data.pop("spin")
+        if str(spin_cfg.get("scheme", "deepspin")) != "native":
+            raise NotImplementedError(
+                "Spin linear_ener models support only spin scheme 'native'."
+            )
+        use_spin = normalize_spin_use_spin(spin_cfg["use_spin"], data["type_map"])
+        spin = Spin(
+            use_spin=use_spin,
+            virtual_scale=spin_cfg.get("virtual_scale", 1.0),
+            allow_missing_label=spin_cfg.get("allow_missing_label", False),
+        )
+        for sub in data["models"]:
+            if "descriptor" in sub:
+                sub["descriptor"]["use_spin"] = use_spin
+    composed = _model_factory.get_linear_atomic_model(data)
+    if spin is not None:
+        if not composed.supports_native_spin():
+            raise NotImplementedError(
+                "spin scheme 'native' requires an atomic model declaring "
+                "supports_native_spin()"
+            )
+        return NativeSpinEnergyModel(atomic_model_=composed, spin=spin)
     return LinearEnergyModel(atomic_model_=composed)
 
 
@@ -135,14 +155,10 @@ def get_native_spin_model(data: dict) -> NativeSpinEnergyModel:
     eligible; the gate is that capability method, not a descriptor-type
     list.
 
-    The non-spin backbone is built by :func:`get_standard_model`, which OWNS
-    everything about assembling the atomic model -- descriptor/fitting,
-    exclusions and the analytical-bridging composition -- so ``spin`` and
-    ``bridging_method`` combine for free: the wrapper re-classes whatever
-    atomic model came back, be it a single learned model or a
-    ``LinearEnergyAtomicModel`` over ``[learned, InnerPotential]`` (the
-    analytical child accepts and ignores ``spin``; the learned child consumes
-    it).
+    The non-spin backbone is built by :func:`get_standard_model`. A spin
+    model with analytical bridging is a ``linear_ener`` composition and
+    routes through :func:`get_linear_model` instead (the ``bridging_method``
+    sugar expands to that form in :func:`get_model`).
 
     Parameters
     ----------
@@ -195,9 +211,13 @@ def get_model(data: dict) -> BaseModel:
     data : dict
         The data to construct the model.
     """
+    data = expand_bridging_method(data)
     return _model_factory.get_model(
         data,
         standard_model_factory=get_standard_model,
         spin_model_factory=get_spin_model,
         native_spin_model_factory=get_native_spin_model,
+        model_factories={
+            "linear_ener": get_linear_model,
+        },
     )