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).\]

beta interpolates 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 is NaN or infinite are dropped from the distribution. Otherwise one non-finite student energy would poison every weight, and through the cross-rank gather (see world_batch) it would reach every rank’s softmax. False skips 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. None gathers whenever a process group with more than one rank is initialized. True always gathers and refuses to run without a process group. False reduces 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_object collective 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 beta falls outside [0, 1] or temperature is 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 when check_one_system is True and num_nodes_per_graph metadata reaches the term, which a direct call does not supply.

  • RuntimeError – If world_batch=True and 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. DistillationStrategy therefore requires on_policy and refuses the term on the validation side. It also warns when replay_ratio mixes 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, and replay_capacity bounds 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 turn check_one_system off 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_batch makes 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=0 can therefore read as converged while the student is far off. Hold beta at 0.5 or 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’]

extra_repr()[source]#

Human-readable hyperparameter summary for nn.Module’s repr.

Return type:

str

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_loss holds 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:

Tensor

property thermal_energy: float#

Thermal energy k_B T in eV, the unit by which energies are reduced.