Skip to content

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

\[ \ell_b = \frac{1}{Z_b}\sum_c\left[ (\boldsymbol\delta_c^{(b)})^\mathsf T\mathsf S^{(b)} \boldsymbol\delta_c^{(b)} +\eta\lVert\boldsymbol\delta_c^{(b)}\rVert_2^2\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. \(\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 applying reduction.

  • 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.