Matrix predicates

This page collects predicates, i.e. functions returning true or false, for testing whether matrices satisfy certain structural or normal-form conditions.

Basic predicates

Matrices support iszero and isone for testing whether a matrix is the zero matrix or the identity matrix, respectively.

Base.isempty — Method

isempty(a::MatrixElem{T}) where {T <: NCRingElement}

Return true if a has no entries, that is, if either the number of rows or the number of columns is zero. Otherwise, return false.

Examples

julia> A = zero_matrix(ZZ, 0, 3)
0 by 3 empty matrix

julia> isempty(A)
true

julia> B = matrix(ZZ, [1 2; 3 4])
[1   2]
[3   4]

julia> isempty(B)
false

Base.isassigned — Method

Base.isassigned(a::MatrixElem{T}, i::Int, j::Int) where {T <: NCRingElement}

Return true if the matrix a has an entry at position (i, j), and false otherwise.

Examples

julia> M = matrix(ZZ, [3 1 2; 2 0 1])
[3   1   2]
[2   0   1]

julia> isassigned(M, 1, 2)
true

julia> isassigned(M, 4, 4)
false

AbstractAlgebra.is_zero_row — Method

is_zero_row(M::Union{Matrix,MatrixElem}, i::Int)

Return true if the $i$-th row of the matrix $M$ is zero, and false otherwise.

This may be more efficient than checking all entries individually.

Examples

julia> M = matrix(ZZ, [1 2 3; 0 0 0])
[1   2   3]
[0   0   0]

julia> is_zero_row(M, 1)
false

julia> is_zero_row(M, 2)
true

AbstractAlgebra.is_zero_column — Method

is_zero_column(M::Union{Matrix,MatrixElem}, j::Int)

Return true if the $j$-th column of the matrix $M$ is zero, and false otherwise.

This may be more efficient than checking all entries individually.

Examples

julia> M = matrix(ZZ, [1 0; 2 0; 3 0])
[1   0]
[2   0]
[3   0]

julia> is_zero_column(M, 1)
false

julia> is_zero_column(M, 2)
true

Triangular and diagonal matrices

AbstractAlgebra.is_lower_triangular — Method

is_lower_triangular(M::MatElem)

Return true if $M$ is a lower triangular matrix, that is, all entries above the main diagonal are zero. Note that this definition also applies to non-square matrices.

Alias for LinearAlgebra.istril.

Examples

julia> is_lower_triangular(QQ[1 2 ; 0 4])
false

julia> is_lower_triangular(QQ[1 0 ; 3 4])
true

julia> is_lower_triangular(QQ[1 2 ;])
false

julia> is_lower_triangular(QQ[1 ; 2])
true

AbstractAlgebra.is_upper_triangular — Method

is_upper_triangular(M::MatElem)

Return true if $M$ is an upper triangular matrix, that is, all entries below the main diagonal are zero. Note that this definition also applies to non-square matrices.

Alias for LinearAlgebra.istriu.

Examples

julia> is_upper_triangular(QQ[1 2 ; 0 4])
true

julia> is_upper_triangular(QQ[1 0 ; 3 4])
false

julia> is_upper_triangular(QQ[1 2 ;])
true

julia> is_upper_triangular(QQ[1 ; 2])
false

AbstractAlgebra.is_diagonal — Method

is_diagonal(A::MatElem)

Return true if $A$ is a diagonal matrix, that is, if all entries off the main diagonal are zero. Note that this definition also applies to non-square matrices.

Alias for LinearAlgebra.isdiag.

Examples

julia> is_diagonal(QQ[1 0 ; 0 4])
true

julia> is_diagonal(QQ[1 2 ; 3 4])
false

julia> is_diagonal(QQ[1 0 ;])
true

AbstractAlgebra.is_hessenberg — Method

is_hessenberg(A::MatElem{T}) where {T <: RingElement}

Return true if $A$ is in (upper) Hessenberg form, that is, if all entries below the first subdiagonal are zero, and false otherwise.

Examples

julia> A = matrix(ZZ, [1 2 3; 4 5 6; 0 7 8])
[1   2   3]
[4   5   6]
[0   7   8]

julia> is_hessenberg(A)
true

julia> B = matrix(ZZ, [1 2 3; 4 5 6; 7 8 9])
[1   2   3]
[4   5   6]
[7   8   9]

julia> is_hessenberg(B)
false

Invertibility

AbstractAlgebra.is_invertible_with_inverse — Method

is_invertible_with_inverse(A::MatrixElem{T}; side::Symbol = :left) where {T <: RingElement}

Return a tuple (flag, B) indicating whether the matrix $A$ has a one-sided inverse.

If $A$ is an $n \times m$ matrix and side == :right, then flag is true precisely if a right inverse exists. In this case, $B$ is an $m \times n$ matrix such that $A B$ is the $n \times n$ identity matrix.

If side == :left, then flag is true precisely if a left inverse exists. In this case, $B$ is an $m \times n$ matrix such that $B A$ is the $m \times m$ identity matrix.

If flag is false, then no inverse exists on the requested side.

To compute all one-sided inverses from one inverse, use the kernel: if $B$ and $C$ are both right inverses, then $A(B - C) = 0$, and similarly for left inverses.

Examples

julia> A = matrix(QQ, [1 2; 3 4])
[1//1   2//1]
[3//1   4//1]

julia> flag, B = is_invertible_with_inverse(A);

julia> flag
true

julia> B
[-2//1    1//1]
[ 3//2   -1//2]

julia> B*A == one(parent(A))
true

julia> A = matrix(QQ, [1 0 0; 0 1 0])
[1//1   0//1   0//1]
[0//1   1//1   0//1]

julia> flag, B = is_invertible_with_inverse(A; side = :right);

julia> flag
true

julia> A*B == one(parent(A*B))
true

AbstractAlgebra.is_invertible — Method

is_invertible(A::MatElem{T}) where {T <: RingElement}

Return true if the square matrix $A$ is invertible, and false otherwise. To also compute an inverse, use is_invertible_with_inverse.

Examples

julia> A = matrix(ZZ, [1 2; 3 4])
[1   2]
[3   4]

julia> is_invertible(A)
false

julia> B = matrix(QQ, [1 2; 3 4])
[1//1   2//1]
[3//1   4//1]

julia> is_invertible(B)
true

Symmetry

AbstractAlgebra.is_symmetric — Method

is_symmetric(M::MatElem)

Return true if the given matrix is symmetric with respect to its main diagonal, i.e., transpose(M) == M, otherwise return false.

Alias for LinearAlgebra.issymmetric.

Examples

julia> M = matrix(ZZ, [1 2 3; 2 4 5; 3 5 6])
[1   2   3]
[2   4   5]
[3   5   6]

julia> is_symmetric(M)
true

julia> N = matrix(ZZ, [1 2 3; 4 5 6; 7 8 9])
[1   2   3]
[4   5   6]
[7   8   9]

julia> is_symmetric(N)
false

AbstractAlgebra.is_skew_symmetric — Method

is_skew_symmetric(M::MatElem)

Return true if the given matrix is skew symmetric with respect to its main diagonal, i.e., transpose(M) == -M, otherwise return false.

Examples

julia> M = matrix(ZZ, [0 -1 -2; 1 0 -3; 2 3 0])
[0   -1   -2]
[1    0   -3]
[2    3    0]

julia> is_skew_symmetric(M)
true

AbstractAlgebra.is_alternating — Method

is_alternating(M::MatElem)

Return true if M is alternating, that is, if M is skew-symmetric and all entries on the main diagonal are zero. Return false otherwise.

Non-square matrices are not considered alternating.

Examples

julia> M = matrix(ZZ, [0 2 -3; -2 0 5; 3 -5 0])
[ 0    2   -3]
[-2    0    5]
[ 3   -5    0]

julia> is_alternating(M)
true

julia> N = matrix(ZZ, [1 2; -2 1])
[ 1   2]
[-2   1]

julia> is_alternating(N)
false

Nilpotency

AbstractAlgebra.is_nilpotent — Method

is_nilpotent(A::MatElem{T}) where {T <: RingElement}

Return true if A is nilpotent, that is, if there exists a positive integer $k$ such that $A^k = 0$. Return false otherwise.

If A is not square, an exception is raised. The test is only supported for matrices defined over integral domains.

Examples

julia> A = matrix(ZZ, [0 1 0; 0 0 1; 0 0 0])
[0   1   0]
[0   0   1]
[0   0   0]

julia> is_nilpotent(A)
true

julia> B = matrix(ZZ, [1 1; 0 1])
[1   1]
[0   1]

julia> is_nilpotent(B)
false

Normal forms

AbstractAlgebra.is_rref — Method

is_rref(M::MatrixElem{T}) where {T <: RingElement}
is_rref(M::MatrixElem{T}) where {T <: FieldElement}

Return true if $M$ is in reduced row echelon form, and false otherwise.

For matrices over fields, leading entries are required to be normalized to one.

Examples

julia> A = matrix(QQ, [1 0 2; 0 1 3; 0 0 0])
[1//1   0//1   2//1]
[0//1   1//1   3//1]
[0//1   0//1   0//1]

julia> is_rref(A)
true

julia> B = matrix(QQ, [2 0 4; 0 1 3; 0 0 0])
[2//1   0//1   4//1]
[0//1   1//1   3//1]
[0//1   0//1   0//1]

julia> is_rref(B)
false

julia> C = matrix(ZZ, [2 0 4; 0 3 6; 0 0 0])
[2   0   4]
[0   3   6]
[0   0   0]

julia> is_rref(C)
true

AbstractAlgebra.is_hnf — Method

is_hnf(M::MatElem{T}) where {T <: RingElement}

Return true if the matrix $M$ is in Hermite normal form, and false otherwise.

Examples

julia> A = matrix(ZZ, [2 3 -1; 3 5 7; 11 1 12])
[ 2   3   -1]
[ 3   5    7]
[11   1   12]

julia> is_hnf(A)
false

julia> H = hnf(A)
[1   0   255]
[0   1    17]
[0   0   281]

julia> is_hnf(H)
true

AbstractAlgebra.is_snf — Method

is_snf(A::MatElem{T}) where {T <: RingElement}

Return true if $A$ is in Smith normal form, and false otherwise.

Examples

julia> A = matrix(ZZ, [2 4 4; -6 6 12; 10 -4 -16])
[ 2    4     4]
[-6    6    12]
[10   -4   -16]

julia> S = snf(A)
[2   0    0]
[0   6    0]
[0   0   12]

julia> is_snf(S)
true

AbstractAlgebra.is_weak_popov — Method

is_weak_popov(P::MatrixElem{T}, rank::Int) where {T <: PolyRingElem}

Return true if $P$ is in weak Popov form with the given rank, and false otherwise.

Examples

julia> R, x = polynomial_ring(QQ, :x);

julia> A = matrix(R, map(R, Any[1 2 3 x; x 2*x 3*x x^2; x x^2+1 x^3+x^2 x^4+x^2+1]));

julia> P = weak_popov(A)
[   1                        2                    3   x]
[   0                        0                    0   0]
[-x^3   -2*x^3 + x^2 - 2*x + 1   -2*x^3 + x^2 - 3*x   1]

julia> is_weak_popov(P, 2)
true

julia> is_weak_popov(P, 3)
false

AbstractAlgebra.is_popov — Method

is_popov(P::MatrixElem{T}, rank::Int) where {T <: PolyRingElem}

Return true if $P$ is in Popov form with the given rank, and false otherwise.

Examples

julia> R, x = polynomial_ring(QQ, :x);

julia> A = matrix(R, map(R, Any[1 2 3 x; x 2*x 3*x x^2; x x^2+1 x^3+x^2 x^4+x^2+1]));

julia> P = popov(A)
[       0                           0                         0       0]
[       1                           2                         3       x]
[1//2*x^3   x^3 - 1//2*x^2 + x - 1//2   x^3 - 1//2*x^2 + 3//2*x   -1//2]

julia> is_popov(P, 1)
false

julia> is_popov(P, 2)
true