spd#

hypercoil.functional.matrix.spd(X: Tensor, eps: float = 1e-06, method: Literal['eig', 'svd'] = 'eig') → Tensor[source]#

Impose symmetric positive definiteness on a tensor block.

Each input matrix is first made symmetric. Next, the symmetrised inputs are decomposed via diagonalisation or SVD. If the inputs are diagonalised, the smallest eigenvalue is identified, and a scaled identity matrix is added to the input such that the smallest eigenvalue of the resulting matrix is no smaller than a specified threshold. If the inputs are decomposed via SVD, then the matrix is reconstituted from the left singular vectors (which are in theory identical to the right singular vectors up to sign for a symmetric matrix) and the absolute values of the eigenvalues. Thus, the maximum reconstruction error is in theory the minimum threshold for diagonalisation and the absolute value of the smallest negative eigenvalue for SVD.

Parameters:
XTensor

Input to be made positive definite.

epsfloat

Minimum threshold for the smallest eigenvalue identified in diagonal eigendecomposition. If diagonalisation is used to impose positive semidefiniteness, then this will be the minimum possible eigenvalue of the output. If SVD is used to impose positive semidefiniteness, then this is unused.

method'eig' or 'svd'

Method used to ensure that all eigenvalues are positive.

  • eig denotes that the input matrices are symmetrised and then diagonalised. The method returns the symmetrised sum of the input and an identity matrix scaled to guarantee no eigenvalue is smaller than eps.

  • svd denotes that the input matrices are decomposed via singular value decomposition after symmetrisation. The method returns a recomposition of the matrix that treats the left singular vectors and singular values output from SVD as though they were outputs of diagonalisation, thereby guaranteeing that no eigenvalue is smaller than the least absolute value among all input eigenvalues. Note that this margin is occasionally insufficient to avoid numerical error if the same matrix is again decomposed.

Returns:
outputTensor

Input modified so that each slice is symmetric and positive definite.