nvalchemi.training.distillation.evaluation.non_conservative_residual#

nvalchemi.training.distillation.evaluation.non_conservative_residual(teacher, data, *, num_loops=4, amplitude=0.05, segments=4, generator=None)[source]#

Estimate the part of a teacher’s force field no conservative student can fit.

For each graph, two orthogonal directions \(u\) and \(v\), each with unit root-mean-square per-atom norm, span a square loop of side amplitude \(\varepsilon\) through configuration space. The teacher’s work \(W = \oint F \cdot \mathrm{d}R\) around the loop is integrated with the midpoint rule at segments samples per side. A conservative field integrates to zero, so \(W\) measures the non-conservative component alone. The loop’s path length is \(4 \varepsilon \sqrt{N}\), so by Cauchy-Schwarz \(|W| / (4 \varepsilon N)\) is a lower bound on the largest root-mean-square per-atom force error a conservative student makes on that loop. This bound is reported as force_floor.

The floor is a bound at the probed displacement scale, not a dataset-wide error bar. It shrinks linearly with amplitude, so choose an amplitude on the order of a thermal vibration. One randomly oriented loop sees a \(1 / \sqrt{3N}\) fraction of the field’s curl, so floors are comparable only between probes of similar system size. A conservative teacher reports the midpoint rule’s quadrature error and, below that, the round-off of the batch’s own dtype. A floor below the float32 round-off plateau needs a float64 batch and teacher. See Evaluation and acceptance for the magnitudes.

Parameters:
  • teacher (TeacherScorer | BaseModelMixin) – Teacher whose field is probed. A bare model is wrapped in an InProcessTeacherScorer, which builds and rolls back the teacher’s neighbor list at each probe point.

  • data (Iterable[Batch] | Batch) – Held-out structures to probe. Positions are displaced in place and restored before returning.

  • num_loops (int, optional) – Loops integrated per graph. Default 4.

  • amplitude (float, optional) – Loop side length in A, as a per-atom displacement. Default 0.05.

  • segments (int, optional) – Midpoint-rule samples per side; one loop costs 4 * segments teacher force evaluations. Default 4.

  • generator (torch.Generator | None, optional) – Generator drawing the loop directions. Default None (the global RNG).

Returns:

Loop work, the force floor it implies, and its size relative to the teacher’s own force scale.

Return type:

NonConservativeResidual

Raises:

ValueError – If amplitude, num_loops, or segments is not positive, if the scorer does not publish the teacher force field, or if data holds no graphs.

Examples

>>> from nvalchemi.training.distillation.evaluation import (
...     non_conservative_residual,
... )
>>> residual = non_conservative_residual(teacher, holdout)
>>> residual.relative_floor
0.02