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\),
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\),
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\),
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\),
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.