nvalchemi.training.distillation.TeacherLabelHook#
- class nvalchemi.training.distillation.TeacherLabelHook(teacher_scorer, sink=None, frequency=1, exit_status=None)[source]#
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 aDataSink. The live batch keeps theenergyandforcesthe 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 outsideteacher_*is rejected, so it cannot overwrite propagator state.With
exit_statusset, graphs whosestatushas reached it are left out of that copy and out of the teacher pass that labels it. A lifecycle freezes those graphs atexit_statusand 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 asksstored_graphs()before it writes, so a structure that a step budget graduates right after this hook stored its frame is not stored twice. Withoutexit_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 nostatusis 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 Distillation API.
- Parameters:
teacher_scorer (TeacherScorer) – Scorer that produces the teacher signals. A scorer that publishes
label_fieldsmakes 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
frequencysteps. Default1.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
Nonelabels and stores every graph.
- Raises:
ValueError – If the scorer declares, or returns, a field outside
teacher_*.
See also
nvalchemi.dynamics.hooks.SnapshotHookCapture frames without labeling them.
nvalchemi.training.distillation.label_datasetLabel a dataset offline.
Examples
>>> from nvalchemi.dynamics.sinks import HostMemory >>> from nvalchemi.training.distillation import ( ... InProcessTeacherScorer, ... TeacherLabelHook, ... ) >>> scorer = InProcessTeacherScorer(teacher, ["energy", "forces"]) >>> sink = HostMemory(capacity=10_000) >>> dynamics.register_hook(TeacherLabelHook(scorer, sink=sink, frequency=10))
Notes
This hook is not the labeling seam inside
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 itsautocastsetting says otherwise, so a frame it labels during a mixed-precision generation phase matches whatlabel_dataset()writes offline.requires_gradhandling is the scorer’s responsibility, and the scorer leaves the batch ascompute()left it.- property labeled_step: 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.
- stored_graphs(step_count, batch)[source]#
Return the graphs of batch whose frame this hook stored on step_count.
Nonewhen the hook stored nothing on that step. The converged-frame route calls this atON_GRADUATEand 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.- Parameters:
step_count (int)
batch (Batch)
- Return type:
Bool[torch.Tensor, ‘G’] | None