# 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` ```magma 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](../../references.md#cite-abm-det)] 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 -> [ ]` 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 -> [ ]` 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` ```magma 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 -> { }` 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.