---
title: "Elementary Operations on Elements"
canonical: "https://docs.magma-maths.org/v2.30-1/Algebras/MatrixAlgebras/element.html"
source: "https://docs.magma-maths.org/v2.30-1/Algebras/MatrixAlgebras/element.md"
part: "Algebras"
chapter: "Matrix Algebras"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "Algebras", "source": "https://docs.magma-maths.org/v2.30-1/Algebras/index-algebras.md"}
  - {"title": "Matrix Algebras", "source": "https://docs.magma-maths.org/v2.30-1/Algebras/MatrixAlgebras/index-matrix-algebras.md"}
prev: {"title": "Changing Rings", "source": "https://docs.magma-maths.org/v2.30-1/Algebras/MatrixAlgebras/change-ring.md"}
next: {"title": "Elements of $M_n$ as Homomorphisms", "source": "https://docs.magma-maths.org/v2.30-1/Algebras/MatrixAlgebras/homomorphism-element.md"}
intrinsics:
  - {"name": "+", "signature": "a + b: AlgMatElt, AlgMatElt -> AlgMatElt"}
  - {"name": "+", "signature": "a + t: AlgMatElt, RngElt -> AlgMatElt"}
  - {"name": "+", "signature": "t + a: AlgMatElt, RngElt -> AlgMatElt"}
  - {"name": "-", "signature": "- a: AlgMatElt -> AlgMatElt"}
  - {"name": "-", "signature": "a - b: AlgMatElt, AlgMatElt -> AlgMatElt"}
  - {"name": "-", "signature": "a - t: AlgMatElt, RngElt -> AlgMatElt"}
  - {"name": "-", "signature": "t - a: AlgMatElt, RngElt -> AlgMatElt"}
  - {"name": "*", "signature": "a * b: AlgMatElt, AlgMatElt -> AlgMatElt"}
  - {"name": "*", "signature": "a * b: AlgMatElt, Mtrx -> Mtrx"}
  - {"name": "*", "signature": "a * b: Mtrx, AlgMatElt -> Mtrx"}
  - {"name": "*", "signature": "t * a: RngElt, AlgMatElt -> AlgMatElt"}
  - {"name": "*", "signature": "a * t: AlgMatElt, RngElt -> AlgMatElt"}
  - {"name": "*", "signature": "u * a: ModTupRngElt, AlgMatElt -> ModTupElt"}
  - {"name": "^", "signature": "a ^ n: AlgMatElt, RngIntElt -> AlgMatElt"}
  - {"name": "NumberOfColumns", "signature": "NumberOfColumns(a): AlgMatElt -> RngIntElt"}
  - {"name": "Ncols", "signature": "Ncols(a): AlgMatElt -> RngIntElt"}
  - {"name": "NumberOfRows", "signature": "NumberOfRows(a): AlgMatElt -> RngIntElt"}
  - {"name": "Nrows", "signature": "Nrows(a): AlgMatElt -> RngIntElt"}
  - {"name": "eq", "signature": "a eq b: AlgMatElt, AlgMatElt -> BoolElt"}
  - {"name": "ne", "signature": "a ne b: AlgMatElt, AlgMatElt -> BoolElt"}
  - {"name": "IsDiagonal", "signature": "IsDiagonal(a): AlgMatElt -> BoolElt"}
  - {"name": "IsMinusOne", "signature": "IsMinusOne(a): AlgMatElt -> BoolElt"}
  - {"name": "IsOne", "signature": "IsOne(a): AlgMatElt -> BoolElt"}
  - {"name": "IsScalar", "signature": "IsScalar(a): AlgMatElt -> BoolElt"}
  - {"name": "IsSymmetric", "signature": "IsSymmetric(a): AlgMatElt -> BoolElt"}
  - {"name": "IsUnit", "signature": "IsUnit(a): AlgMatElt -> BoolElt"}
  - {"name": "IsZero", "signature": "IsZero(a): AlgMatElt -> BoolElt"}
  - {"name": "IsNilpotent", "signature": "IsNilpotent(a): AlgMatElt -> BoolElt, RngIntElt"}
  - {"name": "IsUnipotent", "signature": "IsUnipotent(a): AlgMatElt -> BoolElt, RngIntElt"}
  - {"name": "Rank", "signature": "Rank(a): AlgMatElt -> RngIntElt"}
  - {"name": "Determinant", "signature": "Determinant(A): AlgMatElt -> RngElt"}
  - {"name": "Trace", "signature": "Trace(a): AlgMatElt -> RngElt"}
  - {"name": "Transpose", "signature": "Transpose(a): AlgMatElt -> AlgMatElt"}
  - {"name": "Order", "signature": "Order(a): AlgMatElt -> RngIntElt"}
  - {"name": "FactoredOrder", "signature": "FactoredOrder(a): AlgMatElt -> [ <RngIntElt, RngIntElt> ]"}
  - {"name": "ProjectiveOrder", "signature": "ProjectiveOrder(a): AlgMatElt -> RngIntElt"}
  - {"name": "FactoredProjectiveOrder", "signature": "FactoredProjectiveOrder(a): AlgMatElt -> [ <RngIntElt, RngIntElt> ]"}
  - {"name": "CharacteristicPolynomial", "signature": "CharacteristicPolynomial(a: parameters): AlgMatElt -> RngUPolElt"}
  - {"name": "MinimalPolynomial", "signature": "MinimalPolynomial(a): AlgMatElt -> RngUPolElt"}
  - {"name": "HessenbergForm", "signature": "HessenbergForm(a): AlgMatElt -> AlgMatElt"}
  - {"name": "Adjoint", "signature": "Adjoint(a): AlgMatElt -> AlgMatElt"}
  - {"name": "Eigenvalues", "signature": "Eigenvalues(a): AlgMatElt -> { <FldElt, RngIntElt> }"}
  - {"name": "Eigenspace", "signature": "Eigenspace(a, e): AlgMatElt, FldElt -> ModTup"}
---

# Elementary Operations on Elements

## Arithmetic

<a id="operation-op-plus-algmatelt-algmatelt"></a>
### `a + b: AlgMatElt, AlgMatElt -> AlgMatElt`

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

<a id="operation-op-plus-algmatelt-rngelt"></a>
### `a + t: AlgMatElt, RngElt -> AlgMatElt`

<a id="operation-op-plus-algmatelt-rngelt-2"></a>
### `t + a: AlgMatElt, RngElt -> AlgMatElt`

Sum of the matrix $a$ and the scalar matrix $t * I$.

<a id="operation-operation-algmatelt-algmatelt"></a>
### `- a: AlgMatElt -> AlgMatElt`

Negation of the matrix $a$.

<a id="operation-op-minus-algmatelt-algmatelt"></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 id="operation-op-minus-algmatelt-rngelt"></a>
### `a - t: AlgMatElt, RngElt -> AlgMatElt`

<a id="operation-op-minus-algmatelt-rngelt-2"></a>
### `t - a: AlgMatElt, RngElt -> AlgMatElt`

Difference of the matrix $a$ and the scalar matrix $t * I$.

<a id="operation-op-times-algmatelt-algmatelt"></a>
### `a * b: AlgMatElt, AlgMatElt -> AlgMatElt`

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

<a id="operation-op-times-algmatelt-mtrx"></a>
### `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 id="operation-op-times-mtrx-algmatelt"></a>
### `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)})$.

<a id="operation-op-times-rngelt-algmatelt"></a>
### `t * a: RngElt, AlgMatElt -> AlgMatElt`

<a id="operation-op-times-algmatelt-rngelt"></a>
### `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.

<a id="operation-op-times-modtuprngelt-algmatelt"></a>
### `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 id="operation-op-pow-algmatelt-rngintelt"></a>
### `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$.

<a id="function-numberofcolumns-algmatelt"></a>
### `NumberOfColumns(a): AlgMatElt -> RngIntElt`

<a id="function-ncols-algmatelt"></a>
### `Ncols(a): AlgMatElt -> RngIntElt`

The number of columns in the matrix $a$.

<a id="function-numberofrows-algmatelt"></a>
### `NumberOfRows(a): AlgMatElt -> RngIntElt`

<a id="function-nrows-algmatelt"></a>
### `Nrows(a): AlgMatElt -> RngIntElt`

The number of rows in the matrix $a$.

## Predicates

### Comparison

<a id="operation-op-eq-algmatelt-algmatelt"></a>
#### `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 id="operation-op-ne-algmatelt-algmatelt"></a>
#### `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.

<a id="function-isdiagonal-algmatelt"></a>
#### `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.

<a id="function-isminusone-algmatelt"></a>
#### `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$.

<a id="function-isone-algmatelt"></a>
#### `IsOne(a): AlgMatElt -> BoolElt`

Returns `true` iff the element $a$ belonging to the matrix algebra $R$ is the identity element for $R$.

<a id="function-isscalar-algmatelt"></a>
#### `IsScalar(a): AlgMatElt -> BoolElt`

Returns `true` iff the element $a$ belonging to the matrix algebra $R$ is a scalar matrix.

<a id="function-issymmetric-algmatelt"></a>
#### `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$.

<a id="function-isunit-algmatelt"></a>
#### `IsUnit(a): AlgMatElt -> BoolElt`

Returns `true` iff the matrix $a$ belonging to the matrix algebra $R$ is a unit.

<a id="function-iszero-algmatelt"></a>
#### `IsZero(a): AlgMatElt -> BoolElt`

Returns `true` iff the element $a$ belonging to the matrix algebra $R$ is the zero element for $R$.

<a id="function-isnilpotent-algmatelt"></a>
#### `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$.

<a id="function-isunipotent-algmatelt"></a>
#### `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$.

<a id="function-rank-algmatelt"></a>
#### `Rank(a): AlgMatElt -> RngIntElt`

Return the rank of the element $a$ belonging to the matrix algebra $R$.

<a id="function-determinant-algmatelt"></a>
#### `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. [[ABM99](https://docs.magma-maths.org/v2.30-1/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.

<a id="function-trace-algmatelt"></a>
#### `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$.

<a id="function-transpose-algmatelt"></a>
#### `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)$.

<a id="function-order-algmatelt"></a>
#### `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.

<a id="function-factoredorder-algmatelt"></a>
#### `FactoredOrder(a): AlgMatElt -> [ <RngIntElt, RngIntElt> ]`

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

<a id="function-projectiveorder-algmatelt"></a>
#### `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$.

<a id="function-factoredprojectiveorder-algmatelt"></a>
#### `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$.

<a id="function-characteristicpolynomial-algmatelt"></a>
#### `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$.

<a id="function-minimalpolynomial-algmatelt"></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$.

<a id="function-hessenbergform-algmatelt"></a>
#### `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.)

<a id="function-adjoint-algmatelt"></a>
#### `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$.

<a id="function-eigenvalues-algmatelt"></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.

<a id="function-eigenspace-algmatelt-fldelt"></a>
#### `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.
