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’satomic_energiessignal, whichInProcessTeacherScorerwrites toteacher_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
maskaccepts, \(M_i = |\mathcal{V}_i|\), and \(M = \sum_i M_i\), the residuals are reduced according tonormalize_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=Truethose 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 contributes0.0.The graph-balanced reduction needs
batch_idxandnum_graphsmetadata, whichcompute_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. WhenFalse, compute one global mean over valid atoms.ignore_nonfinite (bool, default True) – When
True, atoms whose target energy isNaNor infinite are excluded from both loss value and gradient usingtorch.isfinite(). A graph whose atoms are all non-finite contributes0.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_idxandnum_graphsmetadata.
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
DistillationStrategyderives theatomic_energiessignal from this term’starget_keyand, under the stocktraining_fn, refuses a student that does not computeatomic_energies; a customtraining_fnowns that contract, and a prediction it never produces surfaces as a missing-predictionKeyErroron the first batch.A residual below single precision is reduced in float32, so the returned scalar and
per_sample_losscome back as float32 for abfloat16orfloat16prediction 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’]
- 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 whennormalize_by_atom_countis set, in at least float32 either way.- Parameters:
residual (Float[Tensor, 'V'])
valid (Bool[Tensor, 'V'])
ctx (ReductionContext)
kwargs (Any)
- Return type: