# 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.
"""Dynamics hooks that capture on-policy frames as a propagator produces them."""
from __future__ import annotations
from typing import TYPE_CHECKING, TypeAlias
import torch
from jaxtyping import Bool
from nvalchemi.dynamics.base import BaseDynamics, DynamicsStage
from nvalchemi.dynamics.hooks.safety import nonfinite_graph_mask
from nvalchemi.dynamics.hooks.snapshot import ConvergedSnapshotHook
from nvalchemi.training.distillation._attach import (
_attach_teacher_labels,
_prune_empty_edges,
)
from nvalchemi.training.distillation.scoring import (
_NEIGHBOR_KEYS,
_reject_foreign_fields,
scorer_fields,
)
if TYPE_CHECKING:
from collections.abc import Callable
from enum import Enum
from nvalchemi.data import Batch
from nvalchemi.dynamics.sinks import DataSink
from nvalchemi.hooks import DynamicsContext
from nvalchemi.training.distillation.scoring import TeacherLabels, TeacherScorer
_DivergencePredicate: TypeAlias = Callable[[Batch], Bool[torch.Tensor, "G"]]
__all__ = ["TeacherLabelHook", "nonfinite_divergence"]
_PREDICTION_KEYS = frozenset(BaseDynamics._OUTPUT_KEY_TO_BATCH_ATTR.values())
"""Batch fields a propagator overwrites with the propagated model's predictions."""
def _run_local_keys(dynamics: BaseDynamics) -> frozenset[str]:
"""Return the fields of a live frame that mean nothing outside its run.
The bookkeeping part is read from *dynamics* at call time through
:meth:`~nvalchemi.dynamics.base.BaseDynamics.bookkeeping_keys`, which
walks the composition, because
:meth:`~nvalchemi.dynamics.base.BaseDynamics.register_bookkeeping_key`
grows the registries as stages are built. For example, a fused stage
registers one step counter per sub-stage, and keeps a ``reprime_pending``
flag of its own. A hook therefore reads the propagator it is registered
on, and belongs on the root of a composition so that root's own keys are
included.
"""
return _NEIGHBOR_KEYS | _PREDICTION_KEYS | dynamics.bookkeeping_keys()
def _score_and_attach(scorer: TeacherScorer, frame: Batch) -> TeacherLabels:
"""Label *frame* in place with *scorer*, refusing a label outside ``teacher_*``.
The scorer is called inside the caller's autocast region, if any. Label
precision is the scorer's decision, and
:class:`~nvalchemi.training.distillation.InProcessTeacherScorer` disables
autocast unless its ``autocast`` setting says otherwise. A label outside
``teacher_*`` is refused before it can overwrite propagator state.
Returns
-------
TeacherLabels
The attached labels, so a caller can resolve the fields the scorer
writes.
Raises
------
ValueError
If the scorer returns a field outside ``teacher_*``.
"""
labels = scorer.label(frame)
_attach_teacher_labels(frame, labels)
return labels
def _strip_replay_frame(frames: Batch, dynamics: BaseDynamics) -> Batch:
"""Reduce *frames* to the replay-frame contract, in place.
A frame captured from the propagator carries run-local fields: the
ephemeral neighbor tensors, the dynamics bookkeeping, and the ``energy``,
``forces``, and ``stress`` the propagated model wrote. A replay frame keeps
only the structure, the propagator state that travels with it, and the
``teacher_*`` labels. A stored frame therefore never offers the propagated
model's own prediction under a reference target's name.
Parameters
----------
frames : Batch
Frames to strip, mutated in place.
dynamics : BaseDynamics
Propagator that wrote *frames*, whose bookkeeping keys are dropped.
Returns
-------
Batch
The same object, holding nothing run-local.
"""
dropped = _run_local_keys(dynamics)
for key in dropped:
if key in frames:
del frames[key]
if frames.keys is not None:
for names in frames.keys.values():
names -= dropped
_prune_empty_edges(frames)
return frames
nonfinite_divergence = nonfinite_graph_mask
"""Default :attr:`~nvalchemi.training.distillation.OnPolicyConfig.divergence`: :func:`~nvalchemi.dynamics.hooks.nonfinite_graph_mask` over positions and forces."""
[docs]
class TeacherLabelHook:
"""Label the live propagator frame with teacher signals, inline.
The hook runs at ``AFTER_STEP``. It attaches every signal its scorer
produces to the batch being propagated, each at the level its signal
declares. It can also copy the labeled frame into a
:class:`~nvalchemi.dynamics.sinks.DataSink`. The live batch keeps the
``energy`` and ``forces`` the propagator wrote, because they drive the
next step. The copy drops them, the ephemeral neighbor tensors, and the
dynamics bookkeeping. A stored frame is therefore a training sample rather
than a propagator state, and it never carries the propagated model's own
prediction under a reference target's name. A scorer that declares or
returns a field outside ``teacher_*`` is rejected, so it cannot overwrite
propagator state.
With ``exit_status`` set, graphs whose ``status`` has reached it are left
out of that copy and out of the teacher pass that labels it. A lifecycle
freezes those graphs at ``exit_status`` and stores each one once, through
a separate converged-frame route. Capturing them here would store and
score the same structure again on every later capture of the segment.
The hook records which graphs it stored on which step. The
converged-frame route asks :meth:`stored_graphs` before it writes, so a
structure that a step budget graduates right after this hook stored its
frame is not stored twice. Without ``exit_status``, every graph is
captured, frozen or not, because nothing else keeps the final frame of a
graduation the propagator manages itself. A frame that carries no
``status`` is labeled and captured whole either way, and a hook without a
sink labels every frame whole.
Labeling is idempotent per step. A cadence dispatch right after a forced
label is skipped, so the teacher is not paid twice for a segment's last
frame and the next cadence step. See :ref:`training-distillation-api`.
Parameters
----------
teacher_scorer : TeacherScorer
Scorer that produces the teacher signals. A scorer that publishes
``label_fields`` makes the idempotency check exact from the first
dispatch.
sink : DataSink | None, optional
Sink each labeled frame is copied into. Default ``None``.
frequency : int, optional
Label every ``frequency`` steps. Default ``1``.
exit_status : int | None, optional
Propagator status at which a graph counts as graduated. A graduated
graph is stored by another route, so this hook leaves it out. Default
``None`` labels and stores every graph.
Raises
------
ValueError
If the scorer declares, or returns, a field outside ``teacher_*``.
See Also
--------
nvalchemi.dynamics.hooks.SnapshotHook : Capture frames without labeling them.
nvalchemi.training.distillation.label_dataset : Label a dataset offline.
Examples
--------
>>> from nvalchemi.dynamics.sinks import HostMemory
>>> from nvalchemi.training.distillation import (
... InProcessTeacherScorer,
... TeacherLabelHook,
... )
>>> scorer = InProcessTeacherScorer(teacher, ["energy", "forces"]) # doctest: +SKIP
>>> sink = HostMemory(capacity=10_000) # doctest: +SKIP
>>> dynamics.register_hook(TeacherLabelHook(scorer, sink=sink, frequency=10)) # doctest: +SKIP
Notes
-----
This hook is not the labeling seam inside
:class:`~nvalchemi.training.distillation.DistillationStrategy`, which is a
training hook that labels batches on their way into a forward pass. The
two run on different engines, and both are active in an on-policy run.
Label precision is the scorer's decision, and the hook opens no autocast
region of its own. The built-in scorer disables autocast unless its
``autocast`` setting says otherwise, so a frame it labels during a
mixed-precision generation phase matches what
:func:`~nvalchemi.training.distillation.label_dataset` writes offline.
``requires_grad`` handling is the scorer's responsibility, and the scorer
leaves the batch as :meth:`~nvalchemi.dynamics.base.BaseDynamics.compute`
left it.
"""
def __init__(
self,
teacher_scorer: TeacherScorer,
sink: DataSink | None = None,
frequency: int = 1,
exit_status: int | None = None,
) -> None:
"""Resolve the fields the scorer populates, when they can be known."""
self.teacher_scorer = teacher_scorer
self.sink = sink
self.frequency = frequency
self.exit_status = exit_status
self.stage = DynamicsStage.AFTER_STEP
self._teacher_fields: tuple[str, ...] | None = scorer_fields(teacher_scorer)
if self._teacher_fields is not None:
_reject_foreign_fields(self._teacher_fields, "A scorer's label_fields")
self._labeled_step: int | None = None
self._stored: tuple[int, torch.Tensor | None] | None = None
@property
def labeled_step(self) -> int | None:
"""Propagator step this hook last labeled a frame on, or ``None``.
A step on which every graph had already graduated leaves it
unchanged, because nothing was labeled. A segment loop uses this to
tell a step the cadence covered from one it skipped.
"""
return self._labeled_step
[docs]
def stored_graphs(
self, step_count: int, batch: Batch
) -> Bool[torch.Tensor, "G"] | None:
"""Return the graphs of *batch* whose frame this hook stored on *step_count*.
``None`` when the hook stored nothing on that step. The converged-frame
route calls this at ``ON_GRADUATE`` and skips a graph whose final frame
this hook already stored. That happens when a step budget graduates
the graph after this hook ran on the same step.
"""
if self._stored is None or self._stored[0] != step_count:
return None
stored = torch.ones(batch.num_graphs, dtype=torch.bool, device=batch.device)
active = self._stored[1]
if active is not None:
stored.zero_()
stored[active] = True
return stored
@torch.compiler.disable
def _label_frame(
self,
batch: Batch,
step_count: int,
*,
dynamics: BaseDynamics,
forced: bool = False,
) -> None:
"""Label the graphs of *batch* that are still moving, once per step.
The frame is narrowed to the graphs below ``exit_status`` before the
teacher sees it. The status is read as it is now, not from the
step-start mask in the hook context, so a graph the criterion froze
earlier in this step is already left out. The run therefore pays
neither for labeling a graduated graph nor for copying it into the
sink. Whenever a graph is cut, the live batch itself is left
unlabeled. A second dispatch at the same step then recognizes its own
work from the step count, because the batch never received the label
fields.
*dynamics* is the propagator that wrote *batch*; the copy handed to
the sink drops its bookkeeping. *forced* marks an out-of-band call
that labels a frame the cadence did not land on, such as the last
frame of an on-policy segment. The adjacency rule never skips a forced
call, and the dynamics registry never makes one.
"""
if (
not forced
and self.frequency > 1
and self._labeled_step is not None
and step_count == self._labeled_step + 1
):
return
active = None
if self.sink is not None and self.exit_status is not None:
moving = BaseDynamics.active_graph_mask(batch, self.exit_status)
if moving is not None and not bool(moving.all()):
active = torch.where(moving)[0]
if active is not None and active.numel() == 0:
return
stored = step_count == self._labeled_step
if stored and (
active is not None
or (
self._teacher_fields is not None
and all(field in batch for field in self._teacher_fields)
)
):
return
frame = (
batch if active is None else self._captured_frame(batch, dynamics, active)
)
labels = _score_and_attach(self.teacher_scorer, frame)
if self._teacher_fields is None:
self._teacher_fields = tuple(sorted(labels))
self._labeled_step = step_count
if self.sink is None or stored:
return
self.sink.write(
frame if active is not None else self._captured_frame(batch, dynamics)
)
self._stored = (step_count, active)
def _captured_frame(
self, batch: Batch, dynamics: BaseDynamics, active: torch.Tensor | None = None
) -> Batch:
"""Return a copy of *batch* holding nothing run-local.
The copy leaves out every run-local field, read from *dynamics*, and
the live batch keeps the neighbor tensors and predictions the next
step reads. An edge
group left empty is removed too, so a store never records edges that
no array backs. *active*, when given, narrows the copy to the graphs
still moving, for a lifecycle that graduates graphs out of the batch.
The copy is taken under :func:`torch.no_grad`. A fused propagator
keeps its autograd inputs tracking gradients across its hooks, so a
stored frame would otherwise carry the step's autograd graph into the
first training pass.
"""
dropped = _run_local_keys(dynamics)
with torch.no_grad():
frame = (
batch.clone(drop=dropped)
if active is None
else batch.index_select(active, drop=dropped)
)
_prune_empty_edges(frame)
return frame
def __call__(self, ctx: DynamicsContext, stage: Enum) -> None: # noqa: ARG002
"""Label the frame the propagator has just resolved."""
self._label_frame(ctx.batch, ctx.step_count, dynamics=ctx.workflow)
class _DivergenceHook:
"""Evaluate the divergence predicate once per step and freeze what it flags.
A diverged relaxation never converges, because every comparison with NaN
is false. Without this hook, nothing would migrate its status, the path
route would keep storing and labeling it, and its labels would reach the
loss. Freezing the graph at the propagator's ``exit_status`` takes it out
of the step and out of both capture routes. The segment boundary then
retires and backfills it like a converged graph. An
:class:`~nvalchemi.training.distillation.AdmissionPolicy` that refuses
non-finite frames at the buffer would achieve the exclusion alone. The
lifecycle still freezes the graph itself, because freezing also stops
propagating and labeling it.
The lifecycle calls the predicate only here, once per step. Each verdict
is ORed into :attr:`diverged`. The converged-frame hook and the segment
boundary read that record and never call the predicate themselves. A
graph that a stateful predicate flags on one step and not on the next
therefore stays out of the converged route and still counts as diverged
at the boundary. :meth:`reset` clears the record once a refill has
changed the batch's rows.
A frozen graph still goes through the propagator's step: the integrator
moves the whole batch and the model evaluates it, and only afterwards are
the frozen graphs' positions, velocities, and cell restored from a
snapshot taken before the step. A graph frozen with non-finite forces or
velocities therefore keeps presenting a non-finite or runaway geometry to
the model on every remaining step of the segment, which a model's
neighbor-list builder may not survive. With ``quarantine`` set, the hook
sanitizes a graph on the step it flags it: velocities and forces are
zeroed and positions made finite. The hook runs at ``AFTER_STEP``, after
that step's restore, and the graph is inactive on every later step, so
each later snapshot and restore carries the sanitized positions and
velocities, the zero velocity moves nothing, and the masked output
publication keeps the zeroed forces. The sanitized frame is still
recorded as diverged and never captured.
Parameters
----------
divergence : Callable[[Batch], Bool[torch.Tensor, "G"]], optional
Predicate flagging the diverged graphs of the live frame. Its verdict
is moved onto the batch's device before it is recorded, so a predicate
that judges on the host is accepted for a frame on an accelerator.
Default :func:`nonfinite_divergence`.
quarantine : bool, optional
Sanitize each graph's state on the step it is flagged: velocities and
forces zeroed, positions restored to the graph's last finite frame.
Default ``False`` leaves the flagged state as it is.
Raises
------
TypeError
If the predicate returns something other than a tensor.
ValueError
If the tensor is not boolean or does not carry one entry per graph.
"""
frequency = 1
stage = DynamicsStage.AFTER_STEP
def __init__(
self,
divergence: _DivergencePredicate = nonfinite_divergence,
*,
quarantine: bool = False,
) -> None:
"""Freeze the graphs *divergence* flags, starting with none recorded."""
self.divergence = divergence
self.quarantine = quarantine
self._diverged: Bool[torch.Tensor, "G"] | None = None
self._last_finite: torch.Tensor | None = None
@property
def diverged(self) -> Bool[torch.Tensor, "G"] | None:
"""Graphs the predicate has flagged since the last reset, or ``None`` before the first verdict."""
return self._diverged
def reset(self) -> None:
"""Forget which graphs diverged, after a refill changed the batch."""
self._diverged = None
self._last_finite = None
def _flags(self, batch: Batch) -> Bool[torch.Tensor, "G"]:
"""Evaluate the predicate on *batch* and return its one-boolean-per-graph verdict on the batch's device."""
flags = self.divergence(batch)
if not isinstance(flags, torch.Tensor):
raise TypeError(
"The divergence predicate must return a boolean tensor with one flag "
f"per graph; got {type(flags).__name__!r}."
)
if flags.dtype != torch.bool or flags.shape != (batch.num_graphs,):
raise ValueError(
"The divergence predicate must return one boolean per graph; got "
f"shape={tuple(flags.shape)!r} of dtype {flags.dtype!r}, expected "
f"({batch.num_graphs},) of torch.bool."
)
return flags.to(batch.device)
def __call__(self, ctx: DynamicsContext, stage: Enum) -> None: # noqa: ARG002
"""Record the predicate's verdict and migrate the flagged graphs to the exit status."""
exit_status = getattr(ctx.workflow, "exit_status", None)
if exit_status is None:
return
moving = BaseDynamics.active_graph_mask(ctx.batch, exit_status)
if moving is None:
return
flags = self._flags(ctx.batch)
if self.quarantine:
self._remember_finite(ctx.batch, flags)
if self._diverged is None or self._diverged.numel() != flags.numel():
self._diverged = torch.zeros_like(flags)
self._diverged |= flags
frozen = flags & moving
status = ctx.batch.status
column = status.view(-1) if status.dim() == 2 else status
column[: ctx.batch.num_graphs].masked_fill_(frozen, exit_status)
if self.quarantine:
self._sanitize(ctx.batch, frozen)
def _remember_finite(self, batch: Batch, flags: Bool[torch.Tensor, "G"]) -> None:
"""Keep the positions of every unflagged graph as its last finite frame.
Rows of graphs the predicate flags keep the snapshot they had, so a
graph that diverges is restored to the step before its divergence
instead of collapsing onto one point. A batch whose shape changed (a
refill without :meth:`reset`) starts a fresh snapshot.
"""
positions = batch.positions.detach()
if self._last_finite is None or self._last_finite.shape != positions.shape:
self._last_finite = positions.clone()
return
nodes = flags[batch.batch_idx.long()]
keep = nodes.view(nodes.shape[0], *([1] * (positions.dim() - 1)))
self._last_finite = torch.where(keep, self._last_finite, positions)
def _sanitize(self, batch: Batch, graphs: Bool[torch.Tensor, "G"]) -> None:
"""Zero the velocities and forces of *graphs* and restore finite positions.
Positions come from the last finite snapshot when one exists; any
value still non-finite (a graph flagged on the very first step) is
zeroed as a last resort.
"""
nodes = graphs[batch.batch_idx.long()]
with torch.no_grad():
for key in ("velocities", "forces"):
tensor = getattr(batch, key, None)
if tensor is None:
continue
mask = nodes.view(nodes.shape[0], *([1] * (tensor.dim() - 1)))
tensor.masked_fill_(mask, 0.0)
positions = batch.positions
mask = nodes.view(nodes.shape[0], *([1] * (positions.dim() - 1)))
source = (
self._last_finite
if self._last_finite is not None
and self._last_finite.shape == positions.shape
else positions
)
finite = torch.nan_to_num(source, nan=0.0, posinf=0.0, neginf=0.0)
torch.where(mask, finite, positions, out=positions)
class _TrajectoryAgeHook:
"""Count each trajectory's propagator steps and retire it at a lifetime.
A thermostatted trajectory never converges, so without a lifetime the
structures of the initial batch are the only ones the run ever
propagates, and the teacher labels new geometries of the same molecules
for the whole run. This hook gives every trajectory a maximum age in
propagator steps. A graph that reaches it is frozen at the propagator's
``exit_status`` on that step, which the propagator reports at
``ON_GRADUATE``, where the converged-frame hook stores its final frame.
The segment boundary then retires and backfills it exactly like a
converged graph.
The age is kept per graph, in batch order, and follows the batch through
a backfill: :meth:`retain` keeps the survivors' ages and starts the fresh
rows at zero. A graph is aged on every step it was active in, so a graph
frozen earlier, by a criterion or by divergence, stops aging.
Parameters
----------
max_steps : int
Propagator steps a trajectory lives for before it is retired.
"""
frequency = 1
stage = DynamicsStage.AFTER_STEP
def __init__(self, max_steps: int) -> None:
"""Retire every trajectory once it has been propagated *max_steps* times."""
self.max_steps = max_steps
self._age: torch.Tensor | None = None
@property
def age(self) -> torch.Tensor | None:
"""Steps each graph of the live batch has been propagated, or ``None`` before the first."""
return self._age
def retain(self, survivors: torch.Tensor, fresh: int) -> None:
"""Keep the *survivors*' ages, in their new order, and age the *fresh* rows from zero."""
if self._age is None:
return
kept = self._age[survivors.to(self._age.device)]
self._age = torch.cat(
[kept, torch.zeros(fresh, dtype=kept.dtype, device=kept.device)]
)
def __call__(self, ctx: DynamicsContext, stage: Enum) -> None: # noqa: ARG002
"""Age the graphs that stepped and freeze the ones that reached the lifetime."""
exit_status = getattr(ctx.workflow, "exit_status", None)
if exit_status is None:
return
batch = ctx.batch
moving = BaseDynamics.active_graph_mask(batch, exit_status)
if moving is None:
return
stepped = moving if ctx.active_graph_mask is None else ctx.active_graph_mask
if self._age is None or self._age.numel() != batch.num_graphs:
self._age = torch.zeros(
batch.num_graphs, dtype=torch.long, device=batch.device
)
self._age += stepped.to(self._age.device).long()
expired = (self._age >= self.max_steps).to(batch.device) & moving
status = batch.status
column = status.view(-1) if status.dim() == 2 else status
column[: batch.num_graphs].masked_fill_(expired, exit_status)
class _ConvergedFrameHook(ConvergedSnapshotHook):
"""Capture each graduating structure once, on the step it stopped moving.
The hook listens at ``ON_GRADUATE``, the stage every
:class:`~nvalchemi.dynamics.base.BaseDynamics` and
:class:`~nvalchemi.dynamics.FusedStage` propagator dispatches with
``ctx.graduated_mask`` marking the graphs that graduated during the step.
A :class:`~nvalchemi.distributed.DomainParallel` propagator dispatches no
such stage, so :class:`~nvalchemi.training.distillation.OnPolicyConfig`
refuses one with a criterion. A graph graduates when its ``status``
reaches ``exit_status``, whether the lifecycle's criterion, a fused
sub-stage's step budget, or the divergence hook moved it. The parent's
``ON_CONVERGE`` stage does not work here, for two reasons.
:class:`~nvalchemi.dynamics.FusedStage` dispatches it on its sub-stages
only. It also fires with every graph the criterion currently accepts, not
only the ones that just reached it. The frames are captured without
teacher labels. The segment loop labels them in one teacher pass when it
drains the sink, which keeps the teacher's batch size independent of the
propagated batch size. A graph the divergence hook has
recorded as diverged is never written, because it diverged rather than
converged. A graph whose frame the path route stored on the same step is
not written again.
Parameters
----------
sink : DataSink
Sink converged frames are written to.
divergence : _DivergenceHook
Hook recording which graphs diverged, registered ahead of this one.
path : TeacherLabelHook | None, optional
Labeling hook of the path route, asked which graphs it stored on the
step. Default ``None`` skips that check, so every graduated graph that
did not diverge is written.
Notes
-----
The write runs under :func:`torch.no_grad`, because a fused propagator
keeps its autograd inputs tracking gradients across its hooks.
"""
def __init__(
self,
sink: DataSink,
divergence: _DivergenceHook,
path: TeacherLabelHook | None = None,
) -> None:
"""Listen at ``ON_GRADUATE`` for the graphs that graduate."""
super().__init__(sink=sink, stage=DynamicsStage.ON_GRADUATE)
self.divergence = divergence
self.path = path
def __call__(self, ctx: DynamicsContext, stage: Enum) -> None: # noqa: ARG002
"""Write the graphs that graduated on this step, and only those."""
fresh = ctx.graduated_mask
if fresh is None:
return
diverged = self.divergence.diverged
if diverged is not None:
fresh = fresh & ~diverged
if self.path is not None:
stored = self.path.stored_graphs(ctx.step_count, ctx.batch)
if stored is not None:
fresh = fresh & ~stored
with torch.no_grad():
self._write_converged(ctx.batch, fresh)