nvalchemi.training.distillation.AtomicEnergyMatchingLoss#

class nvalchemi.training.distillation.AtomicEnergyMatchingLoss(*, target_key='teacher_atomic_energies', prediction_key='predicted_atomic_energies', normalize_by_atom_count=True, ignore_nonfinite=True, dtype_policy='strict')[source]#

Mean-squared-error loss on per-atom energies.

Distillation targets that a total energy cannot express — how a teacher distributes energy across the atoms of a structure — enter training through this term. Prediction and target are node-level tensors of shape (V,): the student’s per-atom energy head against the teacher’s atomic_energies signal, which InProcessTeacherScorer writes to teacher_atomic_energies. The per-atom residual is

\[\rho_{ia} = \left(\hat{\varepsilon}_{ia} - \varepsilon_{ia}\right)^2,\]

where \(\hat{\varepsilon}_{ia}\) is the student’s energy for atom \(a\) of graph \(i\) and \(\varepsilon_{ia}\) the teacher’s. Only valid atoms enter either sum or either denominator: writing \(\mathcal{V}_i\) for the atoms of graph \(i\) that mask accepts, \(M_i = |\mathcal{V}_i|\), and \(M = \sum_i M_i\), the residuals are reduced according to normalize_by_atom_count:

  • normalize_by_atom_count=True (default): the mean per-atom residual of each graph is averaged over graphs, so every structure contributes equally regardless of size,

    \[L = \frac{1}{B} \sum_{i=1}^{B} \frac{1}{\max(M_i, 1)} \sum_{a \in \mathcal{V}_i} \rho_{ia}.\]
  • normalize_by_atom_count=False: one global mean over all valid atoms, \(L = \tfrac{1}{\max(M, 1)} \sum_{i=1}^{B} \sum_{a \in \mathcal{V}_i} \rho_{ia}\), so a large structure dominates a small one.

With the default ignore_nonfinite=True those counts drop every atom whose target energy is not finite, so a graph with one masked atom is divided by its finite-atom count rather than by its size, and a graph with none contributes 0.0.

The graph-balanced reduction needs batch_idx and num_graphs metadata, which compute_supervised_loss() threads from the batch automatically.

Parameters:
  • target_key (str, default "teacher_atomic_energies") – Target container key for the teacher’s per-atom energies.

  • prediction_key (str, default "predicted_atomic_energies") – Prediction container key for the student’s per-atom energy head.

  • normalize_by_atom_count (bool, default True) – When True, compute a mean per-atom residual per graph, then mean over graphs. When False, compute one global mean over valid atoms.

  • ignore_nonfinite (bool, default True) – When True, atoms whose target energy is NaN or infinite are excluded from both loss value and gradient using torch.isfinite(). A graph whose atoms are all non-finite contributes 0.0.

  • dtype_policy ({"strict", "prediction_to_target", "target_to_prediction"}, default "strict") – How to handle prediction/target dtype mismatches before validation. "strict" raises; the other policies cast one tensor to match the other.

Raises:

ValueError – If the graph-balanced reduction is requested without batch_idx and num_graphs metadata.

Examples

>>> import torch
>>> from nvalchemi.training.distillation import AtomicEnergyMatchingLoss
>>> loss_fn = AtomicEnergyMatchingLoss()
>>> pred = torch.tensor([0.0, 2.0, 0.0])
>>> target = torch.zeros(3)
>>> batch_idx = torch.tensor([0, 0, 1])
>>> loss_fn(pred, target, batch_idx=batch_idx, num_graphs=2)
tensor(1.)

Notes

DistillationStrategy derives the atomic_energies signal from this term’s target_key and, under the stock training_fn, refuses a student that does not compute atomic_energies; a custom training_fn owns that contract, and a prediction it never produces surfaces as a missing-prediction KeyError on the first batch.

A residual below single precision is reduced in float32, so the returned scalar and per_sample_loss come back as float32 for a bfloat16 or float16 prediction while gradients reach it in its own dtype.

Per-atom energies are not observable on their own, so this term is a regularizer on the student’s decomposition: pair it with a total-energy term that keeps the extensive quantity anchored.

compute_residual(pred, target, valid)[source]#

Return squared per-atom energy residuals, zeroing invalid atoms.

Parameters:
  • pred (Float[Tensor, 'V'])

  • target (Float[Tensor, 'V'])

  • valid (Bool[Tensor, 'V'])

Return type:

Float[Tensor, ‘V’]

extra_repr()[source]#

Human-readable hyperparameter summary for nn.Module’s repr.

Return type:

str

mask(pred, target, ctx, **kwargs)[source]#

Return one validity flag per atom for the target energies.

Parameters:
  • pred (Float[Tensor, 'V'])

  • target (Float[Tensor, 'V'])

  • ctx (ReductionContext)

  • kwargs (Any)

Return type:

Bool[Tensor, ‘V’]

reduce(residual, valid, ctx, **kwargs)[source]#

Reduce per-atom squared residuals to a scalar loss.

masked_mean() takes the global mean over valid entries, or the graph-balanced one when normalize_by_atom_count is set, in at least float32 either way.

Parameters:
  • residual (Float[Tensor, 'V'])

  • valid (Bool[Tensor, 'V'])

  • ctx (ReductionContext)

  • kwargs (Any)

Return type:

Tensor