symeig

xitorch.linalg.symeig(A: xitorch._core.linop.LinearOperator, neig: Optional[int] = None, mode: str = 'lowest', M: Optional[xitorch._core.linop.LinearOperator] = None, bck_options: Mapping[str, Any] = {}, method: Optional[Union[str, Callable]] = None, **fwd_options) → Tuple[torch.Tensor, torch.Tensor]

Obtain neig lowest eigenvalues and eigenvectors of a linear operator,

\[\mathbf{AX = MXE}\]

where \(\mathbf{A}, \mathbf{M}\) are linear operators, \(\mathbf{E}\) is a diagonal matrix containing the eigenvalues, and \(\mathbf{X}\) is a matrix containing the eigenvectors. This function can handle derivatives for degenerate cases by setting non-zero degen_atol and degen_rtol in the backward option using the expressions in 1.

Parameters

• A (xitorch.LinearOperator) – The linear operator object on which the eigenpairs are constructed. It must be a Hermitian linear operator with shape (*BA, q, q)

• neig (int or None) – The number of eigenpairs to be retrieved. If None, all eigenpairs are retrieved

• mode (str) – "lowest" or "uppermost"/"uppest". If "lowest", it will take the lowest neig eigenpairs. If "uppest", it will take the uppermost neig.

• M (xitorch.LinearOperator) – The transformation on the right hand side. If None, then M=I. If specified, it must be a Hermitian with shape (*BM, q, q).

• bck_options (dict) –

  Method-specific options for solve() which used in backpropagation calculation with some additional arguments for computing the backward derivatives:

  • degen_atol (float or None): Minimum absolute difference between two eigenvalues to be treated as degenerate. If None, it is torch.finfo(dtype).eps**0.6. If 0.0, no special treatment on degeneracy is applied. (default: None)

  • degen_rtol (float or None): Minimum relative difference between two eigenvalues to be treated as degenerate. If None, it is torch.finfo(dtype).eps**0.4. If 0.0, no special treatment on degeneracy is applied. (default: None)

  Note: the default values of degen_atol and degen_rtol are going to change in the future. So, for future compatibility, please specify the specific values.

• method (str or callable or None) – Method for the eigendecomposition. If None, it will choose "exacteig".

• **fwd_options – Method-specific options (see method section below).

Returns

It will return eigenvalues and eigenvectors with shapes respectively (*BAM, neig) and (*BAM, na, neig), where *BAM is the broadcasted shape of *BA and *BM.

Return type

tuple of tensors (eigenvalues, eigenvectors)

References

1

Muhammad F. Kasim, “Derivatives of partial eigendecomposition of a real symmetric matrix for degenerate cases”. arXiv:2011.04366 (2020) https://arxiv.org/abs/2011.04366

method="exacteig"

symeig(..., method="exacteig")

Eigendecomposition using explicit matrix construction. No additional option for this method.

Warning

• As this method construct the linear operators explicitly, it might requires a large memory.

method="davidson"

symeig(..., method="davidson", *, max_niter=1000, nguess=None, v_init="randn", max_addition=None, min_eps=1e-06, verbose=False)

Using Davidson method for large sparse matrix eigendecomposition 2.

Parameters

• max_niter (int) – Maximum number of iterations

• v_init (str) – Mode of the initial guess ("randn", "rand", "eye")

• max_addition (int or None) – Maximum number of new guesses to be added to the collected vectors. If None, set to neig.

• min_eps (float) – Minimum residual error to be stopped

• verbose (bool) – Option to be verbose

References

2

P. Arbenz, “Lecture Notes on Solving Large Scale Eigenvalue Problems” http://people.inf.ethz.ch/arbenz/ewp/Lnotes/chapter12.pdf