# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Atomic energy matching loss for knowledge distillation."""
from __future__ import annotations
from typing import Any, TypeAlias
import torch
from jaxtyping import Bool, Float
from nvalchemi.training.losses.composition import (
BaseLossFunction,
DTypePolicy,
ReductionContext,
)
from nvalchemi.training.losses.reductions import masked_mean
__all__ = ["AtomicEnergyMatchingLoss"]
_NodeEnergies: TypeAlias = Float[torch.Tensor, "V"]
_NodeMask: TypeAlias = Bool[torch.Tensor, "V"]
[docs]
class AtomicEnergyMatchingLoss(BaseLossFunction):
r"""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
:class:`~nvalchemi.training.distillation.InProcessTeacherScorer` writes to
``teacher_atomic_energies``. The per-atom residual is
.. math::
\rho_{ia} = \left(\hat{\varepsilon}_{ia} - \varepsilon_{ia}\right)^2,
where :math:`\hat{\varepsilon}_{ia}` is the student's energy for atom
:math:`a` of graph :math:`i` and :math:`\varepsilon_{ia}` the teacher's.
Only valid atoms enter either sum or either denominator: writing
:math:`\mathcal{V}_i` for the atoms of graph :math:`i` that ``mask``
accepts, :math:`M_i = |\mathcal{V}_i|`, and :math:`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,
.. math::
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,
:math:`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 :func:`~nvalchemi.training.losses.composition.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 :func:`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
-----
:class:`~nvalchemi.training.distillation.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
:class:`KeyError` on the first batch.
A residual below single precision is reduced in float32, so the returned
scalar and :attr:`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.
"""
requires_eval_grad: bool = False
def __init__(
self,
*,
target_key: str = "teacher_atomic_energies",
prediction_key: str = "predicted_atomic_energies",
normalize_by_atom_count: bool = True,
ignore_nonfinite: bool = True,
dtype_policy: DTypePolicy = "strict",
) -> None:
"""Configure attribute keys and per-atom energy reduction semantics."""
super().__init__(dtype_policy=dtype_policy)
self.target_key = target_key
self.prediction_key = prediction_key
self.normalize_by_atom_count = normalize_by_atom_count
self.ignore_nonfinite = ignore_nonfinite
[docs]
def mask(
self,
pred: _NodeEnergies,
target: _NodeEnergies,
ctx: ReductionContext,
**kwargs: Any,
) -> _NodeMask:
"""Return one validity flag per atom for the target energies."""
if self.ignore_nonfinite:
return torch.isfinite(target)
return torch.ones_like(target, dtype=torch.bool)
[docs]
def compute_residual(
self,
pred: _NodeEnergies,
target: _NodeEnergies,
valid: _NodeMask,
) -> _NodeEnergies:
"""Return squared per-atom energy residuals, zeroing invalid atoms."""
residual = torch.where(valid, pred - target, torch.zeros_like(pred))
return residual.pow(2)
[docs]
def reduce(
self,
residual: _NodeEnergies,
valid: _NodeMask,
ctx: ReductionContext,
**kwargs: Any,
) -> torch.Tensor:
"""Reduce per-atom squared residuals to a scalar loss.
:func:`~nvalchemi.training.losses.reductions.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.
"""
loss, per_sample = masked_mean(
residual,
valid,
graph_balanced=self.normalize_by_atom_count,
batch_idx=kwargs.get("batch_idx"),
num_graphs=kwargs.get("num_graphs"),
batch=kwargs.get("batch"),
loss_name=type(self).__name__,
)
if per_sample is not None:
self.per_sample_loss = per_sample.detach()
return loss