docs(dpa2): document pt_expt eager/training default-flip + legacy escape hatch

Review (iProzd behavior-change note, njzjz-bot P2): pt_expt now defaults
graph-eligible DPA2 to the carry-all graph route in eager inference AND
compiled training, not just --lower-kind graph freezing, changing existing
pt_expt configs' numerics (negligible at non-binding sel; other backends
unaffected). Document the change (release-note-worthy) and the supported
legacy-dense escape hatches:
- inference/eval: neighbor_graph_method="legacy";
- training: descriptor.disable_graph_lower() (flips uses_graph_lower() False,
  honored by both eager forward and the compiled lower -- same mechanism the
  spin model uses). A first-class training-config knob is a follow-up.

Adds test_disable_graph_lower_escape_hatch pinning that the hatch makes the
default (None) eager forward take the dense route bit-identically to explicit
'legacy' at a binding sel (where graph and dense genuinely differ).

Author: Han Wang

doc/model/dpa2.md

@@ -102,6 +102,15 @@ dp --pt_expt freeze -o model.pt2 --lower-kind graph
 
 As with DPA-1's graph path (see [Difference among different backends](train-se-atten.md#difference-among-different-backends)), the graph route considers all neighbors within the cutoff rather than a fixed, padded selection, so its numeric result can differ slightly (down to the AOTInductor floating-point noise floor at non-binding `sel`, larger if `sel` is binding) from the dense/`nlist` path.
 
+:::{note}
+**Default route change in pt_expt (eager & training).** For a graph-eligible DPA-2 descriptor, the pt_expt backend now defaults to the carry-all graph route not only for `--lower-kind graph` freezing but also in **eager inference/evaluation and in (compiled) training** (`neighbor_graph_method=None` resolves to the graph). This changes the numerical behavior of existing pt_expt configurations relative to the dense neighbor-list route (by the amounts described above — negligible at non-binding `sel`). The other backends (dpmodel/PyTorch/Paddle/TensorFlow/JAX) are unaffected: they keep the dense route as their only path.
+
+To retain the legacy dense route on pt_expt:
+
+- **Inference / evaluation:** pass `neighbor_graph_method="legacy"` to `forward_common` / `call_common` (forces the dense neighbor-list path).
+- **Training:** call `model.atomic_model.descriptor.disable_graph_lower()` on the constructed model before training. This flips `uses_graph_lower()` to `False`, which both the eager forward and the compiled-training lower honor, so both run the dense route consistently (the same mechanism the spin model uses to stay on the dense path). A first-class training-config knob for this is planned as a follow-up.
+:::
+
 :::{note}
 **Smoothness at the cutoff.** The graph route is exactly smooth at the cutoff, like the dense path. The non-attention channels (environment matrix, switch envelope, convolution, drrd/grrg, g1g1, symmetrization) are smooth by construction. The repformer *attention* channels (`update_g1_has_attn`, `update_g2_has_attn`) additionally use a fixed-phantom-count softmax: the dense smooth-attention denominator keeps exactly `sel − n_real` padding terms at $e^{-\mathrm{attnw\_shift}}$ (a geometry-independent count); the graph kernels reproduce this by excluding masked pairs from the softmax and adding $\max(\mathrm{sel} - n_\mathrm{real}, 0)$ phantom denominator terms per center. An edge entering the cutoff sphere does so at logit $-\mathrm{attnw\_shift}$ exactly while the phantom count drops by one, so the swap is value-preserving and the energy/force are continuous (verified at the float64 noise floor, $\lesssim 10^{-13}$). This also makes the carry-all graph attention agree with the dense attention term-for-term at non-binding `sel`. The only residual $e^{-20}$-scale discontinuity remains for a center with `sel` or more *real* neighbors within the block cutoff — a regime where the dense path itself suffers a far larger discontinuity from truncating a real neighbor, i.e. where `sel` is misconfigured.
 :::

source/tests/pt_expt/model/test_dpa2_graph_lower.py

@@ -224,6 +224,59 @@ def test_force_virial_parity_vs_legacy(self) -> None:
             graph["energy_derv_c_redu"], legacy["energy_derv_c_redu"], **tol
         )
 
+    def test_disable_graph_lower_escape_hatch(self) -> None:
+        """``descriptor.disable_graph_lower()`` is the documented legacy-dense
+        escape hatch: it flips ``uses_graph_lower()`` to ``False`` so the
+        default (``neighbor_graph_method=None``) eager forward takes the DENSE
+        route -- bit-identical to explicitly requesting ``"legacy"``.
+
+        Uses a BINDING repformer sel so graph and dense genuinely differ: with
+        the hatch engaged, the default must match dense (not graph), which a
+        binding sel makes an unambiguous (non-bit-tight) distinction.
+        """
+        generator = torch.Generator(device=self.device).manual_seed(GLOBAL_SEED)
+        nloc = 12
+        box_size = 3.0
+        coord = (
+            torch.rand(
+                [nloc, 3], dtype=torch.float64, device=self.device, generator=generator
+            )
+            * box_size
+        ).unsqueeze(0)
+        atype = torch.tensor(
+            [[ii % self.nt for ii in range(nloc)]],
+            dtype=torch.int64,
+            device=self.device,
+        )
+        box = (
+            torch.eye(3, dtype=torch.float64, device=self.device) * box_size
+        ).reshape(1, 9)
+
+        model = self._make_model(repformer_nsel=3, repformer_attn=True)
+        model.eval()
+        assert model.atomic_model.descriptor.uses_graph_lower() is True
+
+        # engage the escape hatch
+        model.atomic_model.descriptor.disable_graph_lower()
+        assert model.atomic_model.descriptor.uses_graph_lower() is False
+
+        default_after = model.forward_common(
+            coord.clone().requires_grad_(True), atype, box
+        )
+        legacy = model.forward_common(
+            coord.clone().requires_grad_(True),
+            atype,
+            box,
+            neighbor_graph_method="legacy",
+        )
+        # with the hatch on, default (None) == legacy (dense), bit-identical
+        torch.testing.assert_close(
+            default_after["energy_redu"], legacy["energy_redu"], rtol=0, atol=0
+        )
+        torch.testing.assert_close(
+            default_after["energy_derv_r"], legacy["energy_derv_r"], rtol=0, atol=0
+        )
+
     def test_binding_sel_diverges(self) -> None:
         """At binding repformer sel, the carry-all graph (sel-independent)
         keeps neighbors the dense body truncates, so the two routes diverge.