elfes.modules.losses

Loss functions for Cartesian, orbital, and block-sparse quantities.

block_sparse_mae_loss

block_sparse_mae_loss(
    input: BlockSparseOrbData,
    target: BlockSparseOrbData,
    *,
    blocks: _BlockSelection = "all",
    reduction: _Reduction = "mean",
) -> Tensor

Return the mean absolute error of each block-sparse orbital matrix.

\[ \ell = \frac{1}{N_c\sum_{q\in\mathcal B_s} N_{\mathrm{orb},i_q}N_{\mathrm{orb},j_q}} \sum_{q\in\mathcal B_s}\sum_{\mu,\nu,c} \left|\widehat X^q_{\mu\nu c} - X^q_{\mu\nu c}\right|. \]

The set \(\mathcal B_s\) contains all stored blocks by default. With blocks="onsite", it contains blocks whose row and column atoms are equal and whose cell shift is zero; blocks="offsite" selects the complement. For complex values, the absolute value is the complex modulus. Here, \(N_c\) is the number of additional value components. Each stored value has equal weight within one sample, while reduction="mean" gives every sample equal weight. For Hermitian half-storage, this loss measures the stored values; it does not reconstruct or double-count the omitted conjugate blocks. Each sample must contain at least one selected matrix element.

Note

This elementwise L1 error is generally not invariant under orbital-basis rotations.

Parameters:

input
(BlockSparseOrbData) –

values_real: [sum(num_values), *extra_shape]. values_imag: Optional [sum(num_values), *extra_shape]. num_values: [B].
target
(BlockSparseOrbData) –

Target data with the same stored block layout and field shapes as input.
blocks
(_BlockSelection, default: 'all' ) –

Stored blocks included in the loss.
reduction
(_Reduction, default: 'mean' ) –

"none" returns one value per sample; "mean" or "sum" reduces those sample losses.

block_sparse_mse_loss

block_sparse_mse_loss(
    input: BlockSparseOrbData,
    target: BlockSparseOrbData,
    *,
    blocks: _BlockSelection = "all",
    reduction: _Reduction = "mean",
) -> Tensor

Return the mean squared error of each block-sparse orbital matrix.

\[ \ell = \frac{1}{N_c\sum_{q\in\mathcal B_s} N_{\mathrm{orb},i_q}N_{\mathrm{orb},j_q}} \sum_{q\in\mathcal B_s}\sum_{\mu,\nu,c} \left|\widehat X^q_{\mu\nu c} - X^q_{\mu\nu c}\right|^2. \]

The set \(\mathcal B_s\) contains all stored blocks by default. With blocks="onsite", it contains blocks whose row and column atoms are equal and whose cell shift is zero; blocks="offsite" selects the complement. For complex values, the squared absolute value is the sum of the squared real and imaginary errors. Here, \(N_c\) is the number of additional value components. Each stored value has equal weight within one sample, while reduction="mean" gives every sample equal weight. For Hermitian half-storage, this loss measures the stored values; it does not reconstruct or double-count the omitted conjugate blocks. No factor of \(1/2\) is applied. Each sample must contain at least one selected matrix element.

Parameters:

input
(BlockSparseOrbData) –

values_real: [sum(num_values), *extra_shape]. values_imag: Optional [sum(num_values), *extra_shape]. num_values: [B].
target
(BlockSparseOrbData) –

Target data with the same stored block layout and field shapes as input.
blocks
(_BlockSelection, default: 'all' ) –

Stored blocks included in the loss.
reduction
(_Reduction, default: 'mean' ) –

"none" returns one value per sample; "mean" or "sum" reduces those sample losses.

block_sparse_orthogonalized_mse_loss

block_sparse_orthogonalized_mse_loss(
    input: BlockSparseOrbData,
    target: BlockSparseOrbData,
    overlap: BlockSparseOrbData,
    orb_counts: Tensor,
    batch_ptr: Tensor,
    kpoints: Tensor,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return the MSE between Cholesky-orthogonalized Bloch matrices.

\[ \ell = \frac{1}{N_k N_{\mathrm{orb}}^2 N_c} \sum_{\mathbf k\in\mathcal K}\sum_c \left\| U(\mathbf k)^{-\dagger} \Delta X_c(\mathbf k) U(\mathbf k)^{-1} \right\|_F^2, \qquad S(\mathbf k)=U(\mathbf k)^\dagger U(\mathbf k). \]

Here, \(\Delta X(\mathbf k)\) is the Bloch transform of input - target, and \(S(\mathbf k)\) is the Bloch transform of overlap. Thus the transformed difference equals the difference between input and target after both are mapped to the same orthonormal basis. The overlap must be positive-definite at every k-point; failed Cholesky factorization is reported by PyTorch. Samples are grouped by their exact orbital dimension, and the loss does not pad matrices.

Here, \(N_{\mathrm{orb}}\) is the sample's total number of orbitals, \(N_k=|\mathcal K|\), and \(N_c\) is the number of additional value components. Every dense matrix entry, k-point, and additional component has equal weight within one sample; reduction="mean" gives every sample equal weight. No factor of \(1/2\) is applied.

Parameters:

input
(BlockSparseOrbData) –

values_real: [sum(num_values), *extra_shape]. values_imag: Optional [sum(num_values), *extra_shape]. num_values: [B].
target
(BlockSparseOrbData) –

Target data with the same stored block layout and field shapes as input.
overlap
(BlockSparseOrbData) –

Hermitian positive-definite overlap matrix with the same samples and no additional value axes.
orb_counts
(Tensor) –

Number of orbitals on every atom, with shape [N_atom].
batch_ptr
(Tensor) –

Sample boundaries on the atom axis, with shape [B+1].
kpoints
(Tensor) –

One shared fractional k-point with shape [3] or multiple shared k-points with shape [N_kpoint, 3].
reduction
(_Reduction, default: 'mean' ) –

"none" returns one value per sample; "mean" or "sum" reduces those sample losses.

atom_mae_loss

atom_mae_loss(
    input: Tensor,
    target: Tensor,
    num_atoms: Tensor,
    *,
    mean_over: _MeanOver = "atoms",
    reduction: _Reduction = "mean",
) -> Tensor

Return the componentwise absolute error of packed atom-level values.

The elementary errors are

\[ \ell_{ic} = \left|x_{ic} - y_{ic}\right|. \]

With reduction="mean" and mean_over="atoms", every atom and value component in the batch has equal weight:

\[ L_{\mathrm{atoms}} = \frac{1}{N_{\mathrm{atom}}C} \sum_{i,c}\ell_{ic}. \]

With mean_over="samples", every sample instead has equal weight, independently of its number of atoms:

\[ L_{\mathrm{samples}} = \frac{1}{B}\sum_b \frac{1}{N_{\mathrm{atom}}^{(b)}C} \sum_{i\in b,c}\ell_{ic}. \]

Here \(C\) is the product of value_shape; \(C=1\) for one scalar per atom. mean_over affects only the "mean" reduction. "none" returns every elementary error and "sum" returns their unnormalized sum. This componentwise loss is generally not invariant under rotations when the value axes contain Cartesian vectors or tensors.

Parameters:

input
(Tensor) –

Predicted packed atom-level values with shape [N_atom, *value_shape].
target
(Tensor) –

Target values with shape [N_atom, *value_shape].
num_atoms
(Tensor) –

Number of consecutive atoms in each sample, with shape [B] and sum N_atom.
mean_over
(_MeanOver, default: 'atoms' ) –

"atoms" gives every atom equal weight; "samples" gives every sample equal weight.
reduction
(_Reduction, default: 'mean' ) –

"none" returns elementary errors with shape [N_atom, *value_shape]; "mean" averages them according to mean_over; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

atom_mse_loss

atom_mse_loss(
    input: Tensor,
    target: Tensor,
    num_atoms: Tensor,
    *,
    mean_over: _MeanOver = "atoms",
    reduction: _Reduction = "mean",
) -> Tensor

Return the componentwise squared error of packed atom-level values.

The elementary errors are

\[ \ell_{ic} = \left(x_{ic} - y_{ic}\right)^2. \]

With reduction="mean" and mean_over="atoms", every atom and value component in the batch has equal weight:

\[ L_{\mathrm{atoms}} = \frac{1}{N_{\mathrm{atom}}C} \sum_{i,c}\ell_{ic}. \]

With mean_over="samples", every sample instead has equal weight:

\[ L_{\mathrm{samples}} = \frac{1}{B}\sum_b \frac{1}{N_{\mathrm{atom}}^{(b)}C} \sum_{i\in b,c}\ell_{ic}. \]

Here \(C\) is the product of value_shape; \(C=1\) for one scalar per atom. mean_over affects only the "mean" reduction. "none" returns every elementary error and "sum" returns their unnormalized sum. No factor of \(1/2\) is applied.

Parameters:

input
(Tensor) –

Predicted packed atom-level values with shape [N_atom, *value_shape].
target
(Tensor) –

Target values with shape [N_atom, *value_shape].
num_atoms
(Tensor) –

Number of consecutive atoms in each sample, with shape [B] and sum N_atom.
mean_over
(_MeanOver, default: 'atoms' ) –

"atoms" gives every atom equal weight; "samples" gives every sample equal weight.
reduction
(_Reduction, default: 'mean' ) –

"none" returns elementary errors with shape [N_atom, *value_shape]; "mean" averages them according to mean_over; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

atom_vector_norm_loss

atom_vector_norm_loss(
    input: Tensor,
    target: Tensor,
    num_atoms: Tensor,
    *,
    mean_over: _MeanOver = "atoms",
    reduction: _Reduction = "mean",
) -> Tensor

Return Euclidean errors of packed atom-level Cartesian vectors.

The final axis is interpreted as one Cartesian vector and is consumed by the Euclidean norm. The elementary errors are

\[ \ell_{ic} = \sqrt{\sum_{\alpha=1}^{3} \left(x_{ic\alpha} - y_{ic\alpha}\right)^2}. \]

With reduction="mean" and mean_over="atoms", every atom and extra vector in the batch has equal weight:

\[ L_{\mathrm{atoms}} = \frac{1}{N_{\mathrm{atom}}C} \sum_{i,c}\ell_{ic}. \]

With mean_over="samples", every sample instead has equal weight:

\[ L_{\mathrm{samples}} = \frac{1}{B}\sum_b \frac{1}{N_{\mathrm{atom}}^{(b)}C} \sum_{i\in b,c}\ell_{ic}. \]

Here \(C\) is the product of extra_shape; \(C=1\) for one vector per atom. mean_over affects only the "mean" reduction. "none" returns every vector error and "sum" returns their unnormalized sum. Each elementary error is invariant under simultaneous orthogonal transformations of input and target.

Parameters:

input
(Tensor) –

Predicted packed atom-level Cartesian vectors with shape [N_atom, *extra_shape, 3].
target
(Tensor) –

Target vectors with shape [N_atom, *extra_shape, 3].
num_atoms
(Tensor) –

Number of consecutive atoms in each sample, with shape [B] and sum N_atom.
mean_over
(_MeanOver, default: 'atoms' ) –

"atoms" gives every atom equal weight; "samples" gives every sample equal weight.
reduction
(_Reduction, default: 'mean' ) –

"none" returns vector errors with shape [N_atom, *extra_shape]; "mean" averages them according to mean_over; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

mae_loss

mae_loss(input: Tensor, target: Tensor, *, reduction: _Reduction = 'mean') -> Tensor

Return the componentwise absolute error of sample-level values.

With reduction="none", the elementary errors are

\[ \ell_{bc} = \left|x_{bc} - y_{bc}\right|. \]

reduction="mean" returns

\[ L = \frac{1}{BC}\sum_{b,c}\ell_{bc}, \]

where \(C\) is the product of value_shape; \(C=1\) for one scalar per sample. reduction="sum" returns the corresponding unnormalized sum. Because the absolute errors are taken component by component, this loss is generally not invariant under rotations when the value axes contain Cartesian vectors or tensors.

Parameters:

input
(Tensor) –

Predicted sample-level values with shape [B, *value_shape].
target
(Tensor) –

Target values with shape [B, *value_shape].
reduction
(_Reduction, default: 'mean' ) –

"none" returns elementary errors with shape [B, *value_shape]; "mean" averages all elementary errors; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

mse_loss

mse_loss(input: Tensor, target: Tensor, *, reduction: _Reduction = 'mean') -> Tensor

Return the componentwise squared error of sample-level values.

With reduction="none", the elementary errors are

\[ \ell_{bc} = \left(x_{bc} - y_{bc}\right)^2. \]

reduction="mean" returns

\[ L = \frac{1}{BC}\sum_{b,c}\ell_{bc}, \]

where \(C\) is the product of value_shape; \(C=1\) for one scalar per sample. reduction="sum" returns the corresponding unnormalized sum. No factor of \(1/2\) is applied.

Parameters:

input
(Tensor) –

Predicted sample-level values with shape [B, *value_shape].
target
(Tensor) –

Target values with shape [B, *value_shape].
reduction
(_Reduction, default: 'mean' ) –

"none" returns elementary errors with shape [B, *value_shape]; "mean" averages all elementary errors; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

per_atom_mae_loss

per_atom_mae_loss(
    input: Tensor, target: Tensor, num_atoms: Tensor, *, reduction: _Reduction = "mean"
) -> Tensor

Return the per-atom absolute error of extensive sample-level values.

This loss is for an extensive quantity such as total energy: the residual is divided by the number of atoms in its sample before the absolute error is formed. With reduction="none",

\[ \ell_{bc} = \left|\frac{x_{bc} - y_{bc}} {N_{\mathrm{atom}}^{(b)}}\right|. \]

reduction="mean" averages these errors over all samples and value components. For one scalar per sample,

\[ L = \frac{1}{B}\sum_b \frac{\left|x_b-y_b\right|}{N_{\mathrm{atom}}^{(b)}}. \]

This differs from an atom-level loss: input and target have one row per sample, not one row per atom.

Parameters:

input
(Tensor) –

Predicted extensive sample-level values with shape [B, *value_shape].
target
(Tensor) –

Target values with shape [B, *value_shape].
num_atoms
(Tensor) –

Number of atoms in each sample, with shape [B].
reduction
(_Reduction, default: 'mean' ) –

"none" returns per-atom elementary errors with shape [B, *value_shape]; "mean" averages them; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

per_atom_mse_loss

per_atom_mse_loss(
    input: Tensor, target: Tensor, num_atoms: Tensor, *, reduction: _Reduction = "mean"
) -> Tensor

Return the per-atom squared error of extensive sample-level values.

This loss is for an extensive quantity such as total energy: the residual is divided by the number of atoms in its sample before it is squared. With reduction="none",

\[ \ell_{bc} = \left(\frac{x_{bc} - y_{bc}} {N_{\mathrm{atom}}^{(b)}}\right)^2. \]

reduction="mean" averages these errors over all samples and value components. For one scalar per sample,

\[ L = \frac{1}{B}\sum_b \left(\frac{x_b-y_b}{N_{\mathrm{atom}}^{(b)}}\right)^2. \]

The division therefore contributes \((N_{\mathrm{atom}}^{(b)})^{-2}\), not \((N_{\mathrm{atom}}^{(b)})^{-1}\), to the squared loss. No factor of \(1/2\) is applied.

Parameters:

input
(Tensor) –

Predicted extensive sample-level values with shape [B, *value_shape].
target
(Tensor) –

Target values with shape [B, *value_shape].
num_atoms
(Tensor) –

Number of atoms in each sample, with shape [B].
reduction
(_Reduction, default: 'mean' ) –

"none" returns per-atom elementary errors with shape [B, *value_shape]; "mean" averages them; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

vector_norm_loss

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

Return Euclidean errors of sample-level Cartesian vectors.

The final axis is interpreted as one Cartesian vector and is consumed by the Euclidean norm. With reduction="none", the elementary errors are

\[ \ell_{bc} = \sqrt{\sum_{\alpha=1}^{3} \left(x_{bc\alpha} - y_{bc\alpha}\right)^2}. \]

reduction="mean" returns

\[ L = \frac{1}{BC}\sum_{b,c}\ell_{bc}, \]

where \(C\) is the product of extra_shape; \(C=1\) for one vector per sample. reduction="sum" returns the corresponding unnormalized sum. Unlike componentwise MAE, the elementary vector errors are invariant under simultaneous orthogonal transformations of input and target.

Parameters:

input
(Tensor) –

Predicted sample-level Cartesian vectors with shape [B, *extra_shape, 3].
target
(Tensor) –

Target vectors with shape [B, *extra_shape, 3].
reduction
(_Reduction, default: 'mean' ) –

"none" returns vector errors with shape [B, *extra_shape]; "mean" averages all vector errors; "sum" sums them.

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

orb_vector_mae_loss

orb_vector_mae_loss(
    input: OrbData, target: OrbData, *, reduction: _Reduction = "mean"
) -> Tensor

Return the sample-balanced componentwise MAE of orbital vectors.

For sample \(b\),

\[ \ell_b = \frac{1}{N_{\mathrm{orb}}^{(b)}C} \sum_{\mu,c}\left|\widehat d^{(b)}_{\mu c}-d^{(b)}_{\mu c}\right|. \]

reduction="mean" averages the B sample losses, giving every sample the same weight independently of its number of orbital values. "sum" sums the sample losses. This componentwise L1 error is generally not invariant under rotations of non-scalar orbital representations.

Parameters:

input
(OrbData) –

values_real: [sum(num_values), *extra_shape]. num_values: [B].
target
(OrbData) –

Target orbital vectors with the same field shapes as input.
reduction
(_Reduction, default: 'mean' ) –

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

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

orb_vector_mse_loss

orb_vector_mse_loss(
    input: OrbData, target: OrbData, *, reduction: _Reduction = "mean"
) -> Tensor

Return the sample-balanced componentwise MSE of orbital vectors.

For sample \(b\),

\[ \ell_b = \frac{1}{N_{\mathrm{orb}}^{(b)}C} \sum_{\mu,c}\left(\widehat d^{(b)}_{\mu c}-d^{(b)}_{\mu c}\right)^2. \]

reduction="mean" averages the B sample losses, giving every sample the same weight independently of its number of orbital values. "sum" sums the sample losses. No factor of \(1/2\) is applied.

Parameters:

input
(OrbData) –

values_real: [sum(num_values), *extra_shape]. num_values: [B].
target
(OrbData) –

Target orbital vectors with the same field shapes as input.
reduction
(_Reduction, default: 'mean' ) –

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

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

orb_vector_quadratic_loss

orb_vector_quadratic_loss(
    input: OrbData,
    target: OrbData,
    symm_orb_matrix: OrbData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return a symmetric quadratic orbital-vector error.

For sample \(b\),

\[ \ell_b = \sum_{\mu,\nu,c} \left(\widehat d^{(b)}_{\mu c}-d^{(b)}_{\mu c}\right) S^{(b)}_{\mu\nu} \left(\widehat d^{(b)}_{\nu c}-d^{(b)}_{\nu c}\right). \]

\(\mathsf S^{(b)}\) is real and symmetric. symm_orb_matrix stores its upper triangle: sample \(b\) contributes \(N_{\mathrm{orb}}^{(b)}(N_{\mathrm{orb}}^{(b)}+1)/2\) values in torch.triu_indices row-major order, and the stored off-diagonal entries are reflected across the diagonal. The same matrix acts independently on every trailing component, whose quadratic errors are summed. The matrix is treated as fixed data. Positive semidefiniteness gives a nonnegative loss; this function does not test it.

The orbital dimension is not averaged out: it is part of the quadratic form. reduction acts only across the B samples, and no factor of \(1/2\) is applied.

Parameters:

input
(OrbData) –

values_real: [sum(num_values), *extra_shape]. num_values: [B].
target
(OrbData) –

Target orbital vectors with the same field shapes as input.
symm_orb_matrix
(OrbData) –

values_real: [N_matrix]. num_values: [B].
reduction
(_Reduction, default: 'mean' ) –

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

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

orb_vector_triu_mse_loss

orb_vector_triu_mse_loss(
    input: OrbData,
    target: OrbData,
    triu_orb_matrix: OrbData,
    *,
    reduction: _Reduction = "mean",
) -> Tensor

Return an orbital-vector squared error transformed by an upper factor.

For sample \(b\),

\[ \ell_b = \sum_{\mu,c}\left[ \sum_\nu U^{(b)}_{\mu\nu} \left(\widehat d^{(b)}_{\nu c}-d^{(b)}_{\nu c}\right) \right]^2. \]

\(\mathsf U^{(b)}\) is a real upper-triangular factor. triu_orb_matrix stores it in packed-upper layout: sample \(b\) contributes \(N_{\mathrm{orb}}^{(b)}(N_{\mathrm{orb}}^{(b)}+1)/2\) values in torch.triu_indices row-major order. When \(\mathsf S=\mathsf U^\mathsf T\mathsf U\), this function is mathematically equivalent to passing \(\mathsf S\) to orb_vector_quadratic_loss. The same factor acts independently on every trailing component, whose quadratic errors are summed. The factor is treated as fixed data.

The orbital dimension is not averaged out: it is part of the quadratic form. reduction acts only across the B samples, and no factor of \(1/2\) is applied.

Parameters:

input
(OrbData) –

values_real: [sum(num_values), *extra_shape]. num_values: [B].
target
(OrbData) –

Target orbital vectors with the same field shapes as input.
triu_orb_matrix
(OrbData) –

values_real: [N_factor]. num_values: [B].
reduction
(_Reduction, default: 'mean' ) –

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

Returns:

Tensor –

Loss tensor with the shape determined by reduction.

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.

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.