xnn.common.finetune.reference#

Per-element reference energies (E0s) for fine-tuning.

A potential predicts energies relative to per-element reference energies (atom_ref in most xnn models). A fine-tuning set computed at another level of theory differs from the pretraining labels mostly by such composition-dependent constants, so the references are re-set before the fit (Tompa et al., arXiv:2606.12704, Sec. 2.6). Two estimators are provided:

  • average_atomic_energies(): the least-squares fit of the reference energies to the compositions (eq. 5), the minimum-norm solution when the compositions are degenerate;

  • estimate_atomic_energies(): the model-aware reestimation (eq. 6), the per-element corrections that best align the pretrained model’s predictions with the fine-tuning energies, which recovers the target references exactly for a model that predicts the interaction energies exactly and is the recommended choice.

get_atomic_energies() / set_atomic_energies() read and write the references of any xnn model, whatever it calls them.

Module Attributes

REFERENCE_MARKERS

Values of atomic_energies in a config that ask for an estimate from the training data: "estimated" (model-aware reestimation, estimate_atomic_energies()) or "average" (average_atomic_energies()).

Functions

average_atomic_energies(structures[, species])

Per-element reference energies fitted to the energies of structures.

composition_matrix(structures, species)

Atom counts per structure and element, float64 (n_structures, n_species).

estimate_atomic_energies(model, structures)

Model-aware reestimation of the per-element reference energies.

get_atomic_energies(model[, species])

The per-element reference energies of a model, {Z: E0}.

predict_energies(model, structures[, ...])

Energies model predicts for structures, float64 (n,).

reference_markers(model_cfg)

Split the reference-energy markers out of a model config.

set_atomic_energies(model, values)

Set the per-element reference energies of a model.

species_of(structures)

The sorted atomic numbers present in structures (dicts or a dataset).
Show Source