nvalchemi.training.losses.reductions.masked_mean#
- nvalchemi.training.losses.reductions.masked_mean(residual, valid, *, graph_balanced, batch_idx=None, num_graphs=None, batch=None, loss_name='masked_mean')[source]#
Mean of a masked residual, over every valid entry or balanced over graphs.
Without graph_balanced this is the global mean: the residual summed over every entry and divided by the number of valid entries, so every atom weighs the same and a large graph weighs more than a small one. With it, the reduction is
graph_balanced_mean(), so every graph weighs the same. Both branches accumulate in at least float32, so a half-precision residual reduces to a float32 scalar, and a residual with no valid entry reduces to0.0on either branch.- 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.graph_balanced (bool) – Whether to average within each graph first and then over graphs.
batch_idx (BatchIndices | None, optional) – Node-to-graph assignment, read only when graph_balanced. Default
Nonereads it from batch.num_graphs (int | None, optional) – Number of graphs in the batch, read only when graph_balanced. Default
Nonereads it from batch.batch (Any | None, optional) – Object carrying
batch_idxandnum_graphsfor the keywords leftNone, as thebatch=keyword a composed loss forwards. DefaultNone.loss_name (str, optional) – Name of the calling loss, used in the metadata error. Default
"masked_mean".
- Returns:
The scalar loss and, when graph_balanced, the per-graph means it averages, suitable for a loss term’s
per_sample_loss;Noneotherwise.- Return type:
tuple[Float[torch.Tensor, “”], Float[torch.Tensor, “B”] | None]
- Raises:
ValueError – If graph_balanced and neither the keywords nor batch supply
batch_idxandnum_graphs, or if the leading dim ofresidualdoes not matchbatch_idx.