Orbital-vector losses
Orbital vectors can be compared through their coefficients or through a quadratic form that accounts for the basis. Componentwise MAE and MSE average over orbital values within each sample. Quadratic losses sum the error defined by a supplied matrix or upper-triangular factor, then reduce across samples.
When the matrix is the basis overlap, the quadratic form measures the integrated squared error of the represented function. The upper-factor form gives the same quantity when the overlap equals the factor's transpose times the factor. These losses consume the packed orbital vectors used by orbital decoders.
Coefficient errors
Componentwise MAE is generally not invariant under rotations of non-scalar orbital representations.
orb_vector_mae_loss
Return the sample-balanced componentwise MAE of orbital vectors.
For sample \(b\),
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
Return the sample-balanced componentwise MSE of orbital vectors.
For sample \(b\),
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.
Quadratic errors
The matrix or factor is treated as fixed data. The orbital dimension is retained in the quadratic form rather than averaged out.
orb_vector_quadratic_loss optionally adds diagonal_shift times the summed squared coefficient error in each sample, equivalent to replacing the supplied symmetric matrix \(\mathsf S\) with \(\mathsf S+\eta\mathsf I\). Supplying positive num_atoms with shape [B] divides the entire shifted quadratic form by each sample's atom count before reduction across samples. The defaults retain the unshifted, unnormalized quadratic form; atom normalization does not average over orbital values or trailing components.
orb_vector_quadratic_loss
orb_vector_quadratic_loss(
input: OrbData,
target: OrbData,
symm_orb_matrix: OrbData,
*,
diagonal_shift: float = 0.0,
num_atoms: Tensor | None = None,
reduction: _Reduction = "mean",
) -> Tensor
Return a symmetric quadratic orbital-vector error.
Write \(\boldsymbol\delta_c^{(b)}=\widehat{\boldsymbol d}_c^{(b)}- \boldsymbol d_c^{(b)}\). For sample \(b\),
\(\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. \(\eta\) is diagonal_shift, equivalent to using
\(\mathsf S+\eta\mathsf I\) without changing the packed matrix.
\(Z_b=N_{\mathrm{atoms}}^{(b)}\) when num_atoms is supplied, otherwise
\(Z_b=1\). Positive semidefiniteness of the shifted matrix 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]. -
diagonal_shift(float, default:0.0) –Coefficient of the summed squared coefficient error. Defaults to zero, retaining the supplied quadratic form.
-
num_atoms(Tensor | None, default:None) –Positive atom counts with shape
[B], on the input device. When supplied, divide each sample's entire shifted quadratic form by its atom count before applyingreduction. -
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\),
\(\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.