Skip to content

Real-space losses

Real-space losses measure the difference between functions sampled on matching grids. Uniform-grid losses weight each point by its volume element; quadrature losses use the supplied integration weights.

The MAE and MSE losses return integrated absolute or squared errors for each sample and sum over additional value components. Mean reduction averages these sample integrals without dividing by volume, total quadrature weight, or component count. The corresponding physical objects are described under Grids and volumetric quantities.

Uniform grids

uniform_volumetric_mae_loss

uniform_volumetric_mae_loss(
    input: UniformVolumetricData,
    target: UniformVolumetricData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return the integrated L1 error on each uniform grid.

For sample \(b\),

\[ \ell_b = \Delta V^{(b)}\sum_{p,c} \left|\widehat x^{(b)}_{pc}-x^{(b)}_{pc}\right|, \qquad \Delta V^{(b)}=\left|\det\mathsf H^{(b)}\right|. \]

The rows of \(\mathsf H^{(b)}\) are the grid step vectors. Additional value components are summed as part of the L1 norm. reduction="mean" averages the B integrated sample losses; it does not divide by grid volume or component count.

Parameters:

  • input (UniformVolumetricData) –

    values_real: [sum(num_values), *extra_shape]. num_values: [B]. step_vectors: [B, 3, 3].

  • target (UniformVolumetricData) –

    Target data with the same grid layout and field shapes as input.

  • reduction (_Reduction, default: 'mean' ) –

    "none" returns integrated sample losses with shape [B]; "mean" averages them; "sum" sums them.

Returns:

  • Tensor –

    Loss tensor with the shape determined by reduction.

uniform_volumetric_mse_loss

uniform_volumetric_mse_loss(
    input: UniformVolumetricData,
    target: UniformVolumetricData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return the integrated squared L2 error on each uniform grid.

For sample \(b\),

\[ \ell_b = \Delta V^{(b)}\sum_{p,c} \left(\widehat x^{(b)}_{pc}-x^{(b)}_{pc}\right)^2, \qquad \Delta V^{(b)}=\left|\det\mathsf H^{(b)}\right|. \]

The rows of \(\mathsf H^{(b)}\) are the grid step vectors. Additional value components are summed as part of the squared L2 norm. reduction="mean" averages the B integrated sample losses; it does not divide by grid volume or component count. No factor of \(1/2\) is applied.

Parameters:

  • input (UniformVolumetricData) –

    values_real: [sum(num_values), *extra_shape]. num_values: [B]. step_vectors: [B, 3, 3].

  • target (UniformVolumetricData) –

    Target data with the same grid layout and field shapes as input.

  • reduction (_Reduction, default: 'mean' ) –

    "none" returns integrated sample losses with shape [B]; "mean" averages them; "sum" sums them.

Returns:

  • Tensor –

    Loss tensor with the shape determined by reduction.

Scalar-density NMAE

For matching uniform grids, NMAE is sum(abs(prediction-reference)) / sum(reference) for each structure; its volume element cancels. The reference is the complete scalar density, including any baseline. The signed reference integral must be positive, although individual reference grid values may be negative. There is no epsilon adjustment. NMAE is dimensionless; multiply by 100 for percent. reduction="none" is suitable for exact sample-weighted aggregation with MeanMetric(values.sum(), len(values)).

uniform_volumetric_nmae_loss

uniform_volumetric_nmae_loss(
    input: UniformVolumetricData,
    target: UniformVolumetricData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return dimensionless density NMAE on matching uniform grids.

Each sample contributes sum(abs(prediction-reference)) / sum(reference). Its uniform volume element cancels. The denominator is the signed integral of the full reference scalar density, including any fixed baseline, and must be positive; local negative reference values are allowed. No epsilon or absolute value is applied to the denominator.

Values have shape [sum(num_values)] or [sum(num_values), 1]. A separate magnetization component is not part of this scalar-density metric. reduction="none" returns one value per structure; "mean" weights structures equally. Multiply by 100 outside this function for percentages.

Quadrature grids

quadrature_volumetric_mae_loss

quadrature_volumetric_mae_loss(
    input: QuadratureVolumetricData,
    target: QuadratureVolumetricData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return the quadrature-integrated L1 error of each sample.

For sample \(b\),

\[ \ell_b = \sum_{p,c}w^{(b)}_p \left|\widehat x^{(b)}_{pc}-x^{(b)}_{pc}\right|. \]

The quadrature weights are taken from input and should be nonnegative. Additional value components are summed as part of the L1 norm. reduction="mean" averages the B integrated sample losses; it does not divide by the sum of weights or component count.

Parameters:

  • input (QuadratureVolumetricData) –

    values_real: [sum(num_values), *extra_shape]. num_values: [B]. weights: [sum(num_values)].

  • target (QuadratureVolumetricData) –

    Target data with the same grid layout and field shapes as input.

  • reduction (_Reduction, default: 'mean' ) –

    "none" returns integrated sample losses with shape [B]; "mean" averages them; "sum" sums them.

Returns:

  • Tensor –

    Loss tensor with the shape determined by reduction.

quadrature_volumetric_mse_loss

quadrature_volumetric_mse_loss(
    input: QuadratureVolumetricData,
    target: QuadratureVolumetricData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return the quadrature-integrated squared L2 error of each sample.

For sample \(b\),

\[ \ell_b = \sum_{p,c}w^{(b)}_p \left(\widehat x^{(b)}_{pc}-x^{(b)}_{pc}\right)^2. \]

The quadrature weights are taken from input and should be nonnegative. Additional value components are summed as part of the squared L2 norm. reduction="mean" averages the B integrated sample losses; it does not divide by the sum of weights or component count. No factor of \(1/2\) is applied.

Parameters:

  • input (QuadratureVolumetricData) –

    values_real: [sum(num_values), *extra_shape]. num_values: [B]. weights: [sum(num_values)].

  • target (QuadratureVolumetricData) –

    Target data with the same grid layout and field shapes as input.

  • reduction (_Reduction, default: 'mean' ) –

    "none" returns integrated sample losses with shape [B]; "mean" averages them; "sum" sums them.

Returns:

  • Tensor –

    Loss tensor with the shape determined by reduction.