fix(charge-state): validate conditions from training data and malformed archives

The training pipeline registered `charge_spin` as a two-value data requirement
and never checked the values, so a dataset carrying a fractional condition
reached the unguarded embedding gathers and was truncated onto a neighbouring
table row. Validation now runs in `normalize_batch`, the one place every
backend and both the standard and LMDB data systems read a batch through, and
ahead of tensor conversion so no device synchronization is needed. The rule is
evaluated over the whole batch at once, so the training loop pays no per-frame
cost, and the single-state and batch entry points share one implementation.

On the C++ side the range list from the archive is now required to hold one
range per value: a shorter or longer list would have checked one value against
another value's table. An empty range is rejected for the same reason.

Also registers DPA4C in the family's deepspin rejection list, which is a tuple
membership test that its name did not match, and gives it the escape hatch the
base contract requires of any descriptor overriding `uses_graph_lower`. DPA4C
refuses rather than no-ops there: it carries every neighbour within the cutoff
and reports an unreachable `sel`, so a dense lower sized from that capacity is
unallocatable rather than merely slower.

Two DPA4 fixtures named `[0.5, -0.5]`, which truncates to charge 0 and
multiplicity 0; they now name a state the tables can address.

Author: OutisLi

deepmd/dpmodel/descriptor/dpa4c.py

@@ -2021,6 +2021,28 @@ def uses_graph_lower(self) -> bool:
         """Return whether graph-native lowering is supported."""
         return True
 
+    def disable_graph_lower(self) -> None:
+        """Reject the dense lower, which this descriptor cannot serve.
+
+        The base contract asks a descriptor that overrides
+        :meth:`uses_graph_lower` to provide the matching escape hatch. DPA4C
+        has no dense form to escape to: it carries every neighbour within the
+        cutoff and reports an unreachable :meth:`get_sel`, so a dense lower
+        sized from that capacity is not a slower route but an unallocatable
+        one. Refusing is therefore the honest answer, where a silent no-op
+        would leave the caller believing the route had been taken.
+
+        Raises
+        ------
+        NotImplementedError
+            Always, because the graph lower is the only form DPA4C has.
+        """
+        raise NotImplementedError(
+            "DPA4C is graph-native and has no dense lower to fall back on; "
+            "it carries every neighbor within the cutoff rather than a "
+            "bounded `sel`."
+        )
+
     def graph_edge_dtype(self) -> str:
         """Return the edge-geometry dtype accepted by graph deployment.
 

deepmd/dpmodel/model/model.py

@@ -50,7 +50,14 @@
 )
 get_zbl_model = _model_factory.get_zbl_model
 
-_DPA4_SEZM_DESCRIPTOR_TYPES = ("dpa4", "DPA4", "sezm", "SeZM")
+_DPA4_SEZM_DESCRIPTOR_TYPES = (
+    "dpa4",
+    "DPA4",
+    "dpa4c",
+    "DPA4C",
+    "sezm",
+    "SeZM",
+)
 
 
 def get_standard_model(data: dict) -> BaseModel:

deepmd/dpmodel/utils/batch.py

@@ -7,6 +7,10 @@
 
 import numpy as np
 
+from deepmd.utils.charge_state import (
+    validate_charge_states,
+)
+
 # Keys that are metadata / not needed by models or loss functions.
 _DROP_KEYS = {"default_mesh", "sid", "fid"}
 
@@ -36,6 +40,11 @@ def normalize_batch(batch: dict[str, Any]) -> dict[str, Any]:
     * ``find_*`` flags are converted to ``np.bool_``.
     * Metadata keys (``default_mesh``, ``sid``, ``fid``) are dropped.
 
+    Every backend reads its batches through here, so this is also where a
+    frame condition is checked against the charge and multiplicity tables it
+    indexes. Doing it on the numpy batch keeps the check off the compiled
+    forward, where an out-of-range row would reach an unguarded gather.
+
     Parameters
     ----------
     batch : dict[str, Any]
@@ -65,6 +74,9 @@ def normalize_batch(batch: dict[str, Any]) -> dict[str, Any]:
         else:
             out[key] = val
 
+    if out.get("charge_spin") is not None and bool(out.get("find_charge_spin", True)):
+        validate_charge_states(out["charge_spin"])
+
     return out
 
 

deepmd/pt_expt/infer/charge_state.py

@@ -56,6 +56,8 @@ def charge_states(charge_spin: Any, width: int) -> np.ndarray:
         If the request does not hold at least one whole state, or names a
         state that no embedding table row answers.
     """
+    if width <= 0:
+        raise ValueError(f"a charge state must be at least one value wide, got {width}")
     values = np.asarray(charge_spin, dtype=np.float64).reshape(-1)
     if values.size == 0 or values.size % width:
         raise ValueError(

deepmd/utils/charge_state.py

@@ -11,10 +11,11 @@
 Neither the gather nor the compiled kernel bounds-checks the row index, so a
 value outside a table reads past it and a fractional value is silently
 truncated onto a neighbouring row. Every host-side boundary that accepts a
-condition therefore passes it through :func:`validate_charge_state` first. The
-per-forward path is deliberately not guarded: its values come from the data
-pipeline, which owns their validity exactly as it owns the validity of an atom
-type.
+condition therefore checks it here first: a configured default through
+:func:`validate_charge_state`, and a batch of frames read from the training
+data through :func:`validate_charge_states`. Both share one rule, evaluated
+over the whole batch at once so the training loop pays no per-frame cost, and
+both run before tensor conversion so no device synchronization is needed.
 """
 
 from __future__ import (
@@ -53,6 +54,50 @@
 CHARGE_STATE_WIDTH = len(CHARGE_STATE_FIELDS)
 
 
+def _as_states(charge_spin: Any) -> np.ndarray:
+    """Read a request as ``(n, CHARGE_STATE_WIDTH)`` states."""
+    values = np.asarray(charge_spin, dtype=np.float64).reshape(-1)
+    if values.size == 0 or values.size % CHARGE_STATE_WIDTH:
+        raise ValueError(
+            f"A charge state must be a `[charge, multiplicity]` pair, got "
+            f"{values.size} values"
+        )
+    return values.reshape(-1, CHARGE_STATE_WIDTH)
+
+
+def _check_states(states: np.ndarray) -> None:
+    """Reject any state that addresses no row of the embedding tables.
+
+    The whole batch is tested column by column with array operations, so the
+    cost does not grow with the number of frames. A non-finite value is
+    reported as the integrality failure rather than reaching the range test,
+    whose message would have to render it.
+
+    Parameters
+    ----------
+    states : np.ndarray
+        Charge states with shape (n, CHARGE_STATE_WIDTH).
+
+    Raises
+    ------
+    ValueError
+        If any value is not an integer inside its table's row range.
+    """
+    integral = np.isfinite(states) & (states == np.floor(states))
+    for column, (name, (low, high)) in enumerate(
+        zip(CHARGE_STATE_FIELDS, CHARGE_STATE_TABLE_RANGES, strict=True)
+    ):
+        values = states[:, column]
+        offending = values[~integral[:, column]]
+        if offending.size:
+            raise ValueError(f"The {name} must be an integer, got {offending[0]}")
+        outside = values[(values < low) | (values >= high)]
+        if outside.size:
+            raise ValueError(
+                f"The {name} must lie in [{low}, {high}), got {outside[0]:.0f}"
+            )
+
+
 def validate_charge_state(charge_spin: Any) -> list[float]:
     """Check that a frame condition addresses a row of each embedding table.
 
@@ -72,22 +117,28 @@ def validate_charge_state(charge_spin: Any) -> list[float]:
         If the pair does not hold exactly two integral values within the
         representable ranges.
     """
-    values = [float(value) for value in np.reshape(np.asarray(charge_spin), (-1,))]
-    if len(values) != CHARGE_STATE_WIDTH:
+    states = _as_states(charge_spin)
+    if states.shape[0] != 1:
         raise ValueError(
             f"A charge state must be a `[charge, multiplicity]` pair, got "
-            f"{len(values)} values"
+            f"{states.size} values"
         )
-    for value, name, (low, high) in zip(
-        values,
-        CHARGE_STATE_FIELDS,
-        CHARGE_STATE_TABLE_RANGES,
-        strict=True,
-    ):
-        if not np.isfinite(value) or value != int(value):
-            raise ValueError(f"The {name} must be an integer, got {value}")
-        if not low <= value < high:
-            raise ValueError(
-                f"The {name} must lie in [{low}, {high}), got {int(value)}"
-            )
-    return values
+    _check_states(states)
+    return states[0].tolist()
+
+
+def validate_charge_states(charge_spin: Any) -> None:
+    """Check every frame condition of a batch against the embedding tables.
+
+    Parameters
+    ----------
+    charge_spin
+        One ``[charge, multiplicity]`` pair per frame, in any shape holding a
+        whole number of pairs.
+
+    Raises
+    ------
+    ValueError
+        If any frame names a state that no table row answers.
+    """
+    _check_states(_as_states(charge_spin))

source/api_cc/src/DeepPotPTExpt.cc

@@ -224,7 +224,7 @@ void DeepPotPTExpt::init(const std::string& model,
     }
   }
   default_chg_spin_ = read_default_chg_spin(metadata, dchgspin);
-  chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata);
+  chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata, dchgspin);
   check_charge_spin_domain(default_chg_spin_, chg_spin_table_ranges_);
 
   if (metadata.obj_val.count("do_atomic_virial")) {
@@ -397,7 +397,8 @@ void DeepPotPTExpt::init(const std::string& model,
     // The constants were frozen against the archive's own charge state, so
     // that is the state in force until ``set_charge_spin`` installs another.
     default_chg_spin_ = read_default_chg_spin(metadata, settable_chgspin);
-    chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata);
+    chg_spin_table_ranges_ =
+        read_chg_spin_table_ranges(metadata, settable_chgspin);
     check_charge_spin_domain(default_chg_spin_, chg_spin_table_ranges_);
   }
 

source/api_cc/src/DeepSpinPTExpt.cc

@@ -148,7 +148,7 @@ void DeepSpinPTExpt::init(const std::string& model,
     }
   }
   default_chg_spin_ = read_default_chg_spin(metadata, dchgspin);
-  chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata);
+  chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata, dchgspin);
   check_charge_spin_domain(default_chg_spin_, chg_spin_table_ranges_);
 
   if (metadata.obj_val.count("do_atomic_virial")) {

source/api_cc/src/NativeSpinPTExpt.cc

@@ -268,7 +268,7 @@ void NativeSpinPTExpt::init(const std::string& model,
   // compressed model, whose lower has no conditioning input at all.
   settable_chgspin = dchgspin;
   default_chg_spin_ = read_default_chg_spin(metadata, dchgspin);
-  chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata);
+  chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata, dchgspin);
   check_charge_spin_domain(default_chg_spin_, chg_spin_table_ranges_);
   has_default_fparam_ = metadata.obj_val.count("has_default_fparam") &&
                         metadata["has_default_fparam"].as_bool();
@@ -395,7 +395,8 @@ void NativeSpinPTExpt::init(const std::string& model,
     // The constants were frozen against the archive's own charge state, so
     // that is the state in force until ``set_charge_spin`` installs another.
     default_chg_spin_ = read_default_chg_spin(metadata, settable_chgspin);
-    chg_spin_table_ranges_ = read_chg_spin_table_ranges(metadata);
+    chg_spin_table_ranges_ =
+        read_chg_spin_table_ranges(metadata, settable_chgspin);
     check_charge_spin_domain(default_chg_spin_, chg_spin_table_ranges_);
   }
 

source/api_cc/src/commonPTExpt.h

@@ -293,12 +293,17 @@ inline std::vector<double> read_default_chg_spin(const JsonValue& metadata,
  * table. An archive frozen before the ranges were recorded names none, and
  * the boundary then checks only the width, as it did before.
  *
+ * The ranges are indexed by column, so one per value of a charge state is the
+ * only count that lines the domain check up with the values it guards. A
+ * shorter or longer list would check a value against another value's table.
+ *
  * @param[in] metadata Parsed archive metadata.
+ * @param[in] dim_chg_spin Width of a charge state the model accepts.
  * @return One ``{low, high}`` pair per value, empty when the archive names
  *   no ranges.
  **/
 inline std::vector<std::pair<double, double>> read_chg_spin_table_ranges(
-    const JsonValue& metadata) {
+    const JsonValue& metadata, const int dim_chg_spin) {
   std::vector<std::pair<double, double>> ranges;
   if (!metadata.obj_val.count("chg_spin_table_ranges") ||
       metadata["chg_spin_table_ranges"].type == JsonValue::Null) {
@@ -310,8 +315,19 @@ inline std::vector<std::pair<double, double>> read_chg_spin_table_ranges(
       throw deepmd::deepmd_exception(
           "chg_spin_table_ranges must hold a [low, high) pair per value.");
     }
+    if (pair[0].as_double() >= pair[1].as_double()) {
+      throw deepmd::deepmd_exception(
+          "chg_spin_table_ranges names an empty [low, high) range, which no "
+          "charge state can address.");
+    }
     ranges.emplace_back(pair[0].as_double(), pair[1].as_double());
   }
+  if (static_cast<int>(ranges.size()) != dim_chg_spin) {
+    throw deepmd::deepmd_exception(
+        "chg_spin_table_ranges holds " + std::to_string(ranges.size()) +
+        " ranges but the model accepts charge states of width " +
+        std::to_string(dim_chg_spin) + ".");
+  }
   return ranges;
 }
 

source/tests/common/dpmodel/test_descriptor_dpa4c.py

@@ -1798,3 +1798,50 @@ def test_the_calibration_samples_the_corpus_charge_states() -> None:
         [{key: value for key, value in corpus[0].items() if key != "charge_spin"}]
     )
     assert not np.allclose(descriptor.stddev, default_state.stddev)
+
+
+def test_dense_lower_escape_hatch_is_refused() -> None:
+    """DPA4C overrides ``uses_graph_lower`` and owes the paired hatch.
+
+    The base contract requires the postcondition ``uses_graph_lower() is
+    False`` after the hatch. DPA4C has no dense form to reach: it carries
+    every neighbour within the cutoff and reports an unreachable ``get_sel``,
+    so it refuses instead of inheriting a no-op that reports success while
+    leaving the graph lower in place.
+    """
+    descriptor = DescrptDPA4C(
+        rcut=4.0, ntypes=2, channels=8, lmax=2, n_radial=4, seed=1
+    )
+    assert descriptor.uses_graph_lower()
+    with pytest.raises(NotImplementedError, match="no dense lower"):
+        descriptor.disable_graph_lower()
+    assert descriptor.uses_graph_lower()
+
+
+def test_virtual_atom_spin_scheme_is_refused() -> None:
+    """DPA4C is a DPA4-family descriptor, so deepspin must be rejected.
+
+    ``SpinModel`` pulls the dense escape hatch its descriptors do not have,
+    and the family's constraint lives in the model factory, so a new member
+    has to be registered there rather than rely on a downstream failure.
+    """
+    from deepmd.dpmodel.model.model import (
+        get_spin_model,
+    )
+
+    with pytest.raises(NotImplementedError, match="deepspin"):
+        get_spin_model(
+            {
+                "type_map": ["Ni", "O"],
+                "spin": {"use_spin": [True, False]},
+                "descriptor": {
+                    "type": "dpa4c",
+                    "rcut": 4.0,
+                    "channels": 8,
+                    "lmax": 2,
+                    "n_radial": 4,
+                    "seed": 1,
+                },
+                "fitting_net": {"neuron": [8, 8], "seed": 1},
+            }
+        )