nvalchemi.training.distillation.DistillationStrategy#

pydantic model nvalchemi.training.distillation.DistillationStrategy[source]#

Train a student against a frozen teacher’s signals.

A TrainingStrategy over the named models "student" and "teacher". The teacher is frozen by omission — it must not appear in optimizer_configs — while the student and any auxiliary model must be configured with one. Teacher knowledge reaches the loss as teacher_* batch fields, so a built-in term distills by pointing its target_key at one (EnergyMSELoss(target_key="teacher_energy")) and AtomicEnergyMatchingLoss reads teacher_atomic_energies; mixing teacher and reference targets is ordinary loss composition.

The signals the teacher is asked for are derived from the teacher_* targets the training loss and a validation_config loss read, or named in teacher_signals, which must cover the derived set. They are checked against the teacher’s outputs at construction, as are both losses’ prediction keys against the outputs the student actually computes whenever the effective training or validation function is the stock default_distillation_fn(). Nothing re-runs on assignment, so pass validation_config to the constructor or, when rebuilding from a spec that excludes it, to from_spec_dict(). Every resolved signal is required on every batch: a batch missing any resolved field is labeled on the fly by an internal BEFORE_FORWARD hook, in training and validation alike, unless label_missing=False leaves it to surface as a missing loss target, while a store written by label_dataset() with the same signal set trains with no teacher pass at all. A teacher_* target no built-in signal populates is a custom field such a store carries: it is neither derived nor attached, and a batch lacking it fails as a missing target. See Distillation API for the full contract.

Setting on_policy switches run() to the on-policy segment loop instead. In each segment, the student’s own propagator generates frames and the teacher labels them. The labeled frames accumulate in a replay buffer. The segment then trains on a mixture of that buffer and reference_dataset at the configured replay_ratio. The propagator holds the very module the optimizer updates, so every segment generates from a fresher policy than the last. That is what makes the data on-policy, and it is why the propagator’s model is checked for object identity with models["student"] at construction. For a relaxation propagator, set OnPolicyConfig.fmax. Converged structures are then stored once, graduate out of the batch at the segment boundary, and are replaced by fresh initial structures. The buffer therefore keeps filling with structures that are still moving.

Beyond the signals that have a supervised shape, three objectives need more from the run than a target field. Embedding matching compares the student’s and teacher’s per-atom representations. It needs a second pass over the batch on both sides. Across architectures, it also needs the learnable EmbeddingProjector, registered as a "projector" model with an optimizer of its own. Hessian matching compares Hessian-vector products, the products of each model’s energy Hessian with a random probe direction. It needs the student’s energy differentiated twice along the probe the teacher was labeled with. Neither of these predictions is a forward-pass output, so each objective needs the training function that produces it: embedding_distillation_fn() or hessian_distillation_fn(). Boltzmann matching compares the two models’ Boltzmann distributions over configurations. It needs no new prediction, but it does need the on-policy loop, because it reads a batch as a sample of the student’s own ensemble. All three requirements are checked at construction.

Raises:

ValueError – If models is not a named mapping containing "student" and "teacher", if the teacher is given an optimizer config, if the student or an auxiliary model is not, if a loss component reads a prediction the student does not compute or names one outside the predicted_ namespace under a stock training_fn, if an explicit teacher_signals omits a signal a loss needs, if no built-in teacher signal is requested at all, if the teacher cannot produce a requested signal, if the teacher is a composition that plans more than one neighbor-list source, or if label_dtype is not a floating-point dtype. With an embedding objective under the stock embedding training function, also if the student publishes no node-embedding shape, if the student, projector, and teacher widths do not compose, or if the projector declares frozen_student=True over a fully trainable student. With a Hessian objective, also if the student computes no energy. With a Boltzmann objective, also if the run is not on-policy, if on_policy.samples_equilibrium is False, if it is left None and the propagator relaxes or converges graphs out, if the term sits in the validation loss, or if a validation_config has no loss_fn of its own and would reuse the training loss. In on-policy mode, also if the run is sized in epochs, if the propagator holds neither the student nor a model composing it, if replay_ratio and reference_dataset disagree (a ratio below 1 requires a reference dataset and a ratio of 1 rejects one), if reference_dataset is empty or emits on an accelerator the run does not train on, if replay_device or the reference dataset’s fields cannot be mixed with generated frames, or if the propagator’s scorer and the reference dataset do not carry the same teacher fields.

Examples

Distill energies, forces, and the teacher’s per-atom energy decomposition from a store written by label_dataset():

>>> import torch
>>> from nvalchemi.training import EnergyMSELoss, ForceMSELoss, OptimizerConfig
>>> from nvalchemi.training.distillation import (
...     DistillationStrategy,
...     AtomicEnergyMatchingLoss,
... )
>>> loss_fn = (
...     EnergyMSELoss(target_key="teacher_energy")
...     + ForceMSELoss(target_key="teacher_forces", normalize_by_atom_count=True)
...     + 0.1 * AtomicEnergyMatchingLoss()
... )
>>> strategy = DistillationStrategy(
...     models={"student": student, "teacher": teacher},
...     optimizer_configs={
...         "student": [OptimizerConfig(optimizer_cls=torch.optim.Adam)]
...     },
...     loss_fn=loss_fn,
...     num_steps=1_000,
... )
>>> strategy.run(labeled_loader)

Notes

Label precision is the scorer’s decision. The strategy’s own scorer is an InProcessTeacherScorer, which disables autocast. It casts labels to label_dtype when one is given. By default the label dtype is inferred as the student’s first floating-point parameter dtype, never below single precision, so a bfloat16 or float16 student gets float32 labels and needs dtype_policy="prediction_to_target" on its loss terms; a float64 student reads float32 back from a store and needs a dtype_policy too. Set label_dtype explicitly when the inference guesses wrong, as for a mixed-precision student whose first parameter is not representative or a student exposing no parameters at all, which otherwise keeps the teacher’s own dtype. Labels are attached to the device-placed copy the strategy trains on, not the caller’s batch, so a loader replaying the same systems costs one teacher pass per epoch, and the first batch labeled this way raises one UserWarning naming the fields it lacked.

Teacher conservativeness is not validated: a teacher predicting forces from its own head is first class, since every signal is detached before the student sees it. A teacher composition planning more than one neighbor-list source is refused, as by InProcessTeacherScorer.

The labeling hook is never serialized; from_spec_dict() and load_checkpoint() re-register it ahead of the caller’s hooks and replace any carried copy. ValidationConfig(use_ema="auto") validates the EMA student against the live teacher (model_source="mixed"), while use_ema="always" also demands an inference-slot entry for the teacher. Checkpoints serialize every model, teacher included, so size the checkpoint interval for a large teacher.

on_policy and reference_dataset hold live runtime objects that no spec can describe. to_spec_dict() therefore omits them and warns. A strategy rebuilt from such a spec runs offline until they are supplied again. from_spec_dict(), from_checkpoint_dict(), and load_checkpoint() accept them, together with the models the propagator holds. A strategy with a Boltzmann term refuses to rebuild without the loop, so for it the re-supply is mandatory.

field teacher_signals: frozenset[str] | None = None#

Teacher signals produced for every scored batch. None derives them from the teacher_* targets the training and validation losses read; an explicit set must cover those and may request more, at the cost of re-scoring every batch a store labeled without the extra fields delivers.

field label_missing: bool = True#

Whether a batch lacking the required teacher_* fields is labeled on the fly by a teacher forward pass, in training and validation alike. False skips the teacher, so an unlabeled batch surfaces as a missing loss target.

field label_dtype: dtype | None = None#

Floating-point dtype teacher labels are cast to when a batch is labeled on the fly. None infers it from the student’s first floating-point parameter, never below float32; an explicit dtype is passed to the teacher scorer verbatim.

field on_policy: OnPolicyConfig | None = None#

Segment-loop configuration turning run into on-policy distillation. None keeps the offline loop over the dataloader the caller passes to run.

field reference_dataset: BatchDatasetProtocol | None = None#

Teacher-labeled dataset the on-policy mixture draws its 1 - replay_ratio share from. Required whenever the ratio is below 1, and read only in on-policy mode.