General matrix Constructor and display options - Matrices and Spaces of Matrices

Skip to content
Back to top
View this page
Edit this page

# General matrix Constructor and display options

sage.matrix.constructor.Matrix(*args, **kwds)

  alias of `matrix()`.

sage.matrix.constructor.matrix(*args, **kwds)

  Create a matrix.

  This implements the `matrix` constructor:

  Sage

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

  Python

      >>> from sage.all import *
      >>> matrix([[Integer(1),Integer(2)],[Integer(3),Integer(4)]])
      [1 2]
      [3 4]

  It also contains methods to create special types of matrices, see `matrix.[tab]` for more options. For example:

  Sage

      sage: matrix.identity(2)
      [1 0]
      [0 1]

  [Python]

      >>> from sage.all import *
      >>> matrix.identity(Integer(2))
      [1 0]
      [0 1]

  INPUT:

  The `matrix()` command takes the entries of a matrix, optionally preceded by a ring and the dimensions of the matrix, and returns a matrix.

  The entries of a matrix can be specified as a flat list of elements, a list of lists (i.e., a list of rows), a list of Sage vectors, a callable object, or a dictionary having positions as keys and matrix entries as values (see the examples). If you pass in a callable object, then you must specify the number of rows and columns. You can create a matrix of zeros by passing an empty list or the integer zero for the entries. To construct a multiple of the identity (\(cI\)), you can specify square dimensions and pass in \(c\). Calling `matrix()` with a Sage object may return something that makes sense. Calling `matrix()` with a NumPy array will convert the array to a matrix.

  All arguments (even the positional ones) are optional.

  Positional and keyword arguments:

  - `base_ring` – parent of the entries of the matrix (despite the name, this is not a priori required to be a ring). By default, determine this from the given entries, falling back to `ZZ` if no entries are given.

  - `nrows` – the number of rows in the matrix, or a finite or enumerated family of arbitrary objects that index the rows of the matrix

  - `ncols` – the number of columns in the matrix, or a finite or enumerated family of arbitrary objects that index the columns of the matrix

  - `entries` – see examples below

  If any of `nrows`, `ncols`, `row_keys`, `column_keys` is given as keyword argument, then none of these may be given as positional arguments.

  Keyword-only arguments:

  - `sparse` – boolean; create a sparse matrix. This defaults to `True` when the entries are given as a dictionary, otherwise defaults to `False`.

  - `row_keys` – a finite or enumerated family of arbitrary objects that index the rows of the matrix

  - `column_keys` – a finite or enumerated family of arbitrary objects that index the columns of the matrix

  - `space` – matrix space which will be the parent of the output matrix. This determines `base_ring`, `nrows`, `row_keys`, `ncols`, `column_keys`, and `sparse`.

  - `immutable` – boolean; make the matrix immutable. By default, the output matrix is mutable.

  OUTPUT: a matrix or, more generally, a homomorphism between free modules

  EXAMPLES:

  Sage

      sage: m = matrix(2); m; m.parent()
      [0 0]
      [0 0]
      Full MatrixSpace of 2 by 2 dense matrices over Integer Ring

  Python

      >>> from sage.all import *
      >>> m = matrix(Integer(2)); m; m.parent()
      [0 0]
      [0 0]
      Full MatrixSpace of 2 by 2 dense matrices over Integer Ring

  Sage

      sage: m = matrix(2, 3); m; m.parent()
      [0 0 0]
      [0 0 0]
      Full MatrixSpace of 2 by 3 dense matrices over Integer Ring

  [Python]

      >>> from sage.all import *
      >>> m = matrix(Integer(2), Integer(3)); m; m.parent()
      [0 0 0]
      [0 0 0]
      Full MatrixSpace of 2 by 3 dense matrices over Integer Ring

  Sage

      sage: m = matrix(QQ, [[1,2,3], [4,5,6]]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Rational Field

  Python

      >>> from sage.all import *
      >>> m = matrix(QQ, [[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Rational Field

  Sage

      sage: m = matrix(QQ, 3, 3, lambda i, j: i + j); m
      [0 1 2]
      [1 2 3]
      [2 3 4]
      sage: m = matrix(3, lambda i, j: i - j); m
      [ 0 -1 -2]
      [ 1  0 -1]
      [ 2  1  0]

  [Python]

      >>> from sage.all import *
      >>> m = matrix(QQ, Integer(3), Integer(3), lambda i, j: i + j); m
      [0 1 2]
      [1 2 3]
      [2 3 4]
      >>> m = matrix(Integer(3), lambda i, j: i - j); m
      [ 0 -1 -2]
      [ 1  0 -1]
      [ 2  1  0]

  Sage

      sage: matrix(QQ, 2, 3, lambda x, y: x + y)
      [0 1 2]
      [1 2 3]
      sage: matrix(QQ, 5, 5, lambda x, y: (x+1) / (y+1))
      [  1 1/2 1/3 1/4 1/5]
      [  2   1 2/3 1/2 2/5]
      [  3 3/2   1 3/4 3/5]
      [  4   2 4/3   1 4/5]
      [  5 5/2 5/3 5/4   1]

  Python

      >>> from sage.all import *
      >>> matrix(QQ, Integer(2), Integer(3), lambda x, y: x + y)
      [0 1 2]
      [1 2 3]
      >>> matrix(QQ, Integer(5), Integer(5), lambda x, y: (x+Integer(1)) / (y+Integer(1)))
      [  1 1/2 1/3 1/4 1/5]
      [  2   1 2/3 1/2 2/5]
      [  3 3/2   1 3/4 3/5]
      [  4   2 4/3   1 4/5]
      [  5 5/2 5/3 5/4   1]

  Sage

      sage: v1 = vector((1,2,3))
      sage: v2 = vector((4,5,6))
      sage: m = matrix([v1,v2]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Integer Ring

  [Python]

      >>> from sage.all import *
      >>> v1 = vector((Integer(1),Integer(2),Integer(3)))
      >>> v2 = vector((Integer(4),Integer(5),Integer(6)))
      >>> m = matrix([v1,v2]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Integer Ring

  Sage

      sage: m = matrix(QQ, 2, [1,2,3,4,5,6]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Rational Field

  Python

      >>> from sage.all import *
      >>> m = matrix(QQ, Integer(2), [Integer(1),Integer(2),Integer(3),Integer(4),Integer(5),Integer(6)]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Rational Field

  Sage

      sage: m = matrix(QQ, 2, 3, [1,2,3,4,5,6]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Rational Field

  [Python]

      >>> from sage.all import *
      >>> m = matrix(QQ, Integer(2), Integer(3), [Integer(1),Integer(2),Integer(3),Integer(4),Integer(5),Integer(6)]); m; m.parent()
      [1 2 3]
      [4 5 6]
      Full MatrixSpace of 2 by 3 dense matrices over Rational Field

  Sage

      sage: m = matrix({(0,1): 2, (1,1): 2/5}); m; m.parent()
      [  0   2]
      [  0 2/5]
      Full MatrixSpace of 2 by 2 sparse matrices over Rational Field

  Python

      >>> from sage.all import *
      >>> m = matrix({(Integer(0),Integer(1)): Integer(2), (Integer(1),Integer(1)): Integer(2)/Integer(5)}); m; m.parent()
      [  0   2]
      [  0 2/5]
      Full MatrixSpace of 2 by 2 sparse matrices over Rational Field

  Sage

      sage: m = matrix(QQ, 2, 3, {(1,1): 2}); m; m.parent()
      [0 0 0]
      [0 2 0]
      Full MatrixSpace of 2 by 3 sparse matrices over Rational Field

  [Python]

      >>> from sage.all import *
      >>> m = matrix(QQ, Integer(2), Integer(3), {(Integer(1),Integer(1)): Integer(2)}); m; m.parent()
      [0 0 0]
      [0 2 0]
      Full MatrixSpace of 2 by 3 sparse matrices over Rational Field

  Sage

      sage: import numpy                                                              # needs numpy
      sage: n = numpy.array([[1,2], [3,4]], float)                                    # needs numpy
      sage: m = matrix(n); m; m.parent()                                              # needs numpy
      [1.0 2.0]
      [3.0 4.0]
      Full MatrixSpace of 2 by 2 dense matrices over Real Double Field

  Python

      >>> from sage.all import *
      >>> import numpy                                                              # needs numpy
      >>> n = numpy.array([[Integer(1),Integer(2)], [Integer(3),Integer(4)]], float)                                    # needs numpy
      >>> m = matrix(n); m; m.parent()                                              # needs numpy
      [1.0 2.0]
      [3.0 4.0]
      Full MatrixSpace of 2 by 2 dense matrices over Real Double Field

  Sage

      sage: v = vector(ZZ, [1, 10, 100])
      sage: m = matrix(v); m; m.parent()
      [  1  10 100]
      Full MatrixSpace of 1 by 3 dense matrices over Integer Ring
      sage: m = matrix(GF(7), v); m; m.parent()
      [1 3 2]
      Full MatrixSpace of 1 by 3 dense matrices over Finite Field of size 7
      sage: m = matrix(GF(7), 3, 1, v); m; m.parent()
      [1]
      [3]
      [2]
      Full MatrixSpace of 3 by 1 dense matrices over Finite Field of size 7

  [Python]

      >>> from sage.all import *
      >>> v = vector(ZZ, [Integer(1), Integer(10), Integer(100)])
      >>> m = matrix(v); m; m.parent()
      [  1  10 100]
      Full MatrixSpace of 1 by 3 dense matrices over Integer Ring
      >>> m = matrix(GF(Integer(7)), v); m; m.parent()
      [1 3 2]
      Full MatrixSpace of 1 by 3 dense matrices over Finite Field of size 7
      >>> m = matrix(GF(Integer(7)), Integer(3), Integer(1), v); m; m.parent()
      [1]
      [3]
      [2]
      Full MatrixSpace of 3 by 1 dense matrices over Finite Field of size 7

  Sage

      sage: matrix(pari.mathilbert(3))                                                # needs sage.libs.pari
      [  1 1/2 1/3]
      [1/2 1/3 1/4]
      [1/3 1/4 1/5]

  Python

      >>> from sage.all import *
      >>> matrix(pari.mathilbert(Integer(3)))                                                # needs sage.libs.pari
      [  1 1/2 1/3]
      [1/2 1/3 1/4]
      [1/3 1/4 1/5]

  Sage

      sage: g = graphs.PetersenGraph()                                                # needs sage.graphs
      sage: m = matrix(g); m; m.parent()                                              # needs sage.graphs
      [0 1 0 0 1 1 0 0 0 0]
      [1 0 1 0 0 0 1 0 0 0]
      [0 1 0 1 0 0 0 1 0 0]
      [0 0 1 0 1 0 0 0 1 0]
      [1 0 0 1 0 0 0 0 0 1]
      [1 0 0 0 0 0 0 1 1 0]
      [0 1 0 0 0 0 0 0 1 1]
      [0 0 1 0 0 1 0 0 0 1]
      [0 0 0 1 0 1 1 0 0 0]
      [0 0 0 0 1 0 1 1 0 0]
      Full MatrixSpace of 10 by 10 dense matrices over Integer Ring

  [Python]

      >>> from sage.all import *
      >>> g = graphs.PetersenGraph()                                                # needs sage.graphs
      >>> m = matrix(g); m; m.parent()                                              # needs sage.graphs
      [0 1 0 0 1 1 0 0 0 0]
      [1 0 1 0 0 0 1 0 0 0]
      [0 1 0 1 0 0 0 1 0 0]
      [0 0 1 0 1 0 0 0 1 0]
      [1 0 0 1 0 0 0 0 0 1]
      [1 0 0 0 0 0 0 1 1 0]
      [0 1 0 0 0 0 0 0 1 1]
      [0 0 1 0 0 1 0 0 0 1]
      [0 0 0 1 0 1 1 0 0 0]
      [0 0 0 0 1 0 1 1 0 0]
      Full MatrixSpace of 10 by 10 dense matrices over Integer Ring

  Sage

      sage: matrix(ZZ, 10, 10, range(100), sparse=True).parent()
      Full MatrixSpace of 10 by 10 sparse matrices over Integer Ring

  Python

      >>> from sage.all import *
      >>> matrix(ZZ, Integer(10), Integer(10), range(Integer(100)), sparse=True).parent()
      Full MatrixSpace of 10 by 10 sparse matrices over Integer Ring

  Sage

      sage: R = PolynomialRing(QQ, 9, 'x')
      sage: A = matrix(R, 3, 3, R.gens()); A
      [x0 x1 x2]
      [x3 x4 x5]
      [x6 x7 x8]
      sage: det(A)
      -x2*x4*x6 + x1*x5*x6 + x2*x3*x7 - x0*x5*x7 - x1*x3*x8 + x0*x4*x8

  [Python]

      >>> from sage.all import *
      >>> R = PolynomialRing(QQ, Integer(9), 'x')
      >>> A = matrix(R, Integer(3), Integer(3), R.gens()); A
      [x0 x1 x2]
      [x3 x4 x5]
      [x6 x7 x8]
      >>> det(A)
      -x2*x4*x6 + x1*x5*x6 + x2*x3*x7 - x0*x5*x7 - x1*x3*x8 + x0*x4*x8

  Sage

      sage: M = Matrix([[1,2,3], [4,5,6], [7,8,9]], immutable=True)
      sage: M[0] = [9,9,9]
      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).

  Python

      >>> from sage.all import *
      >>> M = Matrix([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)], [Integer(7),Integer(8),Integer(9)]], immutable=True)
      >>> M[Integer(0)] = [Integer(9),Integer(9),Integer(9)]
      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).

  Using `row_keys` and `column_keys`:

  Sage

      sage: M = matrix([[1,2,3], [4,5,6]],
      ....:            column_keys=['a','b','c'], row_keys=['u','v']); M
      Generic morphism:
        From: Free module generated by {'a', 'b', 'c'} over Integer Ring
        To:   Free module generated by {'u', 'v'} over Integer Ring
      sage: print(M._unicode_art_matrix())
        a b c
      u⎛1 2 3⎞
      v⎝4 5 6⎠

  [Python]

      >>> from sage.all import *
      >>> M = matrix([[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]],
      ...            column_keys=['a','b','c'], row_keys=['u','v']); M
      Generic morphism:
        From: Free module generated by {'a', 'b', 'c'} over Integer Ring
        To:   Free module generated by {'u', 'v'} over Integer Ring
      >>> print(M._unicode_art_matrix())
        a b c
      u⎛1 2 3⎞
      v⎝4 5 6⎠

  It is allowed to specify dimensions redundantly:

  Sage

      sage: M = matrix(2, 3, [[1,2,3], [4,5,6]],
      ....:            column_keys=['a','b','c'], row_keys=['u','v']); M
      Generic morphism:
      From: Free module generated by {'a', 'b', 'c'} over Integer Ring
      To:   Free module generated by {'u', 'v'} over Integer Ring

  Python

      >>> from sage.all import *
      >>> M = matrix(Integer(2), Integer(3), [[Integer(1),Integer(2),Integer(3)], [Integer(4),Integer(5),Integer(6)]],
      ...            column_keys=['a','b','c'], row_keys=['u','v']); M
      Generic morphism:
      From: Free module generated by {'a', 'b', 'c'} over Integer Ring
      To:   Free module generated by {'u', 'v'} over Integer Ring

  AUTHORS:

  - William Stein: Initial implementation

  - Jason Grout (2008-03): almost a complete rewrite, with bits and pieces from the original implementation

  - Jeroen Demeyer (2016-02-05): major clean up, see Issue #20015 and Issue #20016

  - Jeroen Demeyer (2018-02-20): completely rewritten using `MatrixArgs`, see Issue #24742

sage.matrix.constructor.options(*get_value, **set_value)

  > Global options for matrices.

  > OPTIONS:

  - `format_numeric` – (default: `{:.{prec}}`) string used for formatting floating point numbers of an (optional) precision `prec`; only supported for entry types implementing `__format__`

  - `max_cols` – (default: `49`) maximum number of columns to display

  - `max_rows` – (default: `19`) maximum number of rows to display

  - `precision` – (default: `None`) number of digits to display for floating point entries; if `None`, the exact representation is used instead. This option is also set by the IPython magic `%precision`.

    > EXAMPLES:

    > Sage

    >     sage: matrix.options.max_cols = 6
    >     sage: matrix.options.max_rows = 3
    >     sage: matrix(ZZ, 3, 6)
    >     [0 0 0 0 0 0]
    >     [0 0 0 0 0 0]
    >     [0 0 0 0 0 0]
    >     sage: matrix(ZZ, 3, 7)
    >     3 x 7 dense matrix over Integer Ring...
    >     sage: matrix(ZZ, 4, 6)
    >     4 x 6 dense matrix over Integer Ring...
    >     sage: matrix.options._reset()

    > Python

    >     >>> from sage.all import *
    >     >>> matrix.options.max_cols = Integer(6)
    >     >>> matrix.options.max_rows = Integer(3)
    >     >>> matrix(ZZ, Integer(3), Integer(6))
    >     [0 0 0 0 0 0]
    >     [0 0 0 0 0 0]
    >     [0 0 0 0 0 0]
    >     >>> matrix(ZZ, Integer(3), Integer(7))
    >     3 x 7 dense matrix over Integer Ring...
    >     >>> matrix(ZZ, Integer(4), Integer(6))
    >     4 x 6 dense matrix over Integer Ring...
    >     >>> matrix.options._reset()

    > The precision can also be set via the IPython magic:

    > Sage

    >     sage: from sage.repl.interpreter import get_test_shell
    >     sage: shell = get_test_shell()
    >     sage: shell.run_cell('%precision 5')
    >     '%.5f'
    >     sage: matrix.options.precision
    >     5
    >     sage: A = matrix(RR, [[200/3]]); A
    >     [66.667]

    > [Python]

    >     >>> from sage.all import *
    >     >>> from sage.repl.interpreter import get_test_shell
    >     >>> shell = get_test_shell()
    >     >>> shell.run_cell('%precision 5')
    >     '%.5f'
    >     >>> matrix.options.precision
    >     5
    >     >>> A = matrix(RR, [[Integer(200)/Integer(3)]]); A
    >     [66.667]

    > The number format can be specified as well:

    > Sage

    >     sage: matrix.options.format_numeric = '{:.{prec}e}'
    >     sage: A
    >     [6.66667e+1]
    >     sage: matrix.options.format_numeric = '{:.{prec}f}'
    >     sage: A
    >     [66.66667]
    >     sage: matrix.options.format_numeric = '{:+.{prec}g}'
    >     sage: A
    >     [+66.667]
    >     sage: matrix.options._reset()

    > Python

    >     >>> from sage.all import *
    >     >>> matrix.options.format_numeric = '{:.{prec}e}'
    >     >>> A
    >     [6.66667e+1]
    >     >>> matrix.options.format_numeric = '{:.{prec}f}'
    >     >>> A
    >     [66.66667]
    >     >>> matrix.options.format_numeric = '{:+.{prec}g}'
    >     >>> A
    >     [+66.667]
    >     >>> matrix.options._reset()

  See `GlobalOptions` for more features of these options.