General matrix Constructor and display options

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

Create a matrix.

This implements the matrix constructor:

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

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

sage: matrix.identity(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) are optional.

Positional and keyword arguments:

• 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.

• ncols – the number of columns in the matrix.

• entries – see examples below.

If either nrows or ncols is given as keyword argument, then no positional arguments nrows and ncols may be given.

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.

• space – matrix space which will be the parent of the output matrix. This determines ring, nrows, ncols and sparse.

• immutable – (boolean) make the matrix immutable. By default, the output matrix is mutable.

OUTPUT:

a matrix

EXAMPLES:

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

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

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

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]

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]

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

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

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

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

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

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

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

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

sage: g = graphs.PetersenGraph()
sage: m = matrix(g); m; m.parent()
[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: matrix(ZZ, 10, 10, range(100), sparse=True).parent()
Full MatrixSpace of 10 by 10 sparse matrices over Integer Ring

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

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).

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 trac ticket #20015 and trac ticket #20016

• Jeroen Demeyer (2018-02-20): completely rewritten using MatrixArgs, see trac ticket #24742

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

Create a matrix.

This implements the matrix constructor:

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

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

sage: matrix.identity(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) are optional.

Positional and keyword arguments:

• 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.

• ncols – the number of columns in the matrix.

• entries – see examples below.

If either nrows or ncols is given as keyword argument, then no positional arguments nrows and ncols may be given.

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.

• space – matrix space which will be the parent of the output matrix. This determines ring, nrows, ncols and sparse.

• immutable – (boolean) make the matrix immutable. By default, the output matrix is mutable.

OUTPUT:

a matrix

EXAMPLES:

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

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

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

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]

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]

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

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

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

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

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

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

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

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

sage: g = graphs.PetersenGraph()
sage: m = matrix(g); m; m.parent()
[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: matrix(ZZ, 10, 10, range(100), sparse=True).parent()
Full MatrixSpace of 10 by 10 sparse matrices over Integer Ring

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

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).

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 trac ticket #20015 and trac ticket #20016

• Jeroen Demeyer (2018-02-20): completely rewritten using MatrixArgs, see trac ticket #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: 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()
  

  The precision can also be set via the IPython magic:

  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]
  

  The number format can be specified as well:

  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()
  

See GlobalOptions for more features of these options.