torch.symeig

torch.symeig(input, eigenvectors=False, upper=True, *, out=None)

This function returns eigenvalues and eigenvectors of a real symmetric or complex Hermitian matrix input or a batch thereof, represented by a namedtuple (eigenvalues, eigenvectors).

This function calculates all eigenvalues (and vectors) of input such that $\text{input} = V \text{diag}(e) V^T$.

The boolean argument eigenvectors defines computation of both eigenvectors and eigenvalues or eigenvalues only.

If it is False, only eigenvalues are computed. If it is True, both eigenvalues and eigenvectors are computed.

Since the input matrix input is supposed to be symmetric or Hermitian, only the upper triangular portion is used by default.

If upper is False, then lower triangular portion is used.

Warning

torch.symeig() is deprecated in favor of torch.linalg.eigh() and will be removed in a future PyTorch release. The default behavior has changed from using the upper triangular portion of the matrix by default to using the lower triangular portion.

L, _ = torch.symeig(A, upper=upper) should be replaced with

UPLO = "U" if upper else "L"
L = torch.linalg.eigvalsh(A, UPLO=UPLO)

L, V = torch.symeig(A, eigenvectors=True, upper=upper) should be replaced with

UPLO = "U" if upper else "L"
L, V = torch.linalg.eigh(A, UPLO=UPLO)

Note

The eigenvalues are returned in ascending order. If input is a batch of matrices, then the eigenvalues of each matrix in the batch is returned in ascending order.

Note

Irrespective of the original strides, the returned matrix V will be transposed, i.e. with strides V.contiguous().transpose(-1, -2).stride().

Warning

Extra care needs to be taken when backward through outputs. Such operation is only stable when all eigenvalues are distinct and becomes less stable the smaller $\min_{i \neq j} |\lambda_i - \lambda_j|$ is.

Parameters

• input (Tensor) – the input tensor of size $(*, n, n)$ where * is zero or more batch dimensions consisting of symmetric or Hermitian matrices.

• eigenvectors (bool, optional) – controls whether eigenvectors have to be computed

• upper (boolean, optional) – controls whether to consider upper-triangular or lower-triangular region

Keyword Arguments

out (tuple, optional) – the output tuple of (Tensor, Tensor)

Returns

A namedtuple (eigenvalues, eigenvectors) containing

• eigenvalues (Tensor): Shape $(*, m)$. The eigenvalues in ascending order.

• eigenvectors (Tensor): Shape $(*, m, m)$. If eigenvectors=False, it’s an empty tensor. Otherwise, this tensor contains the orthonormal eigenvectors of the input.

Return type

(Tensor, Tensor)

Examples:

>>> a = torch.randn(5, 5)
>>> a = a + a.t()  # To make a symmetric
>>> a
tensor([[-5.7827,  4.4559, -0.2344, -1.7123, -1.8330],
        [ 4.4559,  1.4250, -2.8636, -3.2100, -0.1798],
        [-0.2344, -2.8636,  1.7112, -5.5785,  7.1988],
        [-1.7123, -3.2100, -5.5785, -2.6227,  3.1036],
        [-1.8330, -0.1798,  7.1988,  3.1036, -5.1453]])
>>> e, v = torch.symeig(a, eigenvectors=True)
>>> e
tensor([-13.7012,  -7.7497,  -2.3163,   5.2477,   8.1050])
>>> v
tensor([[ 0.1643,  0.9034, -0.0291,  0.3508,  0.1817],
        [-0.2417, -0.3071, -0.5081,  0.6534,  0.4026],
        [-0.5176,  0.1223, -0.0220,  0.3295, -0.7798],
        [-0.4850,  0.2695, -0.5773, -0.5840,  0.1337],
        [ 0.6415, -0.0447, -0.6381, -0.0193, -0.4230]])
>>> a_big = torch.randn(5, 2, 2)
>>> a_big = a_big + a_big.transpose(-2, -1)  # To make a_big symmetric
>>> e, v = a_big.symeig(eigenvectors=True)
>>> torch.allclose(torch.matmul(v, torch.matmul(e.diag_embed(), v.transpose(-2, -1))), a_big)
True