cone_project_spd

hypercoil.functional.semidefinite.cone_project_spd(input: Tensor, reference: Tensor, psi: float = 0, key: Tensor | None = None, recondition: Literal['eigenspaces', 'convexcombination'] = 'eigenspaces', fill_nans: bool = True, truncate_eigenvalues: bool = False) → Tensor

Project a batch of symmetric matrices from a tangent subspace into the positive semidefinite cone.

Given a tangency point \(\Omega\), each input \(\vec{\Theta}\) is projected as:

\(\Theta = \Omega^{1/2} \exp \vec{\Theta} \Omega^{1/2}\)

where \(\Omega^{1/2}\) denotes the matrix square root of \(\Omega\) and \(\exp\) denotes the matrix-argument exponential.

Warning

If the tangency point is not in the positive semidefinite cone, the result is undefined unless reconditioning is used. If reconditioning is necessary, however, cone_project_spd is not guaranteed to be a well-formed inverse of tangent_project_spd.

Dimension:

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

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

Reference : \((*, D, D)\)

As above.

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

As above.

Parameters:

inputTensor

Batch of symmetric positive definite matrices to project into the tangent subspace.

referenceTensor

Point of tangency. This is an element of the positive semidefinite cone at which the projection occurs. It should be representative of the sample being projected (for instance, some form of mean).

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:

Tensor

Batch of matrices transformed via projection into the positive semidefinite cone.

See also

tangent_project_spd

The inverse projection, into a tangent subspace.