7.1.3.5 Matrix_field Objects

class Matrix_field
Matrix_field( parent)

Instances of class Matrix_field have the following methods (in addition to inherited methods and special methods):

charpoly,$  $ column_space,$  $ decomposition_of_subspace,$  $ denominator,$  $ echelon_form,$  $ fcp,$  $ hessenberg_form,$  $ integer_kernel,$  $ is_invertible,$  $ kernel,$  $ maxspin,$  $ nullity,$  $ numeric_array,$  $ pivots,$  $ rank,$  $ restrict,$  $ restrict_domain,$  $ row_space,$  $ row_span,$  $ wiedemann

Further documentation:

charpoly( )

Return the characteristic polynomial of this matrix.

sage: A = MatrixSpace(RationalField(),3)(range(9))
sage: A.charpoly()
x^3 - 12*x^2 - 18*x
sage: A.trace()
12
sage: A.determinant()
0

column_space( )

Return the vector space over the base ring spanned by the columns of this matrix.

decomposition_of_subspace( M, [is_diagonalizable=False])

Suppose the right action of self on M leaves M invariant. Return the decomposition of M as a list of pairs (W, is_irred) where is_irred is True if the charpoly of self acting on the factor W is irreducible.

denominator( )

Return the least common multiple of the denominators of the elements of self.

If there is no denominator function for the base field, or no LCM function for the denominators, raise a TypeError.

sage: A = MatrixSpace(RationalField(),2)(['1/2', '1/3', '1/5', '1/7'])
sage: A.denominator()
210

Denominators are note defined for real numbers:

sage: A = MatrixSpace(RealField(),2)([1,2,3,4])
sage: A.denominator()
Traceback (most recent call last):
...
TypeError: denominator not defined for elements of the base ring

We can even compute the denominator of matrix over the fraction field of $ \mathbf{Z}[x]$ .

sage: K = FractionField(PolynomialRing(IntegerRing()))
sage: x = K.gen()
sage: A = MatrixSpace(K,2)([1/x, 2/(x+1), 1, 5/(x**3)])
sage: A.denominator()
x^4 + x^3

echelon_form( [include_zero_rows=True])

Returns the reduced row echelon form of self.

INPUT:
    matrix -- an element A of a MatrixSpace

OUTPUT:
    matrix -- The reduced row echelon form of A.
    Note that self is *not* changed by this command.

sage: MS = MatrixSpace(RationalField(),2,3)
sage: C = MS.matrix([1,2,3,4,5,6])
sage: C.rank()
2
sage: C.nullity()
1
sage: C.echelon_form()
[ 1  0 -1]
[ 0  1  2]

fcp( )

Return the factorization of the characteristic polynomial of self.

hessenberg_form( )

Return the Hessenberg form of self.

The hessenberg form of a matrix $ A$ is a matrix that is similar to $ A$ , so has the same characteristic polynomial as $ A$ , and is upper triangular except possible for entries right below the diagonal.

ALGORITHM: See Henri Cohen's first book.

sage: A = MatrixSpace(RationalField(),3)([2, 1, 1, -2, 2, 2, -1, -1, -1])
sage: A.hessenberg_form()
[  2 3/2   1]
[ -2   3   2]
[  0  -3  -2]

sage: A = MatrixSpace(RationalField(),4)([2, 1, 1, -2, 2, 2, -1, -1, -1,1,2,3,4,5,6,7])
sage: A.hessenberg_form()
[    2  -7/2 -19/5    -2]
[    2   1/2 -17/5    -1]
[    0  25/4  15/2   5/2]
[    0     0  58/5     3]

integer_kernel( )

Return the integer kernel of this matrix.

Assume that the base field of this matrix has a numerator and denominator functions for its elements, e.g., it is the rational numbers or a fraction field. This function computes a basis over the integers for the kernel of self.

sage: A = MatrixSpace(RationalField(),4)(range(16))
sage: A.integer_kernel()
Free module of degree 4 and rank 2 over Integer Ring
Echelon basis matrix:
[ 1  0 -3  2]
[ 0  1 -2  1]

The integer kernel even makes sense for matrices with fractional entries:

sage: A = MatrixSpace(RationalField(),2)(['1/2',0,  0, 0])
sage: A.integer_kernel()
Free module of degree 2 and rank 1 over Integer Ring
Echelon basis matrix:
[0 1]

is_invertible( )

Return True if this matrix is invertible.

kernel( )

Return the kernel of this matrix, as a vector space.

ALGORITHM: Elementary row operations don't change the kernel, since they are just right multiplication by an invertible matrix, so we instead compute kernel of the column echelon form. More precisely, there is a basis vector of the kernel that corresponds to each non-pivot row. That vector has a 1 at the non-pivot row, 0's at all other non-pivot rows, and for each pivot row, the negative of the entry at the non-pivot row in the column with that pivot element.

Note: Since we view matrices as acting on the right, but have functions for reduced row echelon forms, we instead compute the reduced row echelon form of the transpose of this matrix, which is the reduced column echelon form.

A kernel of dimension one over $ \mathbf{Q}$ :x

sage: A = MatrixSpace(RationalField(),3)(range(9))
sage: A.kernel()
Vector space of degree 3 and dimension 1 over Rational Field
Basis matrix:
[ 1 -2  1]

A trivial kernel:

sage: A = MatrixSpace(RationalField(),2)([1,2,3,4])
sage: A.kernel()
Vector space of degree 2 and dimension 0 over Rational Field
Basis matrix:
[]

Kernel of a zero matrix:

sage: A = MatrixSpace(RationalField(),2)(0)
sage: A.kernel()
Vector space of degree 2 and dimension 2 over Rational Field
Basis matrix:
[1 0]
[0 1]

Kernel of a non-square matrix:

sage: A = MatrixSpace(RationalField(),3,2)(range(6))
sage: A.kernel()
Vector space of degree 3 and dimension 1 over Rational Field
Basis matrix:
[ 1 -2  1]

The 2-dimensional kernel of a matrix over a cyclotomic field:

sage: K = CyclotomicField(12); a=K.gen()
sage: M = MatrixSpace(K,4,2)([1,-1, 0,-2, 0,-a**2-1, 0,a**2-1])
sage: M
[             1             -1]
[             0             -2]
[             0 -zeta_12^2 - 1]
[             0  zeta_12^2 - 1]
sage: M.kernel()
Vector space of degree 4 and dimension 2 over Cyclotomic Field of order 12
and degree 4
Basis matrix:
[               0                1                0     -2*zeta_12^2]
[               0                0                1 -2*zeta_12^2 + 1]

A nontrivial kernel over a complicated base field.

sage: K = FractionField(MPolynomialRing(RationalField(),2))
sage: M = MatrixSpace(K, 2)([[K.gen(1),K.gen(0)], [K.gen(1), K.gen(0)]])
sage: M
[x_1 x_0]
[x_1 x_0]
sage: M.kernel()
Vector space of degree 2 and dimension 1 over Fraction field of Polynomial
ring in x_0, x_1 over Rational Field
Basis matrix:
[(-1*x_1^2)/(-1*x_1^2)          x_1/(-1*x_1)]

maxspin( v)

Computes the largest integer n such that the list of vectors $ S=[v, A(v), ..., A^n(v)]$ are linearly independent, and returns that list.

INPUT:
    self -- Matrix
    v -- Vector
OUTPUT:
    list -- list of Vectors

ALGORITHM: The current implementation just adds vectors to a vector space until the dimension doesn't grow. This could be optimized by directly using matrices and doing an efficient Echelon form. Also, when the base is Q, maybe we could simultaneously keep track of what is going on in the reduction modulo p, which might make things much faster.

numeric_array( [typecode=None])

Return the Numeric array associated to this field, if possible, and Numeric is installed.

pivots( )

Return the i such that the i-th column of self is a pivot column of the reduced row echelon form of self.

OUTPUT: list - sorted list of integers

restrict( V, [check=False])

Returns the matrix that defines the action of self on the invariant subspace V. If V is the ambient vector space, returns self (not a copy of self).

INPUT:
    V -- vector subspace
    check -- (optional) default: False; if True but V is not
             invariant, raise an ArithmeticError exception.
OUTPUT:
    a matrix

WARNING: This function returns an nxn matrix, where V has dimension n. It does not check that V is in fact invariant under self, unless check is True (not the default).

sage: V = VectorSpace(RationalField(),3)
sage: M = MatrixSpace(RationalField(),3)
sage: A = M([1,2,0, 3,4,0, 0,0,0])
sage: W = V.subspace([[1,0,0], [0,1,0]])
sage: A.restrict(W)
[1 2]
[3 4]
sage: A.restrict(W, check=True)
[1 2]
[3 4]

We illustrate the warning about invariance not being checked by default, by giving a non-invariant subspace. With the default check=False this function returns the 'restriction' matrix, which is meaningless as check=True reveals.

sage: W2 = V.subspace([[1,0,0], [0,1,1]])
sage: A.restrict(W2)
[1 2]
[3 4]
sage: A.restrict(W2, check=True)
Traceback (most recent call last):
...
ArithmeticError: subspace is not invariant under matrix

restrict_domain( V)

Compute the matrix relative to the basis for V on the domain obtained by restricting self to V, but not changing the codomain of the matrix. This is the matrix whose rows are the images of the basis for V.

INPUT:
    V -- vector space (subspace of ambient space on which self acts)

SEE ALSO: restrict()

sage: V = VectorSpace(RationalField(),3)
sage: M = MatrixSpace(RationalField(),3)
sage: A = M([1,2,0, 3,4,0, 0,0,0])
sage: W = V.subspace([[1,0,0], [1,2,3]])
sage: A.restrict_domain(W)
[1 2 0]
[3 4 0]
sage: W2 = V.subspace_with_basis([[1,0,0], [1,2,3]])
sage: A.restrict_domain(W2)
[ 1  2  0]
[ 7 10  0]

row_space( )

Return the vector space over the base field spanned by the rows of self.

sage: A = MatrixSpace(RationalField(),2,2)([1,2,3,4])
sage: A.row_space()
Vector space of degree 2 and dimension 2 over Rational Field
Basis matrix:
[1 0]
[0 1]
sage: A.row_span(IntegerRing())
Free module of degree 2 and rank 2 over Integer Ring
Echelon basis matrix:
[1 0]
[0 2]

row_span( [R=None])

Return the R-module spanned by the rows of self.

INPUT:
    R -- (optional) principal ideal ring, such that the
         entries of self coerce into R.  The default
         is the base ring.
OUTPUT:
    a free R-module.

We define a $ 2\times 3$ matrix over $ \mathbf{Q}$ , then consider its row span over both $ \mathbf{Q}$ and $ \mathbf{Z}$ .

sage: A = MatrixSpace(RationalField(),2,3)([1,2,3, '1/3', 4, 2])
sage: A
[  1   2   3]
[1/3   4   2]
sage: M1 = A.row_span(); M1
Vector space of degree 3 and dimension 2 over Rational Field
Basis matrix:
[   1    0 12/5]
[   0    1 3/10]
sage: M2 = A.row_span(IntegerRing()); M2
Free module of degree 3 and rank 2 over Integer Ring
Echelon basis matrix:
[1/3   4   2]
[  0  10   3]

Note that the determinants of the inner product matrices are different, though their discriminants differ by a square:

sage: M1.inner_product_matrix()
[ 169/25   18/25]
[  18/25 109/100]
sage: d1 = M1.discriminant(); d1
137/20
sage: d2 = M2.discriminant(); d2
685/9
sage: d2/d1
100/9

wiedemann( i, [t=0])

Application of Wiedemann's algorithm to the i-th standard basis vector.

If the optimal parameter t is nonzero, use only the first t linear recurrence relations.

Instances of class Matrix_field also have the following special methods:

__invert__,$  $ _set_pivots,$  $ _set_rank

Further documentation:

__invert__( )

Return this inverse of this matrix.

Raises a ZeroDivisionError if the matrix has zero determinant, and raises an ArithmeticError, if the inverse doesn't exist because the matrix is nonsquare.

See About this document... for information on suggesting changes.