Elementary Operations on Elements

Arithmetic

a + b: AlgMatElt, AlgMatElt -> AlgMatElt

Sum of the matrices \(a\) and \(b\), where \(a\) and \(b\) belong to a common matrix algebra \(R\).

a + t: AlgMatElt, RngElt -> AlgMatElt

t + a: AlgMatElt, RngElt -> AlgMatElt

Sum of the matrix \(a\) and the scalar matrix \(t * I\).

- a: AlgMatElt -> AlgMatElt

Negation of the matrix \(a\).

a - b: AlgMatElt, AlgMatElt -> AlgMatElt

Difference of the matrices \(a\) and \(b\), where \(a\) and \(b\) belong to the same matrix algebra \(R\).

a - t: AlgMatElt, RngElt -> AlgMatElt

t - a: AlgMatElt, RngElt -> AlgMatElt

Difference of the matrix \(a\) and the scalar matrix \(t * I\).

a * b: AlgMatElt, AlgMatElt -> AlgMatElt

Product of the matrices \(a\) and \(b\), where \(a\) and \(b\) belong to the same matrix algebra \(R\).

a * b: AlgMatElt, Mtrx -> Mtrx

Given a matrix \(a\) belonging to a subalgebra of \(M_n(S)\) and an element \(b\) of a submodule of \({\operatorname{Hom}}(R^{(n)}, R^{(m)})\), construct the product of \(a\) and \(b\) as an element of \({\operatorname{Hom}}(R^{(n)}, R^{(m)})\).

a * b: Mtrx, AlgMatElt -> Mtrx

Given a matrix \(a\) belonging to a submodule of \({\operatorname{Hom}}(R^{(n)}, R^{(m)})\) and an element \(b\) of a subalgebra of \(M_m(S)\), construct the product of \(a\) and \(b\) as an element of \({\operatorname{Hom}}(R^{(n)}, R^{(m)})\).

t * a: RngElt, AlgMatElt -> AlgMatElt

a * t: AlgMatElt, RngElt -> AlgMatElt

Given an element \(a\) of the matrix algebra \(R\), and an element \(t\) belonging to the coefficient ring \(S\) of \(R\), form their scalar product.

u * a: ModTupRngElt, AlgMatElt -> ModTupElt

Given an element \(u\) belonging to the \(S\)-module \(S^{(n)}\) and an element \(a\) belonging to a subalgebra of \(M_n(S)\), form the element \(u*a\) of \(S^n\).

a ^ n: AlgMatElt, RngIntElt -> AlgMatElt

If \(n\) is positive, form the \(n\)-th power of \(a\); if \(n\) is zero, form the identity matrix; if \(n\) is negative, form the \((-n)\)-th power of the inverse of \(a\).

NumberOfColumns(a): AlgMatElt -> RngIntElt

Ncols(a): AlgMatElt -> RngIntElt

The number of columns in the matrix \(a\).

NumberOfRows(a): AlgMatElt -> RngIntElt

Nrows(a): AlgMatElt -> RngIntElt

The number of rows in the matrix \(a\).

Predicates

Comparison

a eq b: AlgMatElt, AlgMatElt -> BoolElt

Returns true if the matrix \(a\) is equal to the matrix \(b\), where \(a\) and \(b\) are elements of a common matrix algebra \(R\).

a ne b: AlgMatElt, AlgMatElt -> BoolElt

Returns true if the matrix \(a\) is not equal to the matrix \(b\), where \(a\) and \(b\) are elements of a common matrix algebra \(R\).

Properties of Elements

The functions given here test properties of matrices. See also the section in the Lattices chapter for a description of the function IsPositiveDefinite and related functions.

IsDiagonal(a): AlgMatElt -> BoolElt

Returns true iff the element \(a\) belonging to the matrix algebra \(R\) is a diagonal matrix; i.e. the only non-zero entries are on the diagonal.

IsMinusOne(a): AlgMatElt -> BoolElt

Returns true iff the element \(a\) belonging to the matrix algebra \(R\) is the negation of the identity element for \(R\).

IsOne(a): AlgMatElt -> BoolElt

Returns true iff the element \(a\) belonging to the matrix algebra \(R\) is the identity element for \(R\).

IsScalar(a): AlgMatElt -> BoolElt

Returns true iff the element \(a\) belonging to the matrix algebra \(R\) is a scalar matrix.

IsSymmetric(a): AlgMatElt -> BoolElt

Returns true iff the element \(a\) belonging to the matrix algebra \(R\) is a symmetric matrix; i.e. the transpose of \(a\) equals \(a\).

IsUnit(a): AlgMatElt -> BoolElt

Returns true iff the matrix \(a\) belonging to the matrix algebra \(R\) is a unit.

IsZero(a): AlgMatElt -> BoolElt

Returns true iff the element \(a\) belonging to the matrix algebra \(R\) is the zero element for \(R\).

IsNilpotent(a): AlgMatElt -> BoolElt, RngIntElt

Return true if some power of the matrix \(a\) belonging to a matrix algebra is the zero of the matrix algebra. Also returns the minimum exponent \(n\) such that \(a^n = 0\).

IsUnipotent(a): AlgMatElt -> BoolElt, RngIntElt

Return true if the matrix \(a\) belonging to a matrix algebra is the identity of that algebra plus a nilpotent matrix. Also returns the index of nilpotence of \(a - I\).

Rank(a): AlgMatElt -> RngIntElt

Return the rank of the element \(a\) belonging to the matrix algebra \(R\).

Determinant(A): AlgMatElt -> RngElt

MonteCarloLevel: RngIntElt                    Default: 0
Proof          : BoolElt                      Default: true
pAdic          : BoolElt                      Default: true
Divisor        : RngIntElt                    Default: 0

Given a square matrix \(A\) over the ring \(R\), return the determinant of \(A\) as an element of \(R\). \(R\) may be any commutative ring. The determinant of the \(0 \times 0\) matrix over \(R\) is defined to be R!1. If the coefficient ring is the integer ring \({\mathbb{Z}}\) or the rational field \({\mathbb{Q}}\) then a modular algorithm based on that of Abbott et al. [Abbott et al., 1999] is used, which first computes a divisor \(d\) of the determinant \(D\) using a fast \(p\)-adic nullspace computation, and then computes the quotient \(D/d\) by computing the determinant \(D\) modulo enough small primes to cover the Hadamard bound divided by \(d\). This always yields a correct answer. If the parameter MonteCarloLevel is set to a small positive integer \(s\), then a probabilistic Monte-Carlo modular technique is used. Rather than using sufficient primes to cover the Hadamard bound divided by the divisor \(d\), this version of the algorithm terminates when the constructed residue remains constant for \(s\) steps. The probability of this being wrong is non-zero but extremely small, even if \(s\) is only 1 or 2. If the level is set to 0, then the normal deterministic algorithm is used. Setting the parameter Proof to false is equivalent to setting MonteCarloLevel to 2. If the coefficient ring is \({\mathbb{Z}}\) and the parameter Divisor is set to an integer \(d\), then \(d\) must be a known exact divisor of the determinant (the sign does not matter), and the algorithm may be sped up because of this knowledge.

Trace(a): AlgMatElt -> RngElt

Given an element \(a\) of a subalgebra of \(M_n(S)\), return the trace of \(a\) as an element of \(S\).

Transpose(a): AlgMatElt -> AlgMatElt

Given an element \(a\) of a subalgebra of \(M_n(S)\), return the transpose of \(a\) as an element of \(M_n(S)\).

Order(a): AlgMatElt -> RngIntElt

Given an invertible matrix \(a\) over any commutative ring, determine the order of \(a\). If \(a\) has infinite order, the function may become stuck indefinitely since it cannot prove such.

FactoredOrder(a): AlgMatElt -> [ <RngIntElt, RngIntElt> ]

Given an invertible matrix \(a\) over a finite field, return the order of \(a\) in factored form.

ProjectiveOrder(a): AlgMatElt -> RngIntElt

Given an invertible matrix \(a\) over a finite field, return the projective order \(o\) of \(a\) and a scalar \(s\) such that \(a^o = sI\).

FactoredProjectiveOrder(a): AlgMatElt -> [ <RngIntElt, RngIntElt> ]

Given an invertible matrix \(a\) over a finite field, return the projective order \(o\) of \(a\) in factored form and a scalar \(s\) such that \(a^o = sI\).

CharacteristicPolynomial(a: parameters): AlgMatElt -> RngUPolElt

Al   : MonStgElt                    Default: "Modular"
Proof: BoolElt                      Default: true

The characteristic polynomial of the element \(a\) belonging to the algebra \(M_n(R)\), where \(R\) can be any commutative ring. The parameter Al may be used to specify the algorithm used. The algorithm Modular (the default) can be used for matrices over \(Z\) and \(Q\)—in such a case the parameter Proof can also be used to suppress proof of correctness. The algorithm Hessenberg, allowed for matrices over fields, works by first reducing the matrix to Hessenberg form. The algorithm Interpolation, allowed for matrices over \(Z\) and \(Q\), works by evaluating the characteristic matrix of \(a\) at various points and then interpolating. The algorithm Trace, allowed for matrices over fields, works by calculating the traces of powers of \(a\).

MinimalPolynomial(a): AlgMatElt -> RngUPolElt

The minimal polynomial of the element \(a\) belonging to the module \(M_n(R)\), where \(R\) is a field or \(Z\).

HessenbergForm(a): AlgMatElt -> AlgMatElt

The Hessenberg form for the matrix \(a\) belonging to the algebra \(M_n(K)\), where the coefficient ring \(K\) must be a field. The form has zero entries above the super-diagonal. (This form is used in one of the characteristic polynomial algorithms.)

Adjoint(a): AlgMatElt -> AlgMatElt

The adjoint of the matrix \(a\) belonging to the algebra \(M_n(K)\), where the coefficient ring \(K\) must be a ring with exact division whose characteristic must be zero or greater than the degree of \(a\).

Eigenvalues(a): AlgMatElt -> { <FldElt, RngIntElt> }

The eigenvalues of the matrix \(a\) returned as a set of pairs, each of which gives the value of a distinct eigenvalue and its multiplicity. The coefficient ring must have a polynomial roots algorithm.

Eigenspace(a, e): AlgMatElt, FldElt -> ModTup

The eigenspace of the matrix \(a\), corresponding to the eigenvalue \(e\), returned as a submodule of the base module for the parent algebra of \(a\) (i.e. the kernel of \(a-eI\)). If the ring element \(e\) is not a eigenvalue for the matrix \(a\) then the trivial space is returned.