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 to 0.0 on either branch.

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.

  • 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 None reads it from batch.

  • num_graphs (int | None, optional) – Number of graphs in the batch, read only when graph_balanced. Default None reads it from batch.

  • batch (Any | None, optional) – Object carrying batch_idx and num_graphs for the keywords left None, as the batch= keyword a composed loss forwards. Default None.

  • 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; None otherwise.

Return type:

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

Raises:

ValueError – If graph_balanced and neither the keywords nor batch supply batch_idx and num_graphs, or if the leading dim of residual does not match batch_idx.