nvalchemi.training.distillation.DistillationStrategy#
- pydantic model nvalchemi.training.distillation.DistillationStrategy[source]#
Train a student against a frozen teacher’s signals.
A
TrainingStrategyover the named models"student"and"teacher". The teacher is frozen by omission — it must not appear inoptimizer_configs— while the student and any auxiliary model must be configured with one. Teacher knowledge reaches the loss asteacher_*batch fields, so a built-in term distills by pointing itstarget_keyat one (EnergyMSELoss(target_key="teacher_energy")) andAtomicEnergyMatchingLossreadsteacher_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 avalidation_configloss read, or named inteacher_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 stockdefault_distillation_fn(). Nothing re-runs on assignment, so passvalidation_configto the constructor or, when rebuilding from a spec that excludes it, tofrom_spec_dict(). Every resolved signal is required on every batch: a batch missing any resolved field is labeled on the fly by an internalBEFORE_FORWARDhook, in training and validation alike, unlesslabel_missing=Falseleaves it to surface as a missing loss target, while a store written bylabel_dataset()with the same signal set trains with no teacher pass at all. Ateacher_*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_policyswitchesrun()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 andreference_datasetat the configuredreplay_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 withmodels["student"]at construction. For a relaxation propagator, setOnPolicyConfig.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()orhessian_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
modelsis 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 thepredicted_namespace under a stocktraining_fn, if an explicitteacher_signalsomits 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 iflabel_dtypeis 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 declaresfrozen_student=Trueover 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, ifon_policy.samples_equilibriumisFalse, if it is leftNoneand the propagator relaxes or converges graphs out, if the term sits in the validation loss, or if avalidation_confighas noloss_fnof 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, ifreplay_ratioandreference_datasetdisagree (a ratio below1requires a reference dataset and a ratio of1rejects one), ifreference_datasetis empty or emits on an accelerator the run does not train on, ifreplay_deviceor 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 tolabel_dtypewhen one is given. By default the label dtype is inferred as the student’s first floating-point parameter dtype, never below single precision, so abfloat16orfloat16student gets float32 labels and needsdtype_policy="prediction_to_target"on its loss terms; a float64 student reads float32 back from a store and needs adtype_policytoo. Setlabel_dtypeexplicitly 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 oneUserWarningnaming 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()andload_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"), whileuse_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_policyandreference_datasethold 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(), andload_checkpoint()accept them, together with themodelsthe 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.
Nonederives them from theteacher_*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.Falseskips 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.
Noneinfers 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
runinto on-policy distillation.Nonekeeps the offline loop over the dataloader the caller passes torun.
- field reference_dataset: BatchDatasetProtocol | None = None#
Teacher-labeled dataset the on-policy mixture draws its
1 - replay_ratioshare from. Required whenever the ratio is below 1, and read only in on-policy mode.