xnn.common.benchmark.energy

Per-element reference energies (E0s) for atomization-energy scoring.

The total energy of a structure is dominated by per-atom self-energies that carry no information about how the atoms interact. Subtracting a per-element reference energy E0[Z] for every atom turns it into the atomization (a.k.a. interaction) energy – the physically meaningful quantity to report:

E_atomization = E_total - sum_i E0[Z_i]

This module turns a configured atomic_energies value into a lookup tensor indexed by atomic number, reusing the same value parser every model uses (coerce_per_species()) so the accepted spellings match the rest of xnn: a {Z: E0} / {symbol: E0} dict, a list aligned with species, a single number, or the string form of any of these. The special value "average" (or "mean") instead fits the E0s from the benchmark dataset by least squares – the same convention MACE uses when no E0s are given.

Note that MAE / MSE / RMSE between prediction and reference are unchanged by this subtraction (the same per-structure offset cancels out of pred - ref); its effect is to make the reported energies physically meaningful and to give relative or otherwise reference-dependent custom metrics a sensible baseline.

Functions

build_e0_lookup(atomic_energies[, species, ...])	Build a Z-indexed E0 lookup tensor from a configured value.
dataset_structures(dataset)	Return the raw structure dicts backing a dataset or subset.
fit_atomic_energies(structures)	Least-squares fit per-element reference energies from total energies.