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 ofresidualandvalidare 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 (seeper_graph_sum()).- Parameters:
residual (Float[torch.Tensor, "V ..."]) – Per-node residual, already zeroed where
validis false.valid (Num[torch.Tensor, "V ..."]) – Per-node validity mask or weights, same shape as
residual.batch_idx (BatchIndices | None) – Node-to-graph assignment;
Noneis refused.num_graphs (int | None) – Number of graphs in the batch;
Noneis 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_idxornum_graphsisNone, or if the leading dim ofresidualdoes not matchbatch_idx.