### Navigation

- index
- modules |
- next |
- previous |
- Matrices and Spaces of Matrices »

# Base class for matrices, part 0

Base class for matrices, part 0

Note

For design documentation see matrix/docs.py.

EXAMPLES:

    sage: matrix(2,[1,2,3,4])
    [1 2]
    [3 4]

class `sage.matrix.matrix0.``Matrix`

  Bases: `sage.structure.element.Matrix`

  A generic matrix.

  The `Matrix` class is the base class for all matrix classes. To create a `Matrix`, first create a `MatrixSpace`, then coerce a list of elements into the `MatrixSpace`. See the documentation of `MatrixSpace` for more details.

  EXAMPLES:

  We illustrate matrices and matrix spaces. Note that no actual matrix that you make should have class Matrix; the class should always be derived from Matrix.

      sage: M = MatrixSpace(CDF,2,3); M
      Full MatrixSpace of 2 by 3 dense matrices over Complex Double Field
      sage: a = M([1,2,3,  4,5,6]); a
      [1.0 2.0 3.0]
      [4.0 5.0 6.0]
      sage: type(a)
      <type 'sage.matrix.matrix_complex_double_dense.Matrix_complex_double_dense'>
      sage: parent(a)
      Full MatrixSpace of 2 by 3 dense matrices over Complex Double Field

      sage: matrix(CDF, 2,3, [1,2,3, 4,5,6])
      [1.0 2.0 3.0]
      [4.0 5.0 6.0]
      sage: Mat(CDF,2,3)(range(1,7))
      [1.0 2.0 3.0]
      [4.0 5.0 6.0]

      sage: Q.<i,j,k> = QuaternionAlgebra(QQ, -1,-1)
      sage: matrix(Q,2,1,[1,2])
      [1]
      [2]

  `act_on_polynomial`(f)

    Returns the polynomial f(self*x).

    INPUT:

    - `self` - an nxn matrix
    - `f` - a polynomial in n variables x=(x1,...,xn)

    OUTPUT: The polynomial f(self*x).

    EXAMPLES:

        sage: R.<x,y> = QQ[]
        sage: x, y = R.gens()
        sage: f = x**2 - y**2
        sage: M = MatrixSpace(QQ, 2)
        sage: A = M([1,2,3,4])
        sage: A.act_on_polynomial(f)
        -8*x^2 - 20*x*y - 12*y^2

  `add_multiple_of_column`(i, j, s, start_row=0)

    Add s times column j to column i.

    EXAMPLES: We add -1 times the third column to the second column of an integer matrix, remembering to start numbering cols at zero:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.add_multiple_of_column(1,2,-1)
        sage: a
        [ 0 -1  2]
        [ 3 -1  5]

    To add a rational multiple, we first need to change the base ring:

        sage: a = a.change_ring(QQ)
        sage: a.add_multiple_of_column(1,0,1/3)
        sage: a
        [ 0 -1  2]
        [ 3  0  5]

    If not, we get an error message:

        sage: a.add_multiple_of_column(1,0,i)
        Traceback (most recent call last):
        ...
        TypeError: Multiplying column by Symbolic Ring element cannot be done over Rational Field, use change_ring or with_added_multiple_of_column instead.

  `add_multiple_of_row`(i, j, s, start_col=0)

    Add s times row j to row i.

    EXAMPLES: We add -3 times the first row to the second row of an integer matrix, remembering to start numbering rows at zero:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.add_multiple_of_row(1,0,-3)
        sage: a
        [ 0  1  2]
        [ 3  1 -1]

    To add a rational multiple, we first need to change the base ring:

        sage: a = a.change_ring(QQ)
        sage: a.add_multiple_of_row(1,0,1/3)
        sage: a
        [   0    1    2]
        [   3  4/3 -1/3]

    If not, we get an error message:

        sage: a.add_multiple_of_row(1,0,i)
        Traceback (most recent call last):
        ...
        TypeError: Multiplying row by Symbolic Ring element cannot be done over Rational Field, use change_ring or with_added_multiple_of_row instead.

  `anticommutator`(other)

    Return the anticommutator `self` and `other`.

    The anticommutator of two \(n \times n\) matrices \(A\) and \(B\) is defined as \(\{A, B\} := AB + BA\) (sometimes this is written as \([A, B]_+\)).

    EXAMPLES:

        sage: A = Matrix(ZZ, 2, 2, range(4))
        sage: B = Matrix(ZZ, 2, 2, [0, 1, 0, 0])
        sage: A.anticommutator(B)
        [2 3]
        [0 2]
        sage: A.anticommutator(B) == B.anticommutator(A)
        True
        sage: A.commutator(B) + B.anticommutator(A) == 2*A*B
        True

  `base_ring`()

    Returns the base ring of the matrix.

    EXAMPLES:

        sage: m=matrix(QQ,2,[1,2,3,4])
        sage: m.base_ring()
        Rational Field

  `change_ring`(ring)

    Return the matrix obtained by coercing the entries of this matrix into the given ring.

    Always returns a copy (unless self is immutable, in which case returns self).

    EXAMPLES:

        sage: A = Matrix(QQ, 2, 2, [1/2, 1/3, 1/3, 1/4])
        sage: A.parent()
         Full MatrixSpace of 2 by 2 dense matrices over Rational Field
        sage: A.change_ring(GF(25,'a'))
        [3 2]
        [2 4]
        sage: A.change_ring(GF(25,'a')).parent()
         Full MatrixSpace of 2 by 2 dense matrices over Finite Field in a of size 5^2
        sage: A.change_ring(ZZ)
        Traceback (most recent call last):
        ...
        TypeError: matrix has denominators so can't change to ZZ.

    Changing rings preserves subdivisions:

        sage: A.subdivide([1], []); A
        [1/2 1/3]
        [-------]
        [1/3 1/4]
        sage: A.change_ring(GF(25,'a'))
        [3 2]
        [---]
        [2 4]

  `commutator`(other)

    Return the commutator self*other - other*self.

    EXAMPLES:

        sage: A = Matrix(ZZ, 2, 2, range(4))
        sage: B = Matrix(ZZ, 2, 2, [0, 1, 0, 0])
        sage: A.commutator(B)
        [-2 -3]
        [ 0  2]
        sage: A.commutator(B) == -B.commutator(A)
        True

  `dict`()

    Dictionary of the elements of self with keys pairs (i,j) and values the nonzero entries of self.

    It is safe to change the returned dictionary.

    EXAMPLES:

        sage: R.<x,y> = QQ[]
        sage: a = matrix(R,2,[x,y,0, 0,0,2*x+y]); a
        [      x       y       0]
        [      0       0 2*x + y]
        sage: d = a.dict(); d
        {(0, 0): x, (0, 1): y, (1, 2): 2*x + y}

    Notice that changing the returned list does not change a (the list is a copy):

        sage: d[0,0] = 25
        sage: a
        [      x       y       0]
        [      0       0 2*x + y]

  `dimensions`()

    Returns the dimensions of this matrix as the tuple (nrows, ncols).

    EXAMPLES:

        sage: M = matrix([[1,2,3],[4,5,6]])
        sage: N = M.transpose()
        sage: M.dimensions()
        (2, 3)
        sage: N.dimensions()
        (3, 2)

    AUTHORS:

    - Benjamin Lundell (2012-02-09): examples
  `is_alternating`()

    Return `True` if `self` is an alternating matrix.

    Here, “alternating matrix” means a square matrix \(A\) satisfying \(A^T = -A\) and such that the diagonal entries of \(A\) are \(0\). Notice that the condition that the diagonal entries be \(0\) is not redundant for matrices over arbitrary ground rings (but it is redundant when \(2\) is invertible in the ground ring). A square matrix \(A\) only required to satisfy \(A^T = -A\) is said to be “skew-symmetric”, and this property is checked by the `is_skew_symmetric()` method.

    EXAMPLES:

        sage: m = matrix(QQ, [[0,2], [-2,0]])
        sage: m.is_alternating()
        True
        sage: m = matrix(QQ, [[1,2], [2,1]])
        sage: m.is_alternating()
        False

    In contrast to the property of being skew-symmetric, the property of being alternating does not tolerate nonzero entries on the diagonal even if they are their own negatives:

        sage: n = matrix(Zmod(4), [[0, 1], [-1, 2]])
        sage: n.is_alternating()
        False

  `is_dense`()

    Returns True if this is a dense matrix.

    In Sage, being dense is a property of the underlying representation, not the number of nonzero entries.

    EXAMPLES:

        sage: matrix(QQ,2,2,range(4)).is_dense()
        True
        sage: matrix(QQ,2,2,range(4),sparse=True).is_dense()
        False

  `is_hermitian`()

    Returns `True` if the matrix is equal to its conjugate-transpose.

    OUTPUT:

    `True` if the matrix is square and equal to the transpose with every entry conjugated, and `False` otherwise.

    Note that if conjugation has no effect on elements of the base ring (such as for integers), then the `is_symmetric()` method is equivalent and faster.

    This routine is for matrices over exact rings and so may not work properly for matrices over `RR` or `CC`. For matrices with approximate entries, the rings of double-precision floating-point numbers, `RDF` and `CDF`, are a better choice since the `sage.matrix.matrix_double_dense.Matrix_double_dense.is_hermitian()` method has a tolerance parameter. This provides control over allowing for minor discrepancies between entries when checking equality.

    The result is cached.

    EXAMPLES:

        sage: A = matrix(QQbar, [[ 1 + I,  1 - 6*I, -1 - I],
        ...                      [-3 - I,     -4*I,     -2],
        ...                      [-1 + I, -2 - 8*I,  2 + I]])
        sage: A.is_hermitian()
        False
        sage: B = A*A.conjugate_transpose()
        sage: B.is_hermitian()
        True

    Sage has several fields besides the entire complex numbers where conjugation is non-trivial.

        sage: F.<b> = QuadraticField(-7)
        sage: C = matrix(F, [[-2*b - 3,  7*b - 6, -b + 3],
        ...                  [-2*b - 3, -3*b + 2,   -2*b],
        ...                  [   b + 1,        0,     -2]])
        sage: C.is_hermitian()
        False
        sage: C = C*C.conjugate_transpose()
        sage: C.is_hermitian()
        True

    A matrix that is nearly Hermitian, but for a non-real diagonal entry.

        sage: A = matrix(QQbar, [[    2,   2-I, 1+4*I],
        ...                      [  2+I,   3+I, 2-6*I],
        ...                      [1-4*I, 2+6*I,     5]])
        sage: A.is_hermitian()
        False
        sage: A[1,1] = 132
        sage: A.is_hermitian()
        True

    Rectangular matrices are never Hermitian.

        sage: A = matrix(QQbar, 3, 4)
        sage: A.is_hermitian()
        False

    A square, empty matrix is trivially Hermitian.

        sage: A = matrix(QQ, 0, 0)
        sage: A.is_hermitian()
        True

  `is_immutable`()

    Return True if this matrix is immutable.

    See the documentation for self.set_immutable for more details about mutability.

    EXAMPLES:

        sage: A = Matrix(QQ['t','s'], 2, 2, range(4))
        sage: A.is_immutable()
        False
        sage: A.set_immutable()
        sage: A.is_immutable()
        True

  `is_invertible`()

    Return True if this matrix is invertible.

    EXAMPLES: The following matrix is invertible over \(\QQ\) but not over \(\ZZ\).

        sage: A = MatrixSpace(ZZ, 2)(range(4))
        sage: A.is_invertible()
        False
        sage: A.matrix_over_field().is_invertible()
        True

    The inverse function is a constructor for matrices over the fraction field, so it can work even if A is not invertible.

        sage: ~A   # inverse of A
        [-3/2  1/2]
        [   1    0]

    The next matrix is invertible over \(\ZZ\).

        sage: A = MatrixSpace(IntegerRing(),2)([1,10,0,-1])
        sage: A.is_invertible()
        True
        sage: ~A                # compute the inverse
        [ 1 10]
        [ 0 -1]

    The following nontrivial matrix is invertible over \(\ZZ[x]\).

        sage: R.<x> = PolynomialRing(IntegerRing())
        sage: A = MatrixSpace(R,2)([1,x,0,-1])
        sage: A.is_invertible()
        True
        sage: ~A
        [ 1  x]
        [ 0 -1]

  `is_mutable`()

    Return True if this matrix is mutable.

    See the documentation for self.set_immutable for more details about mutability.

    EXAMPLES:

        sage: A = Matrix(QQ['t','s'], 2, 2, range(4))
        sage: A.is_mutable()
        True
        sage: A.set_immutable()
        sage: A.is_mutable()
        False

  `is_singular`()

    Returns `True` if `self` is singular.

    OUTPUT:

    A square matrix is singular if it has a zero determinant and this method will return `True` in exactly this case. When the entries of the matrix come from a field, this is equivalent to having a nontrivial kernel, or lacking an inverse, or having linearly dependent rows, or having linearly dependent columns.

    For square matrices over a field the methods `is_invertible()` and `is_singular()` are logical opposites. However, it is an error to apply `is_singular()` to a matrix that is not square, while `is_invertible()` will always return `False` for a matrix that is not square.

    EXAMPLES:

    A singular matrix over the field `QQ`.

        sage: A = matrix(QQ, 4, [-1,2,-3,6,0,-1,-1,0,-1,1,-5,7,-1,6,5,2])
        sage: A.is_singular()
        True
        sage: A.right_kernel().dimension()
        1

    A matrix that is not singular, i.e. nonsingular, over a field.

        sage: B = matrix(QQ, 4, [1,-3,-1,-5,2,-5,-2,-7,-2,5,3,4,-1,4,2,6])
        sage: B.is_singular()
        False
        sage: B.left_kernel().dimension()
        0

    For rectangular matrices, invertibility is always `False`, but asking about singularity will give an error.

        sage: C = matrix(QQ, 5, range(30))
        sage: C.is_invertible()
        False
        sage: C.is_singular()
        Traceback (most recent call last):
        ...
        ValueError: self must be a square matrix

    When the base ring is not a field, then a matrix may be both not invertible and not singular.

        sage: D = matrix(ZZ, 4, [2,0,-4,8,2,1,-2,7,2,5,7,0,0,1,4,-6])
        sage: D.is_invertible()
        False
        sage: D.is_singular()
        False
        sage: d = D.determinant(); d
        2
        sage: d.is_unit()
        False

  `is_skew_symmetric`()

    Return `True` if `self` is a skew-symmetric matrix.

    Here, “skew-symmetric matrix” means a square matrix \(A\) satisfying \(A^T = -A\). It does not require that the diagonal entries of \(A\) are \(0\) (although this automatically follows from \(A^T = -A\) when \(2\) is invertible in the ground ring over which the matrix is considered). Skew-symmetric matrices \(A\) whose diagonal entries are \(0\) are said to be “alternating”, and this property is checked by the `is_alternating()` method.

    EXAMPLES:

        sage: m = matrix(QQ, [[0,2], [-2,0]])
        sage: m.is_skew_symmetric()
        True
        sage: m = matrix(QQ, [[1,2], [2,1]])
        sage: m.is_skew_symmetric()
        False

    Skew-symmetric is not the same as alternating when \(2\) is a zero-divisor in the ground ring:

        sage: n = matrix(Zmod(4), [[0, 1], [-1, 2]])
        sage: n.is_skew_symmetric()
        True

    but yet the diagonal cannot be completely arbitrary in this case:

        sage: n = matrix(Zmod(4), [[0, 1], [-1, 3]])
        sage: n.is_skew_symmetric()
        False

  `is_skew_symmetrizable`(return_diag=False, positive=True)

    This function takes a square matrix over an ordered integral domain and checks if it is skew-symmetrizable. A matrix \(B\) is skew-symmetrizable iff there exists an invertible diagonal matrix \(D\) such that \(DB\) is skew-symmetric.

    Warning

    Expects `self` to be a matrix over an ordered integral domain.

    INPUT:

    - `return_diag` – bool(default:False) if True and `self` is skew-symmetrizable the diagonal entries of the matrix \(D\) are returned.
    - `positive` – bool(default:True) if True, the condition that \(D\) has positive entries is added.

    OUTPUT:

    - True – if `self` is skew-symmetrizable and `return_diag` is False
    - the diagonal entries of a matrix \(D\) such that \(DB\) is skew-symmetric – iff `self` is skew-symmetrizable and `return_diag` is True
    - False – iff `self` is not skew-symmetrizable

    EXAMPLES:

        sage: matrix([[0,6],[3,0]]).is_skew_symmetrizable(positive=False)
        True
        sage: matrix([[0,6],[3,0]]).is_skew_symmetrizable(positive=True)
        False

        sage: M = matrix(4,[0,1,0,0,-1,0,-1,0,0,2,0,1,0,0,-1,0]); M
        [ 0  1  0  0]
        [-1  0 -1  0]
        [ 0  2  0  1]
        [ 0  0 -1  0]

        sage: M.is_skew_symmetrizable(return_diag=True)
        [1, 1, 1/2, 1/2]

        sage: M2 = diagonal_matrix([1,1,1/2,1/2])*M; M2
        [   0    1    0    0]
        [  -1    0   -1    0]
        [   0    1    0  1/2]
        [   0    0 -1/2    0]

        sage: M2.is_skew_symmetric()
        True

    REFERENCES:

    - [FZ2001] S. Fomin, A. Zelevinsky. Cluster Algebras 1: Foundations, arXiv:math/0104151 (2001).
  `is_sparse`()

    Return True if this is a sparse matrix.

    In Sage, being sparse is a property of the underlying representation, not the number of nonzero entries.

    EXAMPLES:

        sage: matrix(QQ,2,2,range(4)).is_sparse()
        False
        sage: matrix(QQ,2,2,range(4),sparse=True).is_sparse()
        True

  `is_square`()

    Return True precisely if this matrix is square, i.e., has the same number of rows and columns.

    EXAMPLES:

        sage: matrix(QQ,2,2,range(4)).is_square()
        True
        sage: matrix(QQ,2,3,range(6)).is_square()
        False

  `is_symmetric`()

    Returns True if this is a symmetric matrix.

    EXAMPLES:

        sage: m=Matrix(QQ,2,range(0,4))
        sage: m.is_symmetric()
        False

        sage: m=Matrix(QQ,2,(1,1,1,1,1,1))
        sage: m.is_symmetric()
        False

        sage: m=Matrix(QQ,1,(2,))
        sage: m.is_symmetric()
        True

  `is_symmetrizable`(return_diag=False, positive=True)

    This function takes a square matrix over an ordered integral domain and checks if it is symmetrizable. A matrix \(B\) is symmetrizable iff there exists an invertible diagonal matrix \(D\) such that \(DB\) is symmetric.

    Warning

    Expects `self` to be a matrix over an ordered integral domain.

    INPUT:

    - `return_diag` – bool(default:False) if True and `self` is symmetrizable the diagonal entries of the matrix \(D\) are returned.
    - `positive` – bool(default:True) if True, the condition that \(D\) has positive entries is added.

    OUTPUT:

    - True – if `self` is symmetrizable and `return_diag` is False
    - the diagonal entries of a matrix \(D\) such that \(DB\) is symmetric – iff `self` is symmetrizable and `return_diag` is True
    - False – iff `self` is not symmetrizable

    EXAMPLES:

        sage: matrix([[0,6],[3,0]]).is_symmetrizable(positive=False)
        True

        sage: matrix([[0,6],[3,0]]).is_symmetrizable(positive=True)
        True

        sage: matrix([[0,6],[0,0]]).is_symmetrizable(return_diag=True)
        False

        sage: matrix([2]).is_symmetrizable(positive=True)
        True

        sage: matrix([[1,2],[3,4]]).is_symmetrizable(return_diag=true)
        [1, 2/3]

    REFERENCES:

    - [FZ2001] S. Fomin, A. Zelevinsky. Cluster Algebras 1: Foundations, arXiv:math/0104151 (2001).
  `is_weak_popov`()

    Return `True` if the matrix is in weak Popov form.

    OUTPUT:

    A matrix over an ordered ring is in weak Popov form if all leading positions are different [MulSto]. A leading position is the position \(i\) in a row with the highest order (for polynomials this is the degree), for multiple entries with equal but highest order the maximal \(i\) is chosen (which is the furthest to the right in the matrix).

    Warning

    This implementation only works for objects implementing a degree function. It is designed to work for polynomials.

    EXAMPLES:

    A matrix with the same leading position in two rows is not in weak Popov form.

        sage: PF = PolynomialRing(GF(2^12,'a'),'x')
        sage: A = matrix(PF,3,[x,x^2,x^3,x^2,x^2,x^2,x^3,x^2,x])
        sage: A.is_weak_popov()
        False

    If a matrix has different leading positions, it is in weak Popov form.

        sage: B = matrix(PF,3,[1,1,x^3,x^2,1,1,1,x^2,1])
        sage: B.is_weak_popov()
        True

    A matrix not over a polynomial ring will give an error.

        sage: C = matrix(ZZ,4,[-1, 1, 0, 0, 7, 2, 1, 0, 1, 0, 2, -5, -1, 1, 0, 2])
        sage: C.is_weak_popov()
        Traceback (most recent call last):
        ...
        NotImplementedError: is_weak_popov only implements support for matrices ordered by a function self[x,y].degree()

    Weak Popov form is not restricted to square matrices.

        sage: PF = PolynomialRing(GF(7),'x')
        sage: D = matrix(PF,2,4,[x^2+1,1,2,x,3*x+2,0,0,0])
        sage: D.is_weak_popov()
        False

    Even a matrix with more rows than cols can still be in weak Popov form.

        sage: E = matrix(PF,4,2,[4*x^3+x,x^2+5*x+2,0,0,4,x,0,0])
        sage: E.is_weak_popov()
        True

    But a matrix with less cols than non zero rows is never in weak Popov form.

        sage: F = matrix(PF,3,2,[x^2,x,x^3+2,x,4,5])
        sage: F.is_weak_popov()
        False

    TESTS:

    A matrix to check if really the rightmost value is taken.

        sage: F = matrix(PF,2,2,[x^2,x^2,x,5])
        sage: F.is_weak_popov()
        True

    See also

    - `weak_popov_form`

    REFERENCES:

    [MulSto] | T. Mulders, A. Storjohann, “On lattice reduction for polynomial matrices”, J. Symbolic Comput. 35 (2003), no. 4, 377–401

    AUTHOR:

    - David Moedinger (2014-07-30)
  `iterates`(v, n, rows=True)

    Let \(A\) be this matrix and \(v\) be a free module element. If rows is True, return a matrix whose rows are the entries of the following vectors:

    \[v, v A, v A^2, \ldots, v A^{n-1}.\]

    If rows is False, return a matrix whose columns are the entries of the following vectors:

    \[v, Av, A^2 v, \ldots, A^{n-1} v.\]

    INPUT:

    - `v` - free module element
    - `n` - nonnegative integer

    EXAMPLES:

        sage: A = matrix(ZZ,2, [1,1,3,5]); A
        [1 1]
        [3 5]
        sage: v = vector([1,0])
        sage: A.iterates(v,0)
        []
        sage: A.iterates(v,5)
        [  1   0]
        [  1   1]
        [  4   6]
        [ 22  34]
        [124 192]

    Another example:

        sage: a = matrix(ZZ,3,range(9)); a
        [0 1 2]
        [3 4 5]
        [6 7 8]
        sage: v = vector([1,0,0])
        sage: a.iterates(v,4)
        [  1   0   0]
        [  0   1   2]
        [ 15  18  21]
        [180 234 288]
        sage: a.iterates(v,4,rows=False)
        [  1   0  15 180]
        [  0   3  42 558]
        [  0   6  69 936]

  `linear_combination_of_columns`(v)

    Return the linear combination of the columns of `self` given by the coefficients in the list `v`.

    INPUT:

    - `v` - a list of scalars. The length can be less than the number of columns of `self` but not greater.

    OUTPUT:

    The vector (or free module element) that is a linear combination of the columns of `self`. If the list of scalars has fewer entries than the number of columns, additional zeros are appended to the list until it has as many entries as the number of columns.

    EXAMPLES:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.linear_combination_of_columns([1,1,1])
        (3, 12)

        sage: a.linear_combination_of_columns([0,0,0])
        (0, 0)

        sage: a.linear_combination_of_columns([1/2,2/3,3/4])
        (13/6, 95/12)

    The list `v` can be anything that is iterable. Perhaps most naturally, a vector may be used.

        sage: v = vector(ZZ, [1,2,3])
        sage: a.linear_combination_of_columns(v)
        (8, 26)

    We check that a matrix with no columns behaves properly.

        sage: matrix(QQ,2,0).linear_combination_of_columns([])
        (0, 0)

    The object returned is a vector, or a free module element.

        sage: B = matrix(ZZ, 4, 3, range(12))
        sage: w = B.linear_combination_of_columns([-1,2,-3])
        sage: w
        (-4, -10, -16, -22)
        sage: w.parent()
        Ambient free module of rank 4 over the principal ideal domain Integer Ring
        sage: x = B.linear_combination_of_columns([1/2,1/3,1/4])
        sage: x
        (5/6, 49/12, 22/3, 127/12)
        sage: x.parent()
        Vector space of dimension 4 over Rational Field

    The length of v can be less than the number of columns, but not greater.

        sage: A = matrix(QQ,3,5, range(15))
        sage: A.linear_combination_of_columns([1,-2,3,-4])
        (-8, -18, -28)
        sage: A.linear_combination_of_columns([1,2,3,4,5,6])
        Traceback (most recent call last):
        ...
        ValueError: length of v must be at most the number of columns of self

  `linear_combination_of_rows`(v)

    Return the linear combination of the rows of `self` given by the coefficients in the list `v`.

    INPUT:

    - `v` - a list of scalars. The length can be less than the number of rows of `self` but not greater.

    OUTPUT:

    The vector (or free module element) that is a linear combination of the rows of `self`. If the list of scalars has fewer entries than the number of rows, additional zeros are appended to the list until it has as many entries as the number of rows.

    EXAMPLES:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.linear_combination_of_rows([1,2])
        (6, 9, 12)

        sage: a.linear_combination_of_rows([0,0])
        (0, 0, 0)

        sage: a.linear_combination_of_rows([1/2,2/3])
        (2, 19/6, 13/3)

    The list `v` can be anything that is iterable. Perhaps most naturally, a vector may be used.

        sage: v = vector(ZZ, [1,2])
        sage: a.linear_combination_of_rows(v)
        (6, 9, 12)

    We check that a matrix with no rows behaves properly.

        sage: matrix(QQ,0,2).linear_combination_of_rows([])
        (0, 0)

    The object returned is a vector, or a free module element.

        sage: B = matrix(ZZ, 4, 3, range(12))
        sage: w = B.linear_combination_of_rows([-1,2,-3,4])
        sage: w
        (24, 26, 28)
        sage: w.parent()
        Ambient free module of rank 3 over the principal ideal domain Integer Ring
        sage: x = B.linear_combination_of_rows([1/2,1/3,1/4,1/5])
        sage: x
        (43/10, 67/12, 103/15)
        sage: x.parent()
        Vector space of dimension 3 over Rational Field

    The length of v can be less than the number of rows, but not greater.

        sage: A = matrix(QQ,3,4,range(12))
        sage: A.linear_combination_of_rows([2,3])
        (12, 17, 22, 27)
        sage: A.linear_combination_of_rows([1,2,3,4])
        Traceback (most recent call last):
        ...
        ValueError: length of v must be at most the number of rows of self

  `list`()

    List of the elements of `self` ordered by elements in each row. It is safe to change the returned list.

    Warning

    This function returns a list of the entries in the matrix `self`. It does not return a list of the rows of `self`, so it is different than the output of `list(self)`, which returns `[self[0],self[1],...]`.

    EXAMPLES:

        sage: R.<x,y> = QQ[]
        sage: a = matrix(R,2,[x,y,x*y, y,x,2*x+y]); a
        [      x       y     x*y]
        [      y       x 2*x + y]
        sage: v = a.list(); v
        [x, y, x*y, y, x, 2*x + y]

    Note that list(a) is different than a.list():

        sage: a.list()
        [x, y, x*y, y, x, 2*x + y]
        sage: list(a)
        [(x, y, x*y), (y, x, 2*x + y)]

    Notice that changing the returned list does not change a (the list is a copy):

        sage: v[0] = 25
        sage: a
        [      x       y     x*y]
        [      y       x 2*x + y]

  `mod`(p)

    Return matrix mod \(p\), over the reduced ring.

    EXAMPLES:

        sage: M = matrix(ZZ, 2, 2, [5, 9, 13, 15])
        sage: M.mod(7)
        [5 2]
        [6 1]
        sage: parent(M.mod(7))
        Full MatrixSpace of 2 by 2 dense matrices over Ring of integers modulo 7

  `multiplicative_order`()

    Return the multiplicative order of this matrix, which must therefore be invertible.

    EXAMPLES:

        sage: A = matrix(GF(59),3,[10,56,39,53,56,33,58,24,55])
        sage: A.multiplicative_order()
        580
        sage: (A^580).is_one()
        True

        sage: B = matrix(GF(10007^3,'b'),0)
        sage: B.multiplicative_order()
        1

        sage: C = matrix(GF(2^10,'c'),2,3,[1]*6)
        sage: C.multiplicative_order()
        Traceback (most recent call last):
        ...
        ArithmeticError: self must be invertible ...

        sage: D = matrix(IntegerModRing(6),3,[5,5,3,0,2,5,5,4,0])
        sage: D.multiplicative_order()
        Traceback (most recent call last):
        ...
        NotImplementedError: ... only ... over finite fields

        sage: E = MatrixSpace(GF(11^2,'e'),5).random_element()
        sage: (E^E.multiplicative_order()).is_one()
        True

    REFERENCES:

    - Frank Celler and C. R. Leedham-Green, “Calculating the Order of an Invertible Matrix”, 1997
  `mutate`(k)

    Mutates `self` at row and column index `k`.

    Warning

    Only makes sense if `self` is skew-symmetrizable.

    INPUT:

    - `k` – integer at which row/column `self` is mutated.

    EXAMPLES:

    Mutation of the B-matrix of the quiver of type \(A_3\):

        sage: M = matrix(ZZ,3,[0,1,0,-1,0,-1,0,1,0]); M
        [ 0  1  0]
        [-1  0 -1]
        [ 0  1  0]

        sage: M.mutate(0); M
        [ 0 -1  0]
        [ 1  0 -1]
        [ 0  1  0]

        sage: M.mutate(1); M
        [ 0  1 -1]
        [-1  0  1]
        [ 1 -1  0]

        sage: M = matrix(ZZ,6,[0,1,0,-1,0,-1,0,1,0,1,0,0,0,1,0,0,0,1]); M
        [ 0  1  0]
        [-1  0 -1]
        [ 0  1  0]
        [ 1  0  0]
        [ 0  1  0]
        [ 0  0  1]

        sage: M.mutate(0); M
        [ 0 -1  0]
        [ 1  0 -1]
        [ 0  1  0]
        [-1  1  0]
        [ 0  1  0]
        [ 0  0  1]

    REFERENCES:

    - [FZ2001] S. Fomin, A. Zelevinsky. Cluster Algebras 1: Foundations, arXiv:math/0104151 (2001).
  `ncols`()

    Return the number of columns of this matrix.

    EXAMPLES:

        sage: M = MatrixSpace(QQ, 2, 3)
        sage: A = M([1,2,3, 4,5,6])
        sage: A
        [1 2 3]
        [4 5 6]
        sage: A.ncols()
        3
        sage: A.nrows()
        2

    AUTHORS:

    - Naqi Jaffery (2006-01-24): examples
  `nonpivots`()

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

    OUTPUT: sorted tuple of (Python) integers

    EXAMPLES:

        sage: a = matrix(QQ,3,3,range(9)); a
        [0 1 2]
        [3 4 5]
        [6 7 8]
        sage: a.echelon_form()
        [ 1  0 -1]
        [ 0  1  2]
        [ 0  0  0]
        sage: a.nonpivots()
        (2,)

  `nonzero_positions`(copy=True, column_order=False)

    Returns the sorted list of pairs (i,j) such that self[i,j] != 0.

    INPUT:

    - `copy` - (default: True) It is safe to change the resulting list (unless you give the option copy=False).
    - `column_order` - (default: False) If true, returns the list of pairs (i,j) such that self[i,j] != 0, but sorted by columns, i.e., column j=0 entries occur first, then column j=1 entries, etc.

    EXAMPLES:

        sage: a = matrix(QQ, 2,3, [1,2,0,2,0,0]); a
        [1 2 0]
        [2 0 0]
        sage: a.nonzero_positions()
        [(0, 0), (0, 1), (1, 0)]
        sage: a.nonzero_positions(copy=False)
        [(0, 0), (0, 1), (1, 0)]
        sage: a.nonzero_positions(column_order=True)
        [(0, 0), (1, 0), (0, 1)]
        sage: a = matrix(QQ, 2,3, [1,2,0,2,0,0], sparse=True); a
        [1 2 0]
        [2 0 0]
        sage: a.nonzero_positions()
        [(0, 0), (0, 1), (1, 0)]
        sage: a.nonzero_positions(copy=False)
        [(0, 0), (0, 1), (1, 0)]
        sage: a.nonzero_positions(column_order=True)
        [(0, 0), (1, 0), (0, 1)]

  `nonzero_positions_in_column`(i)

    Return a sorted list of the integers j such that self[j,i] is nonzero, i.e., such that the j-th position of the i-th column is nonzero.

    INPUT:

    - `i` - an integer

    OUTPUT: list

    EXAMPLES:

        sage: a = matrix(QQ, 3,2, [1,2,0,2,0,0]); a
        [1 2]
        [0 2]
        [0 0]
        sage: a.nonzero_positions_in_column(0)
        [0]
        sage: a.nonzero_positions_in_column(1)
        [0, 1]

    You’ll get an IndexError, if you select an invalid column:

        sage: a.nonzero_positions_in_column(2)
        Traceback (most recent call last):
        ...
        IndexError: matrix column index out of range

  `nonzero_positions_in_row`(i)

    Return the integers j such that self[i,j] is nonzero, i.e., such that the j-th position of the i-th row is nonzero.

    INPUT:

    - `i` - an integer

    OUTPUT: list

    EXAMPLES:

        sage: a = matrix(QQ, 3,2, [1,2,0,2,0,0]); a
        [1 2]
        [0 2]
        [0 0]
        sage: a.nonzero_positions_in_row(0)
        [0, 1]
        sage: a.nonzero_positions_in_row(1)
        [1]
        sage: a.nonzero_positions_in_row(2)
        []

  `nrows`()

    Return the number of rows of this matrix.

    EXAMPLES:

        sage: M = MatrixSpace(QQ,6,7)
        sage: A = M([1,2,3,4,5,6,7, 22,3/4,34,11,7,5,3, 99,65,1/2,2/3,3/5,4/5,5/6, 9,8/9, 9/8,7/6,6/7,76,4, 0,9,8,7,6,5,4, 123,99,91,28,6,1024,1])
        sage: A
        [   1    2    3    4    5    6    7]
        [  22  3/4   34   11    7    5    3]
        [  99   65  1/2  2/3  3/5  4/5  5/6]
        [   9  8/9  9/8  7/6  6/7   76    4]
        [   0    9    8    7    6    5    4]
        [ 123   99   91   28    6 1024    1]
        sage: A.ncols()
        7
        sage: A.nrows()
        6

    AUTHORS:

    - Naqi Jaffery (2006-01-24): examples
  `permute_columns`(permutation)

    Permute the columns of `self` by applying the permutation group element `permutation`.

    As a permutation group element acts on integers \(\{1, \hdots, n\}\) the columns are considered as being numbered from 1 for this operation.

    INPUT:

    - `permutation` – a `PermutationGroupElement`.

    EXAMPLE: We create a matrix:

        sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
        sage: M
        [1 0 0 0 0]
        [0 2 0 0 0]
        [0 0 3 0 0]
        [0 0 0 4 0]
        [0 0 0 0 5]

    Next of all, create a permutation group element and act on `M` with it:

        sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
        sage: sigma, tau = G.gens()
        sage: sigma
        (1,2,3)(4,5)
        sage: M.permute_columns(sigma)
        sage: M
        [0 0 1 0 0]
        [2 0 0 0 0]
        [0 3 0 0 0]
        [0 0 0 0 4]
        [0 0 0 5 0]

  `permute_rows`(permutation)

    Permute the rows of `self` by applying the permutation group element `permutation`.

    As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows are considered as being numbered from 1 for this operation.

    INPUT:

    - `permutation` – a `PermutationGroupElement`

    EXAMPLE: We create a matrix:

        sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
        sage: M
        [1 0 0 0 0]
        [0 2 0 0 0]
        [0 0 3 0 0]
        [0 0 0 4 0]
        [0 0 0 0 5]

    Next of all, create a permutation group element and act on `M`:

        sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
        sage: sigma, tau = G.gens()
        sage: sigma
        (1,2,3)(4,5)
        sage: M.permute_rows(sigma)
        sage: M
        [0 2 0 0 0]
        [0 0 3 0 0]
        [1 0 0 0 0]
        [0 0 0 0 5]
        [0 0 0 4 0]

  `permute_rows_and_columns`(row_permutation, column_permutation)

    Permute the rows and columns of `self` by applying the permutation group elements `row_permutation` and `column_permutation` respectively.

    As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows and columns are considered as being numbered from 1 for this operation.

    INPUT:

    - `row_permutation` – a `PermutationGroupElement`
    - `column_permutation` – a `PermutationGroupElement`

    OUTPUT:

    - A matrix.

    EXAMPLE: We create a matrix:

        sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
        sage: M
        [1 0 0 0 0]
        [0 2 0 0 0]
        [0 0 3 0 0]
        [0 0 0 4 0]
        [0 0 0 0 5]

    Next of all, create a permutation group element and act on `M`:

        sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
        sage: sigma, tau = G.gens()
        sage: sigma
        (1,2,3)(4,5)
        sage: M.permute_rows_and_columns(sigma,tau)
        sage: M
        [2 0 0 0 0]
        [0 3 0 0 0]
        [0 0 0 0 1]
        [0 0 0 5 0]
        [0 0 4 0 0]

  `pivots`()

    Return the pivot column positions of this matrix.

    OUTPUT: a tuple of Python integers: the position of the first nonzero entry in each row of the echelon form.

    This returns a tuple so it is immutable; see #10752.

    EXAMPLES:

        sage: A = matrix(QQ, 2, 2, range(4))
        sage: A.pivots()
        (0, 1)

  `rank`()

    TESTS:

    We should be able to compute the rank of a matrix whose entries are polynomials over a finite field (trac #5014):

        sage: P.<x> = PolynomialRing(GF(17))
        sage: m = matrix(P, [ [ 6*x^2 + 8*x + 12, 10*x^2 + 4*x + 11],
        ...                   [8*x^2 + 12*x + 15,  8*x^2 + 9*x + 16] ])
        sage: m.rank()
        2

  `rescale_col`(i, s, start_row=0)

    Replace i-th col of self by s times i-th col of self.

    INPUT:

    - `i` - ith column
    - `s` - scalar
    - `start_row` - only rescale entries at this row and lower

    EXAMPLES: We rescale the last column of a matrix over the rational numbers:

        sage: a = matrix(QQ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.rescale_col(2,1/2); a
        [  0   1   1]
        [  3   4 5/2]
        sage: R.<x> = QQ[]

    We rescale the last column of a matrix over a polynomial ring:

        sage: a = matrix(R,2,3,[1,x,x^2,x^3,x^4,x^5]); a
        [  1   x x^2]
        [x^3 x^4 x^5]
        sage: a.rescale_col(2,1/2); a
        [      1       x 1/2*x^2]
        [    x^3     x^4 1/2*x^5]

    We try and fail to rescale a matrix over the integers by a non-integer:

        sage: a = matrix(ZZ,2,3,[0,1,2, 3,4,4]); a
        [0 1 2]
        [3 4 4]
        sage: a.rescale_col(2,1/2)
        Traceback (most recent call last):
        ...
        TypeError: Rescaling column by Rational Field element cannot be done over Integer Ring, use change_ring or with_rescaled_col instead.

    To rescale the matrix by 1/2, you must change the base ring to the rationals:

        sage: a = a.change_ring(QQ); a
        [0 1 2]
        [3 4 4]
        sage: a.rescale_col(2,1/2); a
        [0 1 1]
        [3 4 2]

  `rescale_row`(i, s, start_col=0)

    Replace i-th row of self by s times i-th row of self.

    INPUT:

    - `i` - ith row
    - `s` - scalar
    - `start_col` - only rescale entries at this column and to the right

    EXAMPLES: We rescale the second row of a matrix over the rational numbers:

        sage: a = matrix(QQ,3,range(6)); a
        [0 1]
        [2 3]
        [4 5]
        sage: a.rescale_row(1,1/2); a
        [ 0   1]
        [ 1 3/2]
        [ 4   5]

    We rescale the second row of a matrix over a polynomial ring:

        sage: R.<x> = QQ[]
        sage: a = matrix(R,3,[1,x,x^2,x^3,x^4,x^5]);a
        [  1   x]
        [x^2 x^3]
        [x^4 x^5]
        sage: a.rescale_row(1,1/2); a
        [      1       x]
        [1/2*x^2 1/2*x^3]
        [    x^4     x^5]

    We try and fail to rescale a matrix over the integers by a non-integer:

        sage: a = matrix(ZZ,2,3,[0,1,2, 3,4,4]); a
        [0 1 2]
        [3 4 4]
        sage: a.rescale_row(1,1/2)
        Traceback (most recent call last):
        ...
        TypeError: Rescaling row by Rational Field element cannot be done over Integer Ring, use change_ring or with_rescaled_row instead.

    To rescale the matrix by 1/2, you must change the base ring to the rationals:

        sage: a = a.change_ring(QQ); a
        [0 1 2]
        [3 4 4]
        sage: a.rescale_col(1,1/2); a
        [  0 1/2   2]
        [  3   2   4]

  `set_col_to_multiple_of_col`(i, j, s)

    Set column i equal to s times column j.

    EXAMPLES: We change the second column to -3 times the first column.

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.set_col_to_multiple_of_col(1,0,-3)
        sage: a
        [ 0  0  2]
        [ 3 -9  5]

    If we try to multiply a column by a rational number, we get an error message:

        sage: a.set_col_to_multiple_of_col(1,0,1/2)
        Traceback (most recent call last):
        ...
        TypeError: Multiplying column by Rational Field element cannot be done over Integer Ring, use change_ring or with_col_set_to_multiple_of_col instead.

  `set_immutable`()

    Call this function to set the matrix as immutable.

    Matrices are always mutable by default, i.e., you can change their entries using `A[i,j] = x`. However, mutable matrices aren’t hashable, so can’t be used as keys in dictionaries, etc. Also, often when implementing a class, you might compute a matrix associated to it, e.g., the matrix of a Hecke operator. If you return this matrix to the user you’re really returning a reference and the user could then change an entry; this could be confusing. Thus you should set such a matrix immutable.

    EXAMPLES:

        sage: A = Matrix(QQ, 2, 2, range(4))
        sage: A.is_mutable()
        True
        sage: A[0,0] = 10
        sage: A
        [10   1]
        [ 2   3]

    Mutable matrices are not hashable, so can’t be used as keys for dictionaries:

        sage: hash(A)
        Traceback (most recent call last):
        ...
        TypeError: mutable matrices are unhashable
        sage: v = {A:1}
        Traceback (most recent call last):
        ...
        TypeError: mutable matrices are unhashable

    If we make A immutable it suddenly is hashable.

        sage: A.set_immutable()
        sage: A.is_mutable()
        False
        sage: A[0,0] = 10
        Traceback (most recent call last):
        ...
        ValueError: matrix is immutable; please change a copy instead (i.e., use copy(M) to change a copy of M).
        sage: hash(A) #random
        12
        sage: v = {A:1}; v
        {[10  1]
         [ 2  3]: 1}

  `set_row_to_multiple_of_row`(i, j, s)

    Set row i equal to s times row j.

    EXAMPLES: We change the second row to -3 times the first row:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: a.set_row_to_multiple_of_row(1,0,-3)
        sage: a
        [ 0  1  2]
        [ 0 -3 -6]

    If we try to multiply a row by a rational number, we get an error message:

        sage: a.set_row_to_multiple_of_row(1,0,1/2)
        Traceback (most recent call last):
        ...
        TypeError: Multiplying row by Rational Field element cannot be done over Integer Ring, use change_ring or with_row_set_to_multiple_of_row instead.

  `str`(rep_mapping=None, zero=None, plus_one=None, minus_one=None)

    Return a nice string representation of the matrix.

    INPUT:

    - `rep_mapping` - a dictionary or callable used to override the usual representation of elements.

      If `rep_mapping` is a dictionary then keys should be elements of the base ring and values the desired string representation. Values sent in via the other keyword arguments will override values in the dictionary. Use of a dictionary can potentially take a very long time due to the need to hash entries of the matrix. Matrices with entries from `QQbar` are one example.

      If `rep_mapping` is callable then it will be called with elements of the matrix and must return a string. Simply call `repr()` on elements which should have the default representation.

    - `zero` - string (default: `None`); if not `None` use the value of `zero` as the representation of the zero element.

    - `plus_one` - string (default: `None`); if not `None` use the value of `plus_one` as the representation of the one element.

    - `minus_one` - string (default: `None`); if not `None` use the value of `minus_one` as the representation of the negative of the one element.

    EXAMPLES:

        sage: R = PolynomialRing(QQ,6,'z')
        sage: a = matrix(2,3, R.gens())
        sage: a.__repr__()
        '[z0 z1 z2]\n[z3 z4 z5]'

        sage: M = matrix([[1,0],[2,-1]])
        sage: M.str()
        '[ 1  0]\n[ 2 -1]'
        sage: M.str(plus_one='+',minus_one='-',zero='.')
        '[+ .]\n[2 -]'
        sage: M.str({1:"not this one",2:"II"},minus_one="*",plus_one="I")
        '[ I  0]\n[II  *]'

        sage: def print_entry(x):
        ...     if x>0:
        ...         return '+'
        ...     elif x<0:
        ...         return '-'
        ...     else: return '.'
        ...
        sage: M.str(print_entry)
        '[+ .]\n[+ -]'
        sage: M.str(repr)
        '[ 1  0]\n[ 2 -1]'

    TESTS:

    Prior to Trac #11544 this could take a full minute to run (2011).

        sage: A = matrix(QQ, 4, 4, [1, 2, -2, 2, 1, 0, -1, -1, 0, -1, 1, 1, -1, 2, 1/2, 0])
        sage: e = A.eigenvalues()[3]
        sage: K = (A-e).kernel()
        sage: P = K.basis_matrix()
        sage: P.str()
        '[             1.000000000000000? + 0.?e-17*I -2.116651487479748? + 0.0255565807096352?*I -0.2585224251020429? + 0.288602340904754?*I -0.4847545623533090? - 1.871890760086142?*I]'

  `swap_columns`(c1, c2)

    Swap columns c1 and c2 of self.

    EXAMPLES: We create a rational matrix:

        sage: M = MatrixSpace(QQ,3,3)
        sage: A = M([1,9,-7,4/5,4,3,6,4,3])
        sage: A
        [  1   9  -7]
        [4/5   4   3]
        [  6   4   3]

    Since the first column is numbered zero, this swaps the second and third columns:

        sage: A.swap_columns(1,2); A
        [  1  -7   9]
        [4/5   3   4]
        [  6   3   4]

  `swap_rows`(r1, r2)

    Swap rows r1 and r2 of self.

    EXAMPLES: We create a rational matrix:

        sage: M = MatrixSpace(QQ,3,3)
        sage: A = M([1,9,-7,4/5,4,3,6,4,3])
        sage: A
        [  1   9  -7]
        [4/5   4   3]
        [  6   4   3]

    Since the first row is numbered zero, this swaps the first and third rows:

        sage: A.swap_rows(0,2); A
        [  6   4   3]
        [4/5   4   3]
        [  1   9  -7]

  `with_added_multiple_of_column`(i, j, s, start_row=0)

    Add s times column j to column i, returning new matrix.

    EXAMPLES: We add -1 times the third column to the second column of an integer matrix, remembering to start numbering cols at zero:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: b = a.with_added_multiple_of_column(1,2,-1); b
        [ 0 -1  2]
        [ 3 -1  5]

    The original matrix is unchanged:

        sage: a
        [0 1 2]
        [3 4 5]

    Adding a rational multiple is okay, and reassigning a variable is okay:

        sage: a = a.with_added_multiple_of_column(0,1,1/3); a
        [ 1/3    1    2]
        [13/3    4    5]

  `with_added_multiple_of_row`(i, j, s, start_col=0)

    Add s times row j to row i, returning new matrix.

    EXAMPLES: We add -3 times the first row to the second row of an integer matrix, remembering to start numbering rows at zero:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: b = a.with_added_multiple_of_row(1,0,-3); b
        [ 0  1  2]
        [ 3  1 -1]

    The original matrix is unchanged:

        sage: a
        [0 1 2]
        [3 4 5]

    Adding a rational multiple is okay, and reassigning a variable is okay:

        sage: a = a.with_added_multiple_of_row(0,1,1/3); a
        [   1  7/3 11/3]
        [   3    4    5]

  `with_col_set_to_multiple_of_col`(i, j, s)

    Set column i equal to s times column j, returning a new matrix.

    EXAMPLES: We change the second column to -3 times the first column.

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: b = a.with_col_set_to_multiple_of_col(1,0,-3); b
        [ 0  0  2]
        [ 3 -9  5]

    Note that the original matrix is unchanged:

        sage: a
        [0 1 2]
        [3 4 5]

    Adding a rational multiple is okay, and reassigning a variable is okay:

        sage: a = a.with_col_set_to_multiple_of_col(1,0,1/2); a
        [  0   0   2]
        [  3 3/2   5]

  `with_permuted_columns`(permutation)

    Return the matrix obtained from permuting the columns of `self` by applying the permutation group element `permutation`.

    As a permutation group element acts on integers \(\{1,\hdots,n\}\) the columns are considered as being numbered from 1 for this operation.

    INPUT:

    - `permutation`, a `PermutationGroupElement`

    OUTPUT:

    - A matrix.

    EXAMPLE: We create some matrix:

        sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
        sage: M
        [1 0 0 0 0]
        [0 2 0 0 0]
        [0 0 3 0 0]
        [0 0 0 4 0]
        [0 0 0 0 5]

    Next of all, create a permutation group element and act on `M`:

        sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
        sage: sigma, tau = G.gens()
        sage: sigma
        (1,2,3)(4,5)
        sage: M.with_permuted_columns(sigma)
        [0 0 1 0 0]
        [2 0 0 0 0]
        [0 3 0 0 0]
        [0 0 0 0 4]
        [0 0 0 5 0]

  `with_permuted_rows`(permutation)

    Return the matrix obtained from permuting the rows of `self` by applying the permutation group element `permutation`.

    As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows are considered as being numbered from 1 for this operation.

    INPUT:

    - `permutation` – a `PermutationGroupElement`

    OUTPUT:

    - A matrix.

    EXAMPLE: We create a matrix:

        sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
        sage: M
        [1 0 0 0 0]
        [0 2 0 0 0]
        [0 0 3 0 0]
        [0 0 0 4 0]
        [0 0 0 0 5]

    Next of all, create a permutation group element and act on `M`:

        sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
        sage: sigma, tau = G.gens()
        sage: sigma
        (1,2,3)(4,5)
        sage: M.with_permuted_rows(sigma)
        [0 2 0 0 0]
        [0 0 3 0 0]
        [1 0 0 0 0]
        [0 0 0 0 5]
        [0 0 0 4 0]

  `with_permuted_rows_and_columns`(row_permutation, column_permutation)

    Return the matrix obtained from permuting the rows and columns of `self` by applying the permutation group elements `row_permutation` and `column_permutation`.

    As a permutation group element acts on integers \(\{1,\hdots,n\}\) the rows are considered as being numbered from 1 for this operation.

    INPUT:

    - `row_permutation` – a `PermutationGroupElement`
    - `column_permutation` – a `PermutationGroupElement`

    OUTPUT:

    - A matrix.

    EXAMPLE: We create a matrix:

        sage: M = matrix(ZZ,[[1,0,0,0,0],[0,2,0,0,0],[0,0,3,0,0],[0,0,0,4,0],[0,0,0,0,5]])
        sage: M
        [1 0 0 0 0]
        [0 2 0 0 0]
        [0 0 3 0 0]
        [0 0 0 4 0]
        [0 0 0 0 5]

    Next of all, create a permutation group element and act on `M`:

        sage: G = PermutationGroup(['(1,2,3)(4,5)', '(1,2,3,4,5)'])
        sage: sigma, tau = G.gens()
        sage: sigma
        (1,2,3)(4,5)
        sage: M.with_permuted_rows_and_columns(sigma,tau)
        [2 0 0 0 0]
        [0 3 0 0 0]
        [0 0 0 0 1]
        [0 0 0 5 0]
        [0 0 4 0 0]

  `with_rescaled_col`(i, s, start_row=0)

    Replaces i-th col of self by s times i-th col of self, returning new matrix.

    EXAMPLES: We rescale the last column of a matrix over the integers:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: b = a.with_rescaled_col(2,-2); b
        [  0   1  -4]
        [  3   4 -10]

    The original matrix is unchanged:

        sage: a
        [0 1 2]
        [3 4 5]

    Adding a rational multiple is okay, and reassigning a variable is okay:

        sage: a = a.with_rescaled_col(1,1/3); a
        [  0 1/3   2]
        [  3 4/3   5]

  `with_rescaled_row`(i, s, start_col=0)

    Replaces i-th row of self by s times i-th row of self, returning new matrix.

    EXAMPLES: We rescale the second row of a matrix over the integers:

        sage: a = matrix(ZZ,3,2,range(6)); a
        [0 1]
        [2 3]
        [4 5]
        sage: b = a.with_rescaled_row(1,-2); b
        [ 0  1]
        [-4 -6]
        [ 4  5]

    The original matrix is unchanged:

        sage: a
        [0 1]
        [2 3]
        [4 5]

    Adding a rational multiple is okay, and reassigning a variable is okay:

        sage: a = a.with_rescaled_row(2,1/3); a
        [  0   1]
        [  2   3]
        [4/3 5/3]

  `with_row_set_to_multiple_of_row`(i, j, s)

    Set row i equal to s times row j, returning a new matrix.

    EXAMPLES: We change the second row to -3 times the first row:

        sage: a = matrix(ZZ,2,3,range(6)); a
        [0 1 2]
        [3 4 5]
        sage: b = a.with_row_set_to_multiple_of_row(1,0,-3); b
        [ 0  1  2]
        [ 0 -3 -6]

    Note that the original matrix is unchanged:

        sage: a
        [0 1 2]
        [3 4 5]

    Adding a rational multiple is okay, and reassigning a variable is okay:

        sage: a = a.with_row_set_to_multiple_of_row(1,0,1/2); a
        [  0   1   2]
        [  0 1/2   1]

  `with_swapped_columns`(c1, c2)

    Swap columns `c1` and `c2` of `self` and return a new matrix.

    INPUT:

    - `c1`, `c2` - integers specifying columns of `self` to interchange

    OUTPUT:

    A new matrix, identical to `self` except that columns `c1` and `c2` are swapped.

    EXAMPLES:

    Remember that columns are numbered starting from zero.

        sage: A = matrix(QQ, 4, range(20))
        sage: A.with_swapped_columns(1, 2)
        [ 0  2  1  3  4]
        [ 5  7  6  8  9]
        [10 12 11 13 14]
        [15 17 16 18 19]

    Trying to swap a column with itself will succeed, but still return a new matrix.

        sage: A = matrix(QQ, 4, range(20))
        sage: B = A.with_swapped_columns(2, 2)
        sage: A == B
        True
        sage: A is B
        False

    The column specifications are checked.

        sage: A = matrix(4, range(20))
        sage: A.with_swapped_columns(-1, 2)
        Traceback (most recent call last):
        ...
        IndexError: matrix column index out of range

        sage: A.with_swapped_columns(2, 5)
        Traceback (most recent call last):
        ...
        IndexError: matrix column index out of range

  `with_swapped_rows`(r1, r2)

    Swap rows `r1` and `r2` of `self` and return a new matrix.

    INPUT:

    - `r1`, `r2` - integers specifying rows of `self` to interchange

    OUTPUT:

    A new matrix, identical to `self` except that rows `r1` and `r2` are swapped.

    EXAMPLES:

    Remember that rows are numbered starting from zero.

        sage: A = matrix(QQ, 4, range(20))
        sage: A.with_swapped_rows(1, 2)
        [ 0  1  2  3  4]
        [10 11 12 13 14]
        [ 5  6  7  8  9]
        [15 16 17 18 19]

    Trying to swap a row with itself will succeed, but still return a new matrix.

        sage: A = matrix(QQ, 4, range(20))
        sage: B = A.with_swapped_rows(2, 2)
        sage: A == B
        True
        sage: A is B
        False

    The row specifications are checked.

        sage: A = matrix(4, range(20))
        sage: A.with_swapped_rows(-1, 2)
        Traceback (most recent call last):
        ...
        IndexError: matrix row index out of range

        sage: A.with_swapped_rows(2, 5)
        Traceback (most recent call last):
        ...
        IndexError: matrix row index out of range

`sage.matrix.matrix0.``set_max_cols`(n)

  Sets the global variable max_cols (which is used in deciding how to output a matrix).

  EXAMPLES:

      sage: from sage.matrix.matrix0 import set_max_cols
      sage: set_max_cols(50)

`sage.matrix.matrix0.``set_max_rows`(n)

  Sets the global variable max_rows (which is used in deciding how to output a matrix).

  EXAMPLES:

      sage: from sage.matrix.matrix0 import set_max_rows
      sage: set_max_rows(20)

`sage.matrix.matrix0.``unpickle`(cls, parent, immutability, cache, data, version)

  Unpickle a matrix. This is only used internally by Sage. Users should never call this function directly.

  EXAMPLES: We illustrating saving and loading several different types of matrices.

  OVER \(\ZZ\):

      sage: A = matrix(ZZ,2,range(4))
      sage: loads(dumps(A)) # indirect doctest
      [0 1]
      [2 3]

  Sparse OVER \(\QQ\):

  Dense over \(\QQ[x,y]\):

  Dense over finite field.

### Navigation

- index
- modules |
- next |
- previous |
- Matrices and Spaces of Matrices »