matrix(*args, **kwds)
Create a matrix.
 
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.
 
The ring, number of rows, and number of columns of the matrix can
be specified by setting the ring, nrows, or ncols parameters or by
passing them as the first arguments to the function in the order
ring, nrows, ncols. The ring defaults to ZZ if it is not specified
or cannot be determined from the entries. If the numbers of rows
and columns are not specified and cannot be determined, then an
empty 0x0 matrix is returned.
 
 
-  ``ring`` - the base ring for the entries of the
   matrix.
 
-  ``nrows`` - the number of rows in the matrix.
 
-  ``ncols`` - the number of columns in the matrix.
 
-  ``sparse`` - create a sparse matrix. This defaults
   to True when the entries are given as a dictionary, otherwise
   defaults to False.
 
 
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,3,2,lambda x, y: x+y)
    [0 1]
    [1 2]
    [2 3]
 
::
 
    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: 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
 
TESTS::
 
    sage: m=matrix(); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 dense matrices over Integer Ring
    sage: m=matrix(QQ); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 dense matrices over Rational Field
    sage: m=matrix(QQ,2); m; m.parent()
    [0 0]
    [0 0]
    Full MatrixSpace of 2 by 2 dense matrices over Rational Field
    sage: m=matrix(QQ,2,3); m; m.parent()
    [0 0 0]
    [0 0 0]
    Full MatrixSpace of 2 by 3 dense matrices over Rational Field
    sage: m=matrix([]); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 dense matrices over Integer Ring
    sage: m=matrix(QQ,[]); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 dense matrices over Rational Field
    sage: m=matrix(2,2,1); m; m.parent()
    [1 0]
    [0 1]
    Full MatrixSpace of 2 by 2 dense matrices over Integer Ring
    sage: m=matrix(QQ,2,2,1); m; m.parent()
    [1 0]
    [0 1]
    Full MatrixSpace of 2 by 2 dense matrices over Rational Field
    sage: m=matrix(2,3,0); m; m.parent()
    [0 0 0]
    [0 0 0]
    Full MatrixSpace of 2 by 3 dense matrices over Integer Ring
    sage: m=matrix(QQ,2,3,0); m; m.parent()
    [0 0 0]
    [0 0 0]
    Full MatrixSpace of 2 by 3 dense matrices over Rational Field
    sage: m=matrix([[1,2,3],[4,5,6]]); 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,3,[[1,2,3],[4,5,6]]); m; m.parent()
    Traceback (most recent call last):
    ...
    ValueError: Number of rows does not match up with specified number.
    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(QQ,2,4,[[1,2,3],[4,5,6]]); m; m.parent()
    Traceback (most recent call last):
    ...
    ValueError: Number of columns does not match up with specified number.
    sage: m=matrix([(1,2,3),(4,5,6)]); m; m.parent()
    [1 2 3]
    [4 5 6]
    Full MatrixSpace of 2 by 3 dense matrices over Integer Ring
    sage: m=matrix([1,2,3,4,5,6]); m; m.parent()
    [1 2 3 4 5 6]
    Full MatrixSpace of 1 by 6 dense matrices over Integer Ring
    sage: m=matrix((1,2,3,4,5,6)); m; m.parent()
    [1 2 3 4 5 6]
    Full MatrixSpace of 1 by 6 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 1 by 6 dense matrices over Rational Field
    sage: m=matrix(QQ,3,2,[1,2,3,4,5,6]); m; m.parent()
    [1 2]
    [3 4]
    [5 6]
    Full MatrixSpace of 3 by 2 dense matrices over Rational Field
    sage: m=matrix(QQ,2,4,[1,2,3,4,5,6]); m; m.parent()
    Traceback (most recent call last):
    ...
    ValueError: entries has the wrong length
    sage: m=matrix(QQ,5,[1,2,3,4,5,6]); m; m.parent()
    Traceback (most recent call last):
    ...
    TypeError: entries has the wrong length
    sage: m=matrix({(1,1): 2}); m; m.parent()
    [0 0]
    [0 2]
    Full MatrixSpace of 2 by 2 sparse matrices over Integer Ring
    sage: m=matrix(QQ,{(1,1): 2}); m; m.parent()
    [0 0]
    [0 2]
    Full MatrixSpace of 2 by 2 sparse matrices over Rational Field
    sage: m=matrix(QQ,3,{(1,1): 2}); m; m.parent()
    [0 0 0]
    [0 2 0]
    [0 0 0]
    Full MatrixSpace of 3 by 3 sparse matrices over Rational Field
    sage: m=matrix(QQ,3,4,{(1,1): 2}); m; m.parent()
    [0 0 0 0]
    [0 2 0 0]
    [0 0 0 0]
    Full MatrixSpace of 3 by 4 sparse matrices over Rational Field
    sage: m=matrix(QQ,2,{(1,1): 2}); m; m.parent()
    [0 0]
    [0 2]
    Full MatrixSpace of 2 by 2 sparse matrices over Rational Field
    sage: m=matrix(QQ,1,{(1,1): 2}); m; m.parent()
    Traceback (most recent call last):
    ...
    IndexError: invalid entries list
    sage: m=matrix({}); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 sparse matrices over Integer Ring
    sage: m=matrix(QQ,{}); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 sparse matrices over Rational Field
    sage: m=matrix(QQ,2,{}); m; m.parent()
    [0 0]
    [0 0]
    Full MatrixSpace of 2 by 2 sparse matrices over Rational Field
    sage: m=matrix(QQ,2,3,{}); m; m.parent()
    [0 0 0]
    [0 0 0]
    Full MatrixSpace of 2 by 3 sparse matrices over Rational Field
    sage: m=matrix(2,{}); m; m.parent()
    [0 0]
    [0 0]
    Full MatrixSpace of 2 by 2 sparse matrices over Integer Ring
    sage: m=matrix(2,3,{}); m; m.parent()
    [0 0 0]
    [0 0 0]
    Full MatrixSpace of 2 by 3 sparse matrices over Integer Ring
    sage: m=matrix(0); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 dense matrices over Integer Ring
    sage: m=matrix(0,2); m; m.parent()
    []
    Full MatrixSpace of 0 by 2 dense matrices over Integer Ring
    sage: m=matrix(2,0); m; m.parent()
    []
    Full MatrixSpace of 2 by 0 dense matrices over Integer Ring
    sage: m=matrix(0,[1]); m; m.parent()
    Traceback (most recent call last):
    ...
    ValueError: entries has the wrong length
    sage: m=matrix(1,0,[]); m; m.parent()
    []
    Full MatrixSpace of 1 by 0 dense matrices over Integer Ring
    sage: m=matrix(0,1,[]); m; m.parent()
    []
    Full MatrixSpace of 0 by 1 dense matrices over Integer Ring
    sage: m=matrix(0,[]); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 dense matrices over Integer Ring
    sage: m=matrix(0,{}); m; m.parent()
    []
    Full MatrixSpace of 0 by 0 sparse matrices over Integer Ring
    sage: m=matrix(0,{(1,1):2}); m; m.parent()
    Traceback (most recent call last):
    ...
    IndexError: invalid entries list
    sage: m=matrix(2,0,{(1,1):2}); m; m.parent()
    Traceback (most recent call last):
    ...
    IndexError: invalid entries list
    sage: import numpy
    sage: n=numpy.array([[numpy.complex(0,1),numpy.complex(0,2)],[3,4]],complex)
    sage: m=matrix(n); m; m.parent()
    [1.0*I 2.0*I]
    [  3.0   4.0]
    Full MatrixSpace of 2 by 2 dense matrices over Complex Double Field
    sage: n=numpy.array([[1,2],[3,4]],'int32')
    sage: m=matrix(n); m; m.parent()
    [1 2]
    [3 4]
    Full MatrixSpace of 2 by 2 dense matrices over Integer Ring
    sage: n = numpy.array([[1,2,3],[4,5,6],[7,8,9]],'float32')
    sage: m=matrix(n); m; m.parent()
    [1.0 2.0 3.0]
    [4.0 5.0 6.0]
    [7.0 8.0 9.0]
    Full MatrixSpace of 3 by 3 dense matrices over Real Double Field
    sage: n=numpy.array([[1,2,3],[4,5,6],[7,8,9]],'float64')
    sage: m=matrix(n); m; m.parent()
    [1.0 2.0 3.0]
    [4.0 5.0 6.0]
    [7.0 8.0 9.0]
    Full MatrixSpace of 3 by 3 dense matrices over Real Double Field
    sage: n=numpy.array([[1,2,3],[4,5,6],[7,8,9]],'complex64')
    sage: m=matrix(n); m; m.parent()
    [1.0 2.0 3.0]
    [4.0 5.0 6.0]
    [7.0 8.0 9.0]
    Full MatrixSpace of 3 by 3 dense matrices over Complex Double Field
    sage: n=numpy.array([[1,2,3],[4,5,6],[7,8,9]],'complex128')
    sage: m=matrix(n); m; m.parent()
    [1.0 2.0 3.0]
    [4.0 5.0 6.0]
    [7.0 8.0 9.0]
    Full MatrixSpace of 3 by 3 dense matrices over Complex Double Field
    sage: a = matrix([[1,2],[3,4]])
    sage: b = matrix(a.numpy()); b
    [1 2]
    [3 4]
    sage: a == b
    True
    sage: c = matrix(a.numpy('float32')); c
    [1.0 2.0]
    [3.0 4.0]
    sage: matrix(numpy.array([[5]]))
    [5]
    sage: v = vector(ZZ, [1, 10, 100])
    sage: m=matrix(ZZ['x'], v); m; m.parent()
    [  1  10 100]
    Full MatrixSpace of 1 by 3 dense matrices over Univariate Polynomial Ring in x over Integer Ring
    sage: matrix(ZZ, 10, 10, range(100)).parent()
    Full MatrixSpace of 10 by 10 dense matrices over Integer Ring
    sage: m = matrix(GF(7), [[1/3,2/3,1/2], [3/4,4/5,7]]); m; m.parent()
    [5 3 4]
    [6 5 0]
    Full MatrixSpace of 2 by 3 dense matrices over Finite Field of size 7
    sage: m = matrix([[1,2,3], [RDF(2), CDF(1,2), 3]]); m; m.parent()
    [        1.0         2.0         3.0]
    [        2.0 1.0 + 2.0*I         3.0]
    Full MatrixSpace of 2 by 3 dense matrices over Complex Double Field
    sage: m=matrix(3,3,1/2); m; m.parent()
    [1/2   0   0]
    [  0 1/2   0]
    [  0   0 1/2]
    Full MatrixSpace of 3 by 3 dense matrices over Rational Field
    sage: matrix([[1],[2,3]])
    Traceback (most recent call last):
    ...
    ValueError: List of rows is not valid (rows are wrong types or lengths)
    sage: matrix([[1],2])
    Traceback (most recent call last):
    ...
    ValueError: List of rows is not valid (rows are wrong types or lengths)
    sage: matrix(vector(RR,[1,2,3])).parent()
    Full MatrixSpace of 1 by 3 dense matrices over Real Field with 53 bits of precision
    sage: matrix(ZZ, [[0] for i in range(10^6)]).is_zero() # see #10158
    True
 
AUTHORS:
 
- ??: Initial implementation
 
- Jason Grout (2008-03): almost a complete rewrite, with bits and
  pieces from the original implementation