mean_geom_spd#

hypercoil.functional.semidefinite.mean_geom_spd(input: Tensor, axis: int | Sequence[int] = 0, eps: float = 1e-06, max_iter: int = 10, psi: float = 0, key: Tensor | None = None, recondition: Literal['eigenspaces', 'convexcombination'] = 'eigenspaces', fill_nans: bool = True, truncate_eigenvalues: bool = False) → Tensor[source]#

Batch-wise geometric mean of tensors in the positive semidefinite cone.

The geometric mean is computed via gradient descent along the geodesic on the manifold. In brief:

Initialisation :

  • The estimate of the mean is initialised to the Euclidean mean.

Iteration :

  • Using the working estimate of the mean as the point of tangency, the tensors are projected into a tangent space.

  • The arithmetic mean of the tensors is computed in tangent space.

  • This mean is projected back into the positive semidefinite cone using the same point of tangency. It now becomes a new working estimate of the mean and thus a new point of tangency.

Termination / convergence :

  • The algorithm terminates either when the Frobenius norm of the difference between the new estimate and the previous estimate is less than a specified threshold, or when a maximum number of iterations has been attained.

Dimension:
Input : \((N, *, D, D)\)

N denotes batch size, * denotes any number of intervening dimensions, D denotes matrix row and column dimension.

Output : \((*, D, D)\)

As above.

Parameters:
inputTensor

Batch of matrices over which the Euclidean mean is to be computed.

axisint

Axis or axes over which the mean is computed.

max_iternonnegative int

The maximum number of iterations of gradient descent to run before termination.

psifloat in [0, 1]

Conditioning factor to promote positive definiteness.

key: Tensor or None (default None)

Key for pseudo-random number generation. Required if recondition is set to 'eigenspaces' and psi is in (0, 1].

recondition'convexcombination' or 'eigenspaces' (default 'eigenspaces')

Method for reconditioning.

  • 'convexcombination' denotes that the original input will be replaced with a convex combination of the input and an identity matrix.

    \(\widetilde{X} = (1 - \psi) X + \psi I\)

    A suitable \(\psi\) can be used to ensure that all eigenvalues are positive.

  • 'eigenspaces' denotes that noise will be added to the original input along the diagonal.

    \(\widetilde{X} = X + \psi I - \xi I\)

    where each element of \(\xi\) is independently sampled uniformly from \((0, \psi)\). In addition to promoting positive definiteness, this method promotes eigenspaces with dimension 1 (no degenerate/repeated eigenvalues). Nondegeneracy of eigenvalues is required for differentiation through SVD.

fill_nansbool (default True)

Indicates that any NaNs among the transformed eigenvalues should be replaced with zeros.

truncate_eigenvaluesbool (default False)

Indicates that very small eigenvalues, which might for instance occur due to numerical errors in the decomposition, should be truncated to zero. Note that you should not do this if you wish to differentiate through this operation, or if you require the input to be positive definite. For these use cases, consider using the psi and recondition parameters.

Returns:
outputTensor

Log-Euclidean mean of the input batch.