nvalchemi.training.losses.reductions.graph_balanced_mean#

nvalchemi.training.losses.reductions.graph_balanced_mean(residual, valid, batch_idx, num_graphs, *, loss_name)[source]#

Mean over graphs of each graph’s mean valid residual.

For per-node residuals \(\rho_{ia}\) and validity weights \(w_{ia}\) this returns

\[L = \frac{1}{B} \sum_{i=1}^{B} \frac{\sum_a \rho_{ia}}{\max\left(\sum_a w_{ia}, 1\right)},\]

so every graph contributes equally regardless of its size and a graph with no valid node contributes 0.0. Trailing dims of residual and valid are summed into the node before the scatter, so a (V, 3) squared force error with a (V, 3) component mask divides by the number of valid components rather than of valid atoms. Both tensors are promoted to at least float32 first and the per-graph sums stay at that width (see per_graph_sum()).

Parameters:
  • residual (Float[torch.Tensor, "V ..."]) – Per-node residual, already zeroed where valid is false.

  • valid (Num[torch.Tensor, "V ..."]) – Per-node validity mask or weights, same shape as residual.

  • batch_idx (BatchIndices | None) – Node-to-graph assignment; None is refused.

  • num_graphs (int | None) – Number of graphs in the batch; None is refused.

  • loss_name (str) – Name of the calling loss, used in the metadata error.

Returns:

The scalar loss and the per-graph means it averages, the latter suitable for a loss term’s per_sample_loss.

Return type:

tuple[Float[torch.Tensor, “”], Float[torch.Tensor, “B”]]

Raises:

ValueError – If batch_idx or num_graphs is None, or if the leading dim of residual does not match batch_idx.