nvalchemi.training.distillation.TeacherSignal#

class nvalchemi.training.distillation.TeacherSignal(name, model_output, field, level, normalize=None, extra_fields=())[source]#

Model output, batch field, level, and shape rule behind one teacher signal.

A signal names what the teacher produces — model_output, a key in its outputs — and where the label lands: field, at level. A signal with model_output=None is one the scorer derives outside the forward pass, such as the built-in embeddings through compute_embeddings(); a custom signal must name an output. Pass an instance to InProcessTeacherScorer beside the built-in names to label a teacher output the built-in table does not cover.

Parameters:
  • name (str) – Signal name, as a scorer is asked for it.

  • model_output (str | None) – Key of the teacher output the label is read from, or None for a signal the scorer derives by a route of its own.

  • field (str) – Batch field the label populates; must start with teacher_.

  • level (SignalLevel) – "node" for one row per atom, "system" for one per graph.

  • normalize (SignalNormalizer | None, optional) – Reshapes the detached raw output to the field’s canonical shape, given the batch it was produced for. For a signal with companion fields, it instead returns a mapping from every name in fields to its tensor, all at level. Default None (keep the shape).

  • extra_fields (tuple[str, ...], optional) – Companion fields the signal writes beside field, each in the teacher_* namespace and produced by normalize. Default ().

Raises:

ValueError – If field or a companion field falls outside the teacher_* namespace, if level is neither "node" nor "system", or if a signal read from a model output declares companion fields without a normalize to produce them.

Examples

>>> from nvalchemi.training.distillation import TeacherSignal
>>> charges = TeacherSignal("charges", "charges", "teacher_charges", "node")
>>> charges.fields
('teacher_charges',)
property fields: tuple[str, ...]#

Return every batch field the signal populates, its own first.