nvalchemi.training.distillation.evaluation.extensivity_error#

nvalchemi.training.distillation.evaluation.extensivity_error(model, data, *, repeats=(2, 1, 1), extensive_keys=DEFAULT_EXTENSIVE_SYSTEM_KEYS, intensive_keys=DEFAULT_INTENSIVE_SYSTEM_KEYS, drop_keys=())[source]#

Check that a model’s energy scales with the number of replicated cells.

A size-extensive potential returns exactly k times the energy for a k-fold supercell. A student that learned a global readout breaks that identity. So does a potential whose numerics are re-derived from the cell it is given, such as an Ewald or PME tail whose splitting parameter follows the atom count and volume. The break shows up in MD long before it shows up in a held-out energy MAE.

Parameters:
  • model (TeacherScorer | BaseModelMixin) – Model to check. A bare model is wrapped in an InProcessTeacherScorer, which builds and rolls back the neighbor list it needs.

  • data (Iterable[Batch] | Batch) – Periodic structures to replicate; they are left unmodified. make_supercell() carries node-level fields into the supercell and scales system-level fields by their extensivity. A system-level field with no defined scaling is rejected.

  • repeats (Sequence[int], optional) – Replication factors along the three lattice vectors. Default (2, 1, 1).

  • extensive_keys (Collection[str], optional) – System-level fields multiplied by the copy count. Default DEFAULT_EXTENSIVE_SYSTEM_KEYS.

  • intensive_keys (Collection[str], optional) – System-level fields carried unchanged. Default DEFAULT_INTENSIVE_SYSTEM_KEYS.

  • drop_keys (Collection[str], optional) – Fields left out of the supercell, on top of the ephemeral neighbor tensors, which are always dropped. A batch returned by run() carries the propagator’s bookkeeping, such as status and system_id, which no scaling rule covers; pass propagator.bookkeeping_keys() to replicate such a batch. Default ().

Returns:

Worst-case and mean energy-scaling error, in eV/atom.

Return type:

ExtensivityMetrics

Raises:

ValueError – If repeats is not three positive integers. If a structure is not periodic (it has no cell, or its pbc marks every axis non-periodic), or carries a system-level field that neither scales with the supercell nor is dropped. If data holds no graphs.

Examples

>>> from nvalchemi.training.distillation.evaluation import extensivity_error
>>> extensivity_error(student, holdout, repeats=(2, 2, 1))
>>> extensivity_error(
...     student, nve.run(batch), drop_keys=nve.bookkeeping_keys()
... )