nvalchemi.training.distillation.evaluation.AccuracyMetrics#

class nvalchemi.training.distillation.evaluation.AccuracyMetrics(*, name, num_graphs, num_atoms, energy_mae=None, energy_rmse=None, energy_per_atom_mae=None, energy_per_atom_rmse=None, forces_mae=None, forces_rmse=None, stress_mae=None, stress_rmse=None, force_cosine_mean=None, force_cosine_aggregate=None, atomic_energies_mae=None, atomic_energies_rmse=None, force_nonfinite_atoms=0, errors=<factory>)[source]#

Errors of one student against one set of targets over a held-out set.

Every metric is an exact global reduction over the evaluated set: the sum of residuals divided by the total count, not a mean of per-batch means. Metrics are in the units the batch carries: eV for energies, eV/A for forces, and the dataset’s stress units. A quantity the pass could not measure is None. That happens when the quantity was not requested, or when no batch carried its prediction or target. A quantity that was measured but came out non-finite is nan. An acceptance bar fails a nan value instead of reporting it as missing.

Parameters:
  • name (str)

  • num_graphs (int)

  • num_atoms (int)

  • energy_mae (float | None)

  • energy_rmse (float | None)

  • energy_per_atom_mae (float | None)

  • energy_per_atom_rmse (float | None)

  • forces_mae (float | None)

  • forces_rmse (float | None)

  • stress_mae (float | None)

  • stress_rmse (float | None)

  • force_cosine_mean (float | None)

  • force_cosine_aggregate (float | None)

  • atomic_energies_mae (float | None)

  • atomic_energies_rmse (float | None)

  • force_nonfinite_atoms (int)

  • errors (dict[str, dict[str, float]])

name#

Label carried into reports.

Type:

str

num_graphs, num_atoms

Graphs and atoms evaluated.

Type:

int

energy_mae, energy_rmse

Total-energy error per graph.

Type:

float | None

energy_per_atom_mae, energy_per_atom_rmse

Total-energy error divided by each graph’s atom count.

Type:

float | None

forces_mae, forces_rmse

Force error per Cartesian component over every atom.

Type:

float | None

stress_mae, stress_rmse

Stress error per component over all nine components.

Type:

float | None

force_cosine_mean#

Mean over atoms of the cosine between the predicted and target force, weighting every atom equally. An atom whose force is at or below the student’s own error has an essentially random angle, so this number describes the held-out set’s low-force tail as much as the student. Atoms whose force vanishes on either side are not counted. None when no atom carries a force on both sides.

Type:

float | None

force_cosine_aggregate#

Cosine between the two force fields, each taken as a single vector over the whole set, so atoms are weighted by force magnitude. This is the alignment an acceptance bar reads. A single non-finite atom makes it nan, whereas force_cosine_mean still reports the atoms that stayed finite.

Type:

float | None

atomic_energies_mae, atomic_energies_rmse

Per-atom energy error, measured when both the prediction and the target include a per-atom energy decomposition.

Type:

float | None

force_nonfinite_atoms#

Atoms dropped from force_cosine_mean for a non-finite force.

Type:

int

errors#

{"mae": ..., "rmse": ...} per custom AccuracyQuantitySpec that was measured; the built-in quantities report through their own fields.

Type:

Mapping[str, Mapping[str, float]]

model_config = {'extra': 'forbid', 'frozen': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_dict()[source]#

Return the populated fields as a plain dictionary.

A quantity that was not measured is left out rather than exported as None, and from_dict() restores it as None. An empty errors map is left out the same way.

Return type:

dict[str, Any]