Shortcuts

torch.linalg.matrix_rank

torch.linalg.matrix_rank(A, tol=None, hermitian=False, *, out=None)Tensor

Computes the numerical rank of a matrix.

The matrix rank is computed as the number of singular values (or eigenvalues in absolute value when hermitian= True) that are greater than the specified tol threshold.

Supports input of float, double, cfloat and cdouble dtypes. Also supports batches of matrices, and if A is a batch of matrices then the output has the same batch dimensions.

If hermitian= True, A is assumed to be Hermitian if complex or symmetric if real, but this is not checked internally. Instead, just the lower triangular part of the matrix is used in the computations.

If tol is not specified and A is a matrix of dimensions (m, n), the tolerance is set to be

tol=σ1max(m,n)ε\text{tol} = \sigma_1 \max(m, n) \varepsilon

where σ1\sigma_1 is the largest singular value (or eigenvalue in absolute value when hermitian= True), and ε\varepsilon is the epsilon value for the dtype of A (see torch.finfo). If A is a batch of matrices, tol is computed this way for every element of the batch.

Note

The matrix rank is computed using singular value decomposition torch.linalg.svd() if hermitian= False (default) and the eigenvalue decomposition torch.linalg.eigvalsh() when hermitian= True. When inputs are on a CUDA device, this function synchronizes that device with the CPU.

Parameters
  • A (Tensor) – tensor of shape (*, m, n) where * is zero or more batch dimensions.

  • tol (float, Tensor, optional) – the tolerance value. See above for the value it takes when None. Default: None.

  • hermitian (bool, optional) – indicates whether A is Hermitian if complex or symmetric if real. Default: False.

Keyword Arguments

out (Tensor, optional) – output tensor. Ignored if None. Default: None.

Examples:

>>> A = torch.eye(10)
>>> torch.linalg.matrix_rank(A)
tensor(10)
>>> B = torch.eye(10)
>>> B[0, 0] = 0
>>> torch.linalg.matrix_rank(B)
tensor(9)

>>> A = torch.randn(4, 3, 2)
>>> torch.linalg.matrix_rank(A)
tensor([2, 2, 2, 2])

>>> A = torch.randn(2, 4, 2, 3)
>>> torch.linalg.matrix_rank(A)
tensor([[2, 2, 2, 2],
        [2, 2, 2, 2]])

>>> A = torch.randn(2, 4, 3, 3, dtype=torch.complex64)
>>> torch.linalg.matrix_rank(A)
tensor([[3, 3, 3, 3],
        [3, 3, 3, 3]])
>>> torch.linalg.matrix_rank(A, hermitian=True)
tensor([[3, 3, 3, 3],
        [3, 3, 3, 3]])
>>> torch.linalg.matrix_rank(A, tol=1.0)
tensor([[3, 2, 2, 2],
        [1, 2, 1, 2]])
>>> torch.linalg.matrix_rank(A, tol=1.0, hermitian=True)
tensor([[2, 2, 2, 1],
        [1, 2, 2, 2]])

Docs

Access comprehensive developer documentation for PyTorch

View Docs

Tutorials

Get in-depth tutorials for beginners and advanced developers

View Tutorials

Resources

Find development resources and get your questions answered

View Resources