nvalchemi.training.distillation.evaluation.AcceptanceThresholds#

pydantic model nvalchemi.training.distillation.evaluation.AcceptanceThresholds[source]#

Acceptance bars a student has to clear to be accepted.

Every bar defaults to None, which means “do not test this”, except no_divergence, a flag that defaults to False with the same meaning. A bar that is set but has no matching measurement fails the student; it is never skipped silently. A bar outside the built-in table is set through extra, keyed by the name of its AcceptanceBar. build_acceptance_report() refuses an extra key that its table of bars does not carry.

Examples

>>> from nvalchemi.training.distillation.evaluation import AcceptanceThresholds
>>> thresholds = AcceptanceThresholds(
...     max_energy_per_atom_mae=0.005,
...     max_forces_mae=0.05,
...     max_energy_drift_per_atom_per_ns=0.01,
...     max_from_scratch_ratio=1.0,
... )
>>> thresholds.max_from_scratch_ratio
1.0
field max_energy_per_atom_mae: float | None = None#

Largest accepted energy MAE per atom.

Constraints:
  • gt = 0

field max_forces_mae: float | None = None#

Largest accepted force MAE per Cartesian component.

Constraints:
  • gt = 0

field max_stress_mae: float | None = None#

Largest accepted stress MAE.

Constraints:
  • gt = 0

field min_force_cosine: float | None = None#

Smallest accepted magnitude-weighted cosine similarity between the student’s and the target force fields. It is read off force_cosine_aggregate rather than the per-atom mean, which the holdout’s near-zero forces dominate.

Constraints:
  • ge = -1.0

  • le = 1.0

field max_energy_drift_per_atom_per_ns: float | None = None#

Largest accepted fitted energy drift rate, in eV/atom/ns.

Constraints:
  • gt = 0

field max_energy_drift_per_atom_per_step: float | None = None#

Largest accepted energy drift per atom per step.

Constraints:
  • gt = 0

field max_momentum_drift: float | None = None#

Largest accepted deviation of a graph’s total momentum. Only meaningful under a momentum-conserving integrator: a stochastic thermostat exchanges momentum with its bath by design.

Constraints:
  • gt = 0

field no_divergence: bool = False#

Fail a student whose stability series stopped on a divergence, that is, whose StabilityMetrics carry a first_divergence_step. The drift bars alone cannot catch one: the series ends at the step the monitor’s predicate fired, so they describe the segment before it, which can look perfectly conserved.

field max_extensivity_error_per_atom: float | None = None#

Largest accepted supercell energy-scaling error per atom.

Constraints:
  • gt = 0

field max_rdf_jensen_shannon: float | None = None#

Largest accepted Jensen-Shannon divergence between the student’s and the reference trajectory’s pair-distance histograms. Blind to which species a pair joins unless the compared distributions were themselves resolved to one pair of species.

Constraints:
  • gt = 0

  • le = 1.0

field max_from_scratch_ratio: float | None = None#

Largest accepted ratio of the distilled student’s error to the equal-size from-scratch student’s error on the same holdout. The ratio is taken on energy_per_atom_mae, forces_mae, and stress_mae, whichever both carry, and the worst one is kept. A limit of 1.0 demands a match and a limit below 1.0 demands a margin.

Constraints:
  • gt = 0

field extra: dict[str, float] [Optional]#

Limits of custom acceptance bars, keyed by the AcceptanceBar name they are applied under in the table the report is built with.