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

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.

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

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.