update documentation

Author: Biffo89

src/sage/matrix/matrix0.pyx

@@ -558,11 +558,25 @@ cdef class Matrix(sage.structure.element.Matrix):
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
         """
-        Copy from one matrix to another. It is assumed ``src`` is the same type of matrix as ``self``, with the same base ring.
+        Copy element (iSrc, jSrc) from ``src`` to position (iDst, jDst) in
+        ``self``. It is assumed ``src`` is the same type of matrix as``self``,
+        with the same base ring.
 
-        This is fast because it avoids the type conversion that often is necessary in ``get_unsafe`` and ``set_unsafe``.
+        This should generally be reimplemented in subclasses to avoid the type
+        conversion that often is necessary in ``get_unsafe`` and
+        ``set_unsafe``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be the same type as
+                    ``self`` with the same base ring.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
         """
-        raise NotImplementedError("this must be defined in the derived type.")
+        cdef Matrix _src = <Matrix>src
+        self.set_unsafe(iDst, jDst, _src.get_unsafe(iSrc, jSrc))
 
     cdef bint get_is_zero_unsafe(self, Py_ssize_t i, Py_ssize_t j) except -1:
         """

src/sage/matrix/matrix_complex_ball_dense.pyx

@@ -309,13 +309,47 @@ cdef class Matrix_complex_ball_dense(Matrix_dense):
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
         """
-        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)`` entry of this matrix.
+        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
+        entry of ``self``.
 
         .. warning::
 
-           This is very unsafe; it assumes ``iSrc``, ``jSrc``, ``iDst`` and ``jDst`` are in the right
-           range, and that ``src`` is a
+           This is very unsafe; it assumes ``iSrc``, ``jSrc``, ``iDst`` and
+           ``jDst`` are in the right range, and that ``src`` is a
            Matrix_complex_ball_dense with the same base ring as ``self``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a
+                    Matrix_complex_ball_dense with the same base ring as
+                    ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: m = MatrixSpace(CBF,3,4)(range(12))
+            sage: m
+            [                0 1.000000000000000 2.000000000000000 3.000000000000000]
+            [4.000000000000000 5.000000000000000 6.000000000000000 7.000000000000000]
+            [8.000000000000000 9.000000000000000 10.00000000000000 11.00000000000000]
+            sage: m.transpose()
+            [                0 4.000000000000000 8.000000000000000]
+            [1.000000000000000 5.000000000000000 9.000000000000000]
+            [2.000000000000000 6.000000000000000 10.00000000000000]
+            [3.000000000000000 7.000000000000000 11.00000000000000]
+            sage: m.matrix_from_rows([0,2])
+            [                0 1.000000000000000 2.000000000000000 3.000000000000000]
+            [8.000000000000000 9.000000000000000 10.00000000000000 11.00000000000000]
+            sage: m.matrix_from_columns([1,3])
+            [1.000000000000000 3.000000000000000]
+            [5.000000000000000 7.000000000000000]
+            [9.000000000000000 11.00000000000000]
+            sage: m.matrix_from_rows_and_columns([1,2],[0,3])
+            [4.000000000000000 7.000000000000000]
+            [8.000000000000000 11.00000000000000]
         """
         cdef Matrix_complex_ball_dense _src = <Matrix_complex_ball_dense> src
         acb_set(acb_mat_entry(self.value, iDst, jDst), acb_mat_entry(_src.value, iSrc, jSrc))

src/sage/matrix/matrix_cyclo_dense.pyx

@@ -409,10 +409,45 @@ cdef class Matrix_cyclo_dense(Matrix_dense):
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
         """
-        Copy the (iSrc,jSrc)-th entry of ``src`` to the (iDst,jDst)-th entry ``self``.
+        Copy the (iSrc,jSrc)-th entry of ``src`` to the (iDst,jDst)-th entry
+        ``self``.
 
-        WARNING: As the name suggests, expect segfaults if iSrc,jSrc,iDst,jDst are out
-        of bounds!! This is for internal use only. This method assumes ``src`` is a Matrix_cyclo_dense with the same base ring as ``self``.
+        WARNING: As the name suggests, expect segfaults if iSrc,jSrc,iDst,jDst
+        are out of bounds!! This is for internal use only. This method assumes
+        ``src`` is a Matrix_cyclo_dense with the same base ring as ``self``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a Matrix_cyclo_dense
+                    with the same base ring as ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: K.<z> = CyclotomicField(3)
+            sage: M = matrix(K,3,4,[i + z/(i+1) for i in range(12)])
+            sage: M
+            [          z   1/2*z + 1   1/3*z + 2   1/4*z + 3]
+            [  1/5*z + 4   1/6*z + 5   1/7*z + 6   1/8*z + 7]
+            [  1/9*z + 8  1/10*z + 9 1/11*z + 10 1/12*z + 11]
+            sage: M.transpose()
+            [          z   1/5*z + 4   1/9*z + 8]
+            [  1/2*z + 1   1/6*z + 5  1/10*z + 9]
+            [  1/3*z + 2   1/7*z + 6 1/11*z + 10]
+            [  1/4*z + 3   1/8*z + 7 1/12*z + 11]
+            sage: M.matrix_from_rows([0,2])
+            [          z   1/2*z + 1   1/3*z + 2   1/4*z + 3]
+            [  1/9*z + 8  1/10*z + 9 1/11*z + 10 1/12*z + 11]
+            sage: M.matrix_from_columns([1,3])
+            [  1/2*z + 1   1/4*z + 3]
+            [  1/6*z + 5   1/8*z + 7]
+            [ 1/10*z + 9 1/12*z + 11]
+            sage: M.matrix_from_rows_and_columns([1,2],[0,3])
+            [  1/5*z + 4   1/8*z + 7]
+            [  1/9*z + 8 1/12*z + 11]
         """
         cdef Matrix_cyclo_dense _src = src
         cdef int a

src/sage/matrix/matrix_gap.pyx

@@ -205,6 +205,42 @@ cdef class Matrix_gap(Matrix_dense):
         self._libgap[i,j] = x
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
+        r"""
+        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
+        entry of ``self``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a Matrix_gap with the
+                    same base ring as ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: M = MatrixSpace(ZZ, 3, 4, implementation='gap')(range(12))
+            sage: M
+            [ 0  1  2  3]
+            [ 4  5  6  7]
+            [ 8  9 10 11]
+            sage: M.transpose()
+            [ 0  4  8]
+            [ 1  5  9]
+            [ 2  6 10]
+            [ 3  7 11]
+            sage: M.matrix_from_rows([0,2])
+            [ 0  1  2  3]
+            [ 8  9 10 11]
+            sage: M.matrix_from_columns([1,3])
+            [ 1  3]
+            [ 5  7]
+            [ 9 11]
+            sage: M.matrix_from_rows_and_columns([1,2],[0,3])
+            [ 4  7]
+            [ 8 11]
+        """
         cdef Matrix_gap _src = <Matrix_gap>src
         self._libgap[iDst,jDst] = _src._libgap[iSrc,jSrc]
 

src/sage/matrix/matrix_generic_dense.pyx

@@ -100,6 +100,43 @@ cdef class Matrix_generic_dense(matrix_dense.Matrix_dense):
         return self._entries[i*self._ncols + j]
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
+        r"""
+        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
+        entry of ``self``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a Matrix_generic_dense
+                    with the same base ring as ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: K.<z> = GF(9)
+            sage: m = matrix(K,3,4,[((i%9)//3)*z + i%3 for i in range(12)])
+            sage: m
+            [      0       1       2       z]
+            [  z + 1   z + 2     2*z 2*z + 1]
+            [2*z + 2       0       1       2]
+            sage: m.transpose()
+            [      0   z + 1 2*z + 2]
+            [      1   z + 2       0]
+            [      2     2*z       1]
+            [      z 2*z + 1       2]
+            sage: m.matrix_from_rows([0,2])
+            [      0       1       2       z]
+            [2*z + 2       0       1       2]
+            sage: m.matrix_from_columns([1,3])
+            [      1       z]
+            [  z + 2 2*z + 1]
+            [      0       2]
+            sage: m.matrix_from_rows_and_columns([1,2],[0,3])
+            [  z + 1 2*z + 1]
+            [2*z + 2       2]
+        """
         cdef Matrix_generic_dense _src = <Matrix_generic_dense>src
         self._entries[iDst*self._ncols + jDst] = _src._entries[iSrc*_src._ncols + jSrc]
 

src/sage/matrix/matrix_generic_sparse.pyx

@@ -201,6 +201,43 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse):
         return self._entries.get((i,j), self._zero)
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
+        r"""
+        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
+        entry of ``self``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a Matrix_generic_sparse
+                    with the same base ring as ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: K.<z> = GF(9)
+            sage: m = matrix(K,3,4,[((i%9)//3)*z + i%3 if is_prime(i) else 0 for i in range(12)],sparse=True)
+            sage: m
+            [      0       0       2       z]
+            [      0   z + 2       0 2*z + 1]
+            [      0       0       0       2]
+            sage: m.transpose()
+            [      0       0       0]
+            [      0   z + 2       0]
+            [      2       0       0]
+            [      z 2*z + 1       2]
+            sage: m.matrix_from_rows([0,2])
+            [0 0 2 z]
+            [0 0 0 2]
+            sage: m.matrix_from_columns([1,3])
+            [      0       z]
+            [  z + 2 2*z + 1]
+            [      0       2]
+            sage: m.matrix_from_rows_and_columns([1,2],[0,3])
+            [      0 2*z + 1]
+            [      0       2]
+        """
         cdef Matrix_generic_sparse _src = <Matrix_generic_sparse>src
         if (iSrc,jSrc) in _src._entries:
             self._entries[(iDst,jDst)] = _src._entries.get((iSrc, jSrc), _src._zero)

src/sage/matrix/matrix_gf2e_dense.pyx

@@ -286,16 +286,42 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense):
         return cache.fetch_int(r)
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
-        """
-        A[iDst,jDst] = B[iSrc,jSrc] without bound checks.
+        r"""
+        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
+        entry of ``self``.
 
         INPUT:
 
-        - ``iDst`` -- row index
-        - ``jDst`` -- column index
-        - ``src``  -- source matrix, assumed to be a Matrix_gf2e_dense, with same base ring
-        - ``iSrc`` -- row index
-        - ``jSrc`` -- column index
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a Matrix_gf2e_dense with
+                    the same base ring as ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: K.<z> = GF(512)
+            sage: m = matrix(K,3,4,[sum([(i//(2^j))%2 * z^j for j in range(4)]) for i in range(12)])
+            sage: m
+            [          0           1           z       z + 1]
+            [        z^2     z^2 + 1     z^2 + z z^2 + z + 1]
+            [        z^3     z^3 + 1     z^3 + z z^3 + z + 1]
+            sage: m.transpose()
+            [          0         z^2         z^3]
+            [          1     z^2 + 1     z^3 + 1]
+            [          z     z^2 + z     z^3 + z]
+            [      z + 1 z^2 + z + 1 z^3 + z + 1]
+            sage: m.matrix_from_rows([0,2])
+            [          0           1           z       z + 1]
+            [        z^3     z^3 + 1     z^3 + z z^3 + z + 1]
+            sage: m.matrix_from_columns([1,3])
+            [          1       z + 1]
+            [    z^2 + 1 z^2 + z + 1]
+            [    z^3 + 1 z^3 + z + 1]
+            sage: m.matrix_from_rows_and_columns([1,2],[0,3])
+            [        z^2 z^2 + z + 1]
+            [        z^3 z^3 + z + 1]
         """
         cdef Matrix_gf2e_dense _src = <Matrix_gf2e_dense>src
         mzed_write_elem(self._entries, iDst, jDst, mzed_read_elem(_src._entries, iSrc, jSrc))

src/sage/matrix/matrix_gfpn_dense.pyx

@@ -674,8 +674,42 @@ cdef class Matrix_gfpn_dense(Matrix_dense):
             sig_off()
 
     cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
-        """
-        Copies values without bound or type checking.
+        r"""
+        Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
+        entry of ``self``.
+
+        INPUT:
+
+        - ``iDst`` - the row to be copied to in ``self``.
+        - ``jDst`` - the column to be copied to in ``self``.
+        - ``src`` - the matrix to copy from. Should be a Matrix_gfpn_dense with
+                    the same base ring as ``self``.
+        - ``iSrc``  - the row to be copied from in ``src``.
+        - ``jSrc`` - the column to be copied from in ``src``.
+
+        TESTS::
+
+            sage: K.<z> = GF(59)
+            sage: M = MatrixSpace(K, 3, 4, implementation=Matrix_gfpn_dense)(range(12))
+            sage: M
+            [ 0  1  2  3]
+            [ 4  5  6  7]
+            [ 8  9 10 11]
+            sage: M.transpose()
+            [ 0  4  8]
+            [ 1  5  9]
+            [ 2  6 10]
+            [ 3  7 11]
+            sage: M.matrix_from_rows([0,2])
+            [ 0  1  2  3]
+            [ 8  9 10 11]
+            sage: M.matrix_from_columns([1,3])
+            [ 1  3]
+            [ 5  7]
+            [ 9 11]
+            sage: M.matrix_from_rows_and_columns([1,2],[0,3])
+            [ 4  7]
+            [ 8 11]
         """
         cdef Matrix_gfpn_dense _src = <Matrix_gfpn_dense>src
         FfInsert(FfGetPtr(self.Data.Data, iDst), jDst, FfExtract(MatGetPtr(_src.Data,iSrc), jSrc))