set-by-statistic double-counts the model-level analytical contribution for bridged models

[wanghan-iapcm]

Summary

For a model that adds an analytical contribution at the model layer (SeZM + InnerPotential/ZBL bridging), bias_adjust_mode="set-by-statistic" fits the atomic output bias to the raw labels. Because the analytical term is then added on top of the atomic output at inference, the mean analytical contribution is counted twice.

change-by-statistic was recently corrected for this in #5910, which routes it through a complete model-level predictor. set-by-statistic was left as-is, so the two modes now disagree about what the bias represents for bridged models.

Mechanism

compute_output_stats chooses what gets fitted based on whether a predictor is supplied:

https://github.com/deepmodeling/deepmd-kit/blob/799252d40da5e4d9a9f48ef1444cd4936964a4ab/deepmd/pt/utils/stat.py#L678-L687

With model_forward=None the fit target is merged_output, i.e. the raw labels. set-by-statistic is exactly the branch that passes no predictor:

deepmd-kit/deepmd/pt/model/atomic_model/base_atomic_model.py

Lines 630 to 645 in 799252d

	)
	self._store_out_stat(delta_bias, out_std, add=True)
	elif bias_adjust_mode == "set-by-statistic":
	bias_out, std_out = compute_output_stats(
	sample_merged,
	self.get_ntypes(),
	keys=self.bias_keys,
	stat_file_path=stat_file_path,
	rcond=self.rcond,
	preset_bias=self.preset_out_bias,
	stats_distinguish_types=self.get_compute_stats_distinguish_types(),
	intensive=self.get_intensive(),
	)
	self._store_out_stat(bias_out, std_out)
	else:
	raise RuntimeError("Unknown bias_adjust_mode mode: " + bias_adjust_mode)

For a bridged model the label is the true total energy, analytical term included. So the per-type bias absorbs the mean analytical contribution, and the model then adds that contribution again during the forward pass.

Why the #5910 fix does not cover it

#5910 added a model-level change_out_bias override that short-circuits change-by-statistic through predict_atomic_outputs_for_stat, and delegates every other mode to the atomic model unchanged. Separately, the initial statistics path never reaches the model layer at all: compute_or_load_out_stat is an atomic-model method calling the atomic change_out_bias directly, so a model-level override cannot intercept it.

deepmd-kit/deepmd/pt/model/atomic_model/base_atomic_model.py

Lines 565 to 569 in 799252d

	self.change_out_bias(
	merged,
	stat_file_path=stat_file_path,
	bias_adjust_mode="set-by-statistic",
	)

Where this is reachable

Three call sites use set-by-statistic:

1. compute_or_load_out_stat — the initial output-statistics computation, run at the start of every training run (link above).
2. dp change-bias --mode set —

   deepmd-kit/deepmd/pt/entrypoints/main.py

   Lines 608 to 612 in 799252d

   	)
   	multi_task = "model_dict" in model_params
   	bias_adjust_mode = "change-by-statistic" if mode == "change" else "set-by-statistic"
   	if multi_task:
   	assert model_branch is not None, (

3. The finetune path in deepmd/pt/train/training.py around L955.

Case 1 is self-correcting in the sense that training can learn to compensate a poor initial bias, so the practical cost there is a worse starting point rather than a permanent error. Cases 2 and 3 apply the shift to an already-trained model, where nothing corrects it.

What I have not verified

• The magnitude of the effect. It is the mean analytical contribution over the calibration set, which for a short-range repulsive term at equilibrium geometries may be small. Somebody should measure it before deciding how urgent this is.
• Whether DPZBLModel (the separate DPZBLLinearEnergyAtomicModel blending implementation used by dpmodel/pt_expt) is affected. It composes differently — the blend happens inside the atomic model, and it is a smooth switch rather than a plain sum — so the analysis above does not carry over directly.
• Whether the current behaviour is in fact intended for some workflow I have not considered.

This is not a regression from #5910; the same behaviour is present before it. It surfaced while reviewing that PR, because fixing one mode made the asymmetry between the two visible.

Possible direction

Neither existing mode expresses the right thing. Passing the model-level predictor to set-by-statistic would just turn it into change-by-statistic. What the bridged case needs is to subtract only the analytical contribution from the labels and then fit absolutely — a third behaviour. A narrower alternative is to reject set-by-statistic for models carrying a model-level analytical term, so the wrong number is never silently produced.

Whichever direction is taken, a regression test in the shape of test_change_out_bias_is_invariant_for_self_labels from #5910 would pin it: label the data with the model's own output, apply the mode, and assert the resulting predictions still reproduce the labels.

[wanghan-iapcm]

Resolved as designed by #5966 (docs + semantic pin tests, no behavior change). The analysis that closes it:

The model energy decomposes as E = E_model + E_bias. The two modes are defined as:

• set-by-statistic: E_bias := the per-type statistic of the raw labels (or user values). Independent of E_model by definition — verified in the code (compute_output_stats with model_forward=None, absolute store). It ignores a trained network and it equally ignores the analytical ZBL term.
• change-by-statistic: E_bias += statistic of (labels − complete model prediction), the bridged predictor since fix(pt): calibrate DPA4 bias and support PyTorch 2.13 compile #5910.

Under these definitions the "double count" this issue describes is not a bridging-specific bug: set uniformly ignores all of E_model, for every model kind. A bridged model after set is offset by the data mean of the ZBL term in exactly the same sense that a trained plain model after set is offset by its network output mean. The asymmetry between the two modes is their definition, not drift.

Supporting facts verified numerically:

• The ZBL pair term contributes exactly zero for isolated atoms — its own legitimate per-type bias is 0, training-independent.
• Both linear composition paths conform: children compute no output statistics; the composition level performs one set fit on raw labels (pt and dpmodel agree bit-for-bit with the raw least-squares reference).

The "third behaviour" contemplated in the issue (subtract only the analytical term, then fit absolutely) was prototyped and deliberately rejected: it would make set depend on part of E_model, silently creating a mode that is neither set nor change. The pin tests added in #5966 assert set == raw-label fit on bridged models in pt and dpmodel, so this cannot be "fixed" back in unnoticed.

Practical guidance now in doc/model/change-bias.md: for a self-consistent calibration of a bridged (or any nonzero-E_model) model, use change-by-statistic; set is the reproducible, model-blind reset.