nvalchemi.training.distillation.BoltzmannMatchingLoss#
- class nvalchemi.training.distillation.BoltzmannMatchingLoss(*, target_key='teacher_energy', prediction_key='predicted_energy', beta=0.5, temperature=300.0, ignore_nonfinite=True, dtype_policy='strict', world_batch=None, check_one_system=True)[source]#
Relative entropy between the teacher’s and student’s Boltzmann distributions.
Energy and force matching are pointwise: they compare the two models one configuration at a time. Boltzmann matching instead asks that the student’s Boltzmann distribution over configurations match the teacher’s. That distribution decides whether a simulation driven by the student visits the same states with the same frequencies as one driven by the teacher. The term is blind to a constant energy offset and to any error that does not change relative populations.
Both distributions are the canonical ensemble at
temperature\(T\), with reduced energies \(u = U / k_\mathrm{B}T\). The batch’s configurations \(\{x_i\}_{i=1}^{B}\) are read as a sample of the student’s distribution, so the student’s empirical weights are uniform, \(\hat q_i = 1/B\). The teacher’s weights follow by reweighting:\[\Delta_i = \frac{U_T(x_i) - U_S(x_i)}{k_\mathrm{B}T}, \qquad \hat p_i = \frac{e^{-\Delta_i}}{\sum_j e^{-\Delta_j}}, \qquad \ell_i = \log(B \hat p_i).\]betainterpolates between the forward, mass-covering direction \(D_{\mathrm{KL}}(\hat p \Vert \hat q) = \sum_i \hat p_i \ell_i\) (beta=0) and the reverse, mode-seeking direction \(D_{\mathrm{KL}}(\hat q \Vert \hat p) = -\frac{1}{B}\sum_i \ell_i\) (beta=1). Both vanish exactly when \(U_T - U_S\) is constant across the batch.- Parameters:
target_key (str, default "teacher_energy") – Target container key for the teacher’s total energies, shape
(B, 1).prediction_key (str, default "predicted_energy") – Prediction container key for the student’s total energies.
beta (float, default 0.5) – Interpolation between the forward (
0) and reverse (1) relative entropy. Must lie in[0, 1].temperature (float, default 300.0) – Ensemble temperature in Kelvin. Set it to the on-policy thermostat’s temperature; nothing here can check that the two agree.
ignore_nonfinite (bool, default True) – When
True, graphs whose target or predicted energy isNaNor infinite are dropped from the distribution. Otherwise one non-finite student energy would poison every weight, and through the cross-rank gather (seeworld_batch) it would reach every rank’s softmax.Falseskips the check, for a run trusted to generate only finite energies.dtype_policy ({"strict", "prediction_to_target", "target_to_prediction"}, default "strict") – How to handle prediction/target dtype mismatches before validation.
world_batch (bool | None, default None) – Whether the softmax is normalized over the world batch, the union of every rank’s shard of the batch.
Nonegathers whenever a process group with more than one rank is initialized.Truealways gathers and refuses to run without a process group.Falsereduces over the local batch alone, for a run whose ranks hold independent ensembles.check_one_system (bool, default True) – Whether the term refuses a batch whose graphs hold different numbers of atoms. Equal atom counts are necessary but not sufficient for the graphs to be configurations of one system. Under data parallelism the check costs one
all_gather_objectcollective per step. Disable it for an ensemble whose composition legitimately varies, such as a grand-canonical run or a student compared across compositions on purpose. The caller then takes responsibility for the energies being comparable.
- Raises:
ValueError – If
betafalls outside[0, 1]ortemperatureis not positive. Also if the batch’s graphs (every rank’s shard of it, under data parallelism) do not all hold the same number of atoms. That check runs only whencheck_one_systemisTrueandnum_nodes_per_graphmetadata reaches the term, which a direct call does not supply.RuntimeError – If
world_batch=Trueand no process group is initialized when the term is evaluated.
Examples
>>> import torch >>> from nvalchemi.training.distillation import BoltzmannMatchingLoss >>> loss_fn = BoltzmannMatchingLoss(beta=1.0) >>> pred = torch.tensor([[0.0], [0.0]]) >>> target = torch.tensor([[0.0], [0.0]]) >>> loss_fn(pred, target) tensor(0.)
Notes
The uniform student weights hold only for a batch the student itself generated.
DistillationStrategytherefore requireson_policyand refuses the term on the validation side. It also warns whenreplay_ratiomixes reference frames in or when the replay buffer is unbounded. A uniform draw over a buffer that never retires frames is a draw over every policy the run has had, andreplay_capacitybounds that staleness. As in the usual on-policy approximation, the dependence of the sampling distribution on the student’s parameters is not differentiated. Equal atom counts are checked (on the gathered world batch, under data parallelism), but they are necessary rather than sufficient. Seed the run with replicas of one structure, and turncheck_one_systemoff only where the composition is meant to vary.Under data parallelism every rank holds a shard of one world batch. The reduced energies are gathered across ranks with an autograd-aware all-gather, and the softmax is normalized over the world batch. Every rank therefore reports the world loss, and the gradient the data-parallel mean produces is the world loss’s own. The gather is a collective, so every rank has to reach the term on every step. Without a process group, or with one rank, the local batch is the world batch.
world_batchmakes the gather decision explicit.A batch is one Monte Carlo sample of the two distributions. A single graph reports
0.0, a handful of graphs gives a high-variance signal, and the self-normalized weights are biased at any finite batch size, so pair this term with a pointwise one. The forward direction is bounded by \(\log B\), and its gradient vanishes once the softmax saturates, as it does for a student whose error spreads over more than a few \(k_\mathrm{B}T\).beta=0can therefore read as converged while the student is far off. Holdbetaat0.5or above until the student is within a couple of \(k_\mathrm{B}T\). Either direction’s gradient per configuration is bounded by \(1/k_\mathrm{B}T\), about 39 eV^-1 at 300 K. That bound is one to two orders of magnitude above a pointwise energy term’s, so weight the term accordingly.- compute_residual(pred, target, valid)[source]#
Return each graph’s reduced energy gap, zero where the graph is invalid.
The zero is selected rather than computed from pred, so a non-finite student energy cannot leak through it. The selection still keeps the result attached to pred’s autograd graph, so a batch with no valid graph backpropagates a zero update.
- Parameters:
pred (Float[Tensor, 'B 1'])
target (Float[Tensor, 'B 1'])
valid (Bool[Tensor, 'B 1'])
- Return type:
Float[Tensor, ‘B 1’]
- mask(pred, target, ctx, **kwargs)[source]#
Return one validity flag per graph, finite on both sides when checked.
- Parameters:
pred (Float[Tensor, 'B 1'])
target (Float[Tensor, 'B 1'])
ctx (ReductionContext)
kwargs (Any)
- Return type:
Bool[Tensor, ‘B 1’]
- normalize(pred, target, **kwargs)[source]#
Check the world batch is one system’s configurations, then pass the energies through.
The guard checks the set the softmax compares, which under data parallelism is the gathered world batch: with a strided deal one rank can hold replicas of one system and another rank a second system of a different size, so no shard alone fails the guard while the world batch does. Atom counts alone are compared, so a second system of the same size passes, on one rank or across ranks. Every rank reaches the collective whenever it reaches the term, and the union is the same on every rank, so the ranks either all refuse or all proceed.
- Parameters:
pred (Float[Tensor, 'B 1'])
target (Float[Tensor, 'B 1'])
kwargs (Any)
- Return type:
tuple[Float[Tensor, ‘B 1’], Float[Tensor, ‘B 1’], ReductionContext]
- reduce(residual, valid, ctx, **kwargs)[source]#
Combine the world batch’s gaps into the beta-interpolated relative entropy.
Under data parallelism each rank holds a shard of one world batch, and a softmax over the shard alone would weight a rank’s configurations against each other rather than against the whole sample. The gaps therefore travel through the differentiable gather of
all_gather_rows(), so every rank computes the same world loss. The gradient that reaches a shard’s energies is the sum of every rank’s copy of it, and the data-parallel mean over ranks turns that sum back into the world loss’s own gradient.per_sample_lossholds one entry per graph on this rank, scaled so that the mean of the entries over the world batch is the scalar loss.- Parameters:
residual (Float[Tensor, 'B 1'])
valid (Bool[Tensor, 'B 1'])
ctx (ReductionContext)
kwargs (Any)
- Return type:
- property thermal_energy: float#
Thermal energy
k_B Tin eV, the unit by which energies are reduced.