New MatrixArgs object to deal with constructing matrices

src/doc/en/reference/matrices/index.rst

@@ -47,23 +47,16 @@ objects like operation tables (e.g. the multiplication table of a group).
 
 
    sage/matrix/matrix_space
-
    sage/matrix/constructor
-
-   sage/matrix/docs
-
-   sage/matrix/matrix_misc
-
    sage/matrix/special
+   sage/matrix/args
 
+   sage/matrix/docs
    sage/matrix/matrix0
-
    sage/matrix/matrix1
-
    sage/matrix/matrix2
 
    sage/matrix/strassen
-
    sage/matrix/berlekamp_massey
 
    sage/matrix/matrix_dense
@@ -72,38 +65,32 @@ objects like operation tables (e.g. the multiplication table of a group).
    sage/matrix/matrix_generic_dense
    sage/matrix/matrix_generic_sparse
 
-   sage/matrix/matrix_modn_sparse
-
-   sage/matrix/matrix_symbolic_dense
-
    sage/matrix/matrix_integer_dense
-
+   sage/matrix/matrix_integer_sparse
+   sage/matrix/matrix_integer_dense_hnf
+   sage/matrix/matrix_integer_dense_saturation
    sage/matrix/matrix_rational_dense
-
+   sage/matrix/matrix_rational_sparse
    sage/matrix/matrix_double_dense
-
    sage/matrix/matrix_real_double_dense
-
+   sage/matrix/matrix_mod2_dense
+   sage/matrix/matrix_gf2e_dense
+   sage/matrix/matrix_modn_dense_double
+   sage/matrix/matrix_modn_dense_float
+   sage/matrix/matrix_modn_sparse
+   sage/matrix/matrix_symbolic_dense
    sage/matrix/matrix_complex_double_dense
    sage/matrix/matrix_complex_ball_dense
-
    sage/matrix/matrix_polynomial_dense
    sage/matrix/matrix_mpolynomial_dense
+   sage/matrix/matrix_cyclo_dense
 
    sage/matrix/operation_table
 
    sage/matrix/action
    sage/matrix/change_ring
    sage/matrix/echelon_matrix
-   sage/matrix/matrix_cyclo_dense
-   sage/matrix/matrix_integer_dense_hnf
-   sage/matrix/matrix_integer_dense_saturation
-   sage/matrix/matrix_integer_sparse
-   sage/matrix/matrix_mod2_dense
-   sage/matrix/matrix_gf2e_dense
-   sage/matrix/matrix_modn_dense_double
-   sage/matrix/matrix_modn_dense_float
-   sage/matrix/matrix_rational_sparse
+   sage/matrix/matrix_misc
    sage/matrix/matrix_window
    sage/matrix/misc
    sage/matrix/symplectic_basis

src/module_list.py

@@ -723,6 +723,9 @@ def uname_specific(name, value, alternative):
     Extension('sage.matrix.action',
               sources = ['sage/matrix/action.pyx']),
 
+    Extension('sage.matrix.args',
+              sources = ['sage/matrix/args.pyx']),
+
     Extension('sage.matrix.echelon_matrix',
               sources = ['sage/matrix/echelon_matrix.pyx']),
 

src/sage/categories/coxeter_groups.py

@@ -249,7 +249,7 @@ def _element_constructor_(self, x, **args):
                 sage: W(s1*s2)
                 Traceback (most recent call last):
                 ...
-                ValueError: ...
+                ValueError: inconsistent number of rows: should be 1 but got 3
             """
             P = parent(x)
             if P in CoxeterGroups():

src/sage/combinat/k_tableau.py

@@ -1823,7 +1823,7 @@ def straighten_input(t, k):
             sage: WeakTableau_factorized_permutation.straighten_input([W.an_element(),W.an_element()], 3)
             Traceback (most recent call last):
             ...
-            ValueError: a matrix from Full MatrixSpace of 5 by 5 dense matrices over Rational Field cannot be converted to a matrix in Full MatrixSpace of 4 by 4 dense matrices over Rational Field!
+            ValueError: inconsistent number of rows: should be 4 but got 5
         """
         W = WeylGroup(['A', k, 1], prefix='s')
         if len(t) > 0:

src/sage/groups/matrix_gps/group_element.pyx

@@ -310,6 +310,21 @@ cdef class MatrixGroupElement_generic(MultiplicativeGroupElement):
         """
         return self._matrix
 
+    def _matrix_(self, base=None):
+        """
+        Method used by the :func:`matrix` constructor.
+
+        EXAMPLES::
+
+            sage: W = CoxeterGroup(['A', 3], base_ring=ZZ)
+            sage: g = W.gen(0)
+            sage: matrix(RDF, g)
+            [-1.0  1.0  0.0]
+            [ 0.0  1.0  0.0]
+            [ 0.0  0.0  1.0]
+        """
+        return self.matrix()
+
     cpdef _mul_(self, other):
         """
         Return the product of ``self`` and`` other``, which must
@@ -590,6 +605,22 @@ cdef class MatrixGroupElement_gap(ElementLibGAP):
         m.set_immutable()
         return m
 
+    def _matrix_(self, base=None):
+        """
+        Method used by the :func:`matrix` constructor.
+
+        EXAMPLES::
+
+            sage: F = GF(3); MS = MatrixSpace(F,2,2)
+            sage: G = MatrixGroup([MS([1,1,0,1])])
+            sage: g = G.gen(0)
+            sage: M = matrix(GF(9), g); M; parent(M)
+            [1 1]
+            [0 1]
+            Full MatrixSpace of 2 by 2 dense matrices over Finite Field in z2 of size 3^2
+        """
+        return self.matrix()
+
     cpdef list list(self):
         """
         Return list representation of this matrix.

src/sage/matrix/__init__.py

@@ -1,5 +1,2 @@
-"""
-Classes for matrix algebra.
-
-See docs.py for more information
-"""
+# Resolve a cyclic import
+import sage.matrix.args

src/sage/matrix/args.pxd

@@ -0,0 +1,122 @@
+from cpython.object cimport PyObject
+from sage.structure.element cimport Element, Matrix
+from sage.structure.parent cimport Parent
+
+
+cdef enum entries_type:
+    # flags appearing in the types below
+    MA_FLAG_ASSUME_SQUARE = 0x01_00  # Assume a square matrix if only 1 dimension given
+    MA_FLAG_DIM_REQUIRED  = 0x02_00  # Dimensions must be given
+    MA_FLAG_BASE_REQUIRED = 0x04_00  # Base must be given or is trivial to determine
+    MA_FLAG_FINAL         = 0x10_00  # Can occur after finalize()
+    MA_FLAG_SPARSE        = 0x20_00  # Sparse by default
+
+    # types of input entries
+    MA_ENTRIES_UNKNOWN    =       0  # anything
+    MA_ENTRIES_ZERO       = 0x17_01  # zero matrix
+    MA_ENTRIES_SCALAR     = 0x17_02  # single scalar value
+    MA_ENTRIES_SEQ_SEQ    = 0x10_03  # list of lists
+    MA_ENTRIES_SEQ_FLAT   = 0x10_04  # flat list
+    MA_ENTRIES_SEQ_SPARSE = 0x37_05  # list of SparseEntry instances
+    MA_ENTRIES_CALLABLE   = 0x13_06  # function for the entries
+    MA_ENTRIES_MATRIX     = 0x14_07  # Sage matrix
+    MA_ENTRIES_MAPPING    = 0x01_08  # dict
+    MA_ENTRIES_METHOD     = 0x00_09  # function returning the matrix
+    MA_ENTRIES_NDARRAY    = 0x00_0A  # numpy array
+
+    # value for exception raised
+    MA_EXCEPT = -1
+
+
+cdef class SparseEntry:
+    cdef public long i, j
+    cdef public object entry
+
+
+cdef inline SparseEntry make_SparseEntry(long i, long j, entry):
+    e = <SparseEntry>SparseEntry.__new__(SparseEntry)
+    e.i = i
+    e.j = j
+    e.entry = entry
+    return e
+
+
+cdef class MatrixArgs:
+    # For integers, -1 means unknown
+    # For Python objects, None means unknown
+    cdef public Parent space  # parent of matrix
+    cdef public Parent base   # parent of entries
+    cdef public long nrows, ncols
+    cdef public object entries
+    cdef entries_type typ
+    cdef public bint sparse
+    cdef public dict kwds     # **kwds for MatrixSpace()
+    cdef bint is_finalized
+
+    cpdef Matrix matrix(self, bint convert=?)
+    cpdef list list(self, bint convert=?)
+    cpdef dict dict(self, bint convert=?)
+
+    cdef inline bint ref_safe(self):
+        """
+        Can we safely return self.entries without making a copy?
+        A refcount of 1 means that self.entries is the only reference.
+        """
+        return (<PyObject*>self.entries).ob_refcnt == 1
+
+    cdef inline bint need_to_convert(self, x):
+        """Is ``x`` not an element of ``self.base``?"""
+        if not isinstance(x, Element):
+            return True
+        return (<Element>x)._parent is not self.base
+
+    cdef int set_base_from_entries(self, entries) except -1
+
+    cdef inline int setdefault_base(self, B) except -1:
+        """
+        Set the base ring if not previously set.
+        """
+        if self.base is not None:
+            return 0
+        self.base = <Parent?>B
+
+    cdef inline int set_ncols(self, long n) except -1:
+        """
+        Set the number of columns with consistency checking: if the
+        value was previously set, it must remain the same.
+        """
+        if n < 0:
+            raise ArithmeticError("number of columns must be non-negative")
+        cdef long p = self.ncols
+        if p != -1 and p != n:
+            raise ValueError(f"inconsistent number of columns: should be {p} but got {n}")
+        self.ncols = n
+
+    cdef inline int set_nrows(self, long n) except -1:
+        """
+        Set the number of rows with consistency checking: if the
+        value was previously set, it must remain the same.
+        """
+        if n < 0:
+            raise ArithmeticError("number of rows must be non-negative")
+        cdef long p = self.nrows
+        if p != -1 and p != n:
+            raise ValueError(f"inconsistent number of rows: should be {p} but got {n}")
+        self.nrows = n
+
+    cpdef int set_space(self, space) except -1
+
+    cdef int finalize(self) except -1
+    cdef int process_mapping(self) except -1
+    cdef int process_method(self) except -1
+    cdef int process_ndarray(self) except -1
+    cdef int finalize_seq_seq(self) except -1
+    cdef int finalize_seq_scalar(self) except -1
+    cdef int finalize_callable(self) except -1
+    cdef entries_type get_type(self) except MA_EXCEPT
+    cdef entries_type sequence_type(self) except MA_EXCEPT
+
+    cdef int set_seq_flat(self, entries) except -1
+
+
+cpdef MatrixArgs MatrixArgs_init(space, entries)