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 * segmentsteacher force evaluations. Default4.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:
- 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