Ticket #10734: trac_10734.02-documentation

File trac_10734.02-documentation, 4.9 KB (added by Gonzalo Tornaría, 11 years ago)

Add documentation for the functions added in #10734

Line 
1# HG changeset patch
2# Date 1300849200 10800
3# User Gonzalo Tornaría <tornaria@cmat.edu.uy>
4# Parent fdd7f5196228b647d8e3ab49069a87f1f357b0a3
5Add documentation for the functions added in #10734
6
7diff -r fdd7f5196228 sage/matrix/matrix_modn_dense.pyx
8--- a/sage/matrix/matrix_modn_dense.pyx Wed Feb 02 00:00:00 2011 -0200
9+++ b/sage/matrix/matrix_modn_dense.pyx Mon Jun 13 13:00:26 2011 -0300
10@@ -356,6 +356,9 @@
11         self._matrix[i][j] = (<IntegerMod_int> value).ivalue
12 
13     cdef get_unsafe_int(self, Py_ssize_t i, Py_ssize_t j):
14+        """
15+        Get the (i,j) entry of self as an int value, no checks.
16+        """
17         return self._matrix[i][j]
18 
19     cdef get_unsafe(self, Py_ssize_t i, Py_ssize_t j):
20diff -r fdd7f5196228 sage/matrix/matrix_modn_sparse.pyx
21--- a/sage/matrix/matrix_modn_sparse.pyx        Wed Feb 02 00:00:00 2011 -0200
22+++ b/sage/matrix/matrix_modn_sparse.pyx        Mon Jun 13 13:00:26 2011 -0300
23@@ -527,6 +527,42 @@
24 
25     def submatrix(self, Py_ssize_t row=0, Py_ssize_t col=0,
26                         Py_ssize_t nrows=-1, Py_ssize_t ncols=-1):
27+        """
28+        Return the matrix constructed from self using the specified
29+        range of rows and columns.
30+
31+        INPUT:
32+
33+        - ``row``, ``col`` - index of the starting row and column.
34+          Indices start at zero.
35+
36+        - ``nrows``, ``ncols`` - (optional) number of rows and columns to
37+          take. If not provided, take all rows below and all columns to
38+          the right of the starting entry.
39+
40+        SEE ALSO:
41+
42+        The functions :func:`matrix_from_rows`,
43+        :func:`matrix_from_columns`, and
44+        :func:`matrix_from_rows_and_columns` allow one to select
45+        arbitrary subsets of rows and/or columns.
46+
47+        EXAMPLES:
48+
49+        Take a `3 \\times 3` submatrix of a sparse matrix::
50+
51+            sage: A = matrix(Integers(7), 100, 100, sparse=True)
52+            sage: A[25,25] = 1 ; A[26,24] = 2 ; A[24,26] = 3
53+            sage: A.submatrix(24,24,3,3)
54+            [0 0 3]
55+            [0 1 0]
56+            [2 0 0]
57+
58+        Note that the result is a sparse matrix::
59+
60+            sage: parent(A.submatrix(20,20,50,50))
61+            Full MatrixSpace of 50 by 50 sparse matrices over Ring of integers modulo 7
62+        """
63         cdef Py_ssize_t i, j, pos
64         cdef Matrix_modn_sparse M
65 
66@@ -544,6 +580,27 @@
67         return M
68 
69     def dense_matrix(self):
70+        """
71+        If this matrix is sparse, return a dense matrix with the same
72+        entries. If this matrix is dense, return this matrix (not a copy).
73+
74+        .. note::
75+
76+           The definition of "dense" and "sparse" in Sage have nothing to
77+           do with the number of nonzero entries. Sparse and dense are
78+           properties of the underlying representation of the matrix.
79+
80+        EXAMPLES::
81+
82+            sage: A = matrix(Integers(7), 4, [1..16], sparse=True)
83+            sage: A.is_sparse()
84+            True
85+            sage: B = A.dense_matrix()
86+            sage: parent(A)
87+            Full MatrixSpace of 4 by 4 sparse matrices over Ring of integers modulo 7
88+            sage: parent(B)
89+            Full MatrixSpace of 4 by 4 dense matrices over Ring of integers modulo 7
90+        """
91         cdef Py_ssize_t i, j
92         cdef Matrix_modn_dense M
93 
94@@ -556,6 +613,37 @@
95 
96     def dense_submatrix(self, Py_ssize_t row=0, Py_ssize_t col=0,
97                               Py_ssize_t nrows=-1, Py_ssize_t ncols=-1):
98+        """
99+        Return the matrix constructed from self using the specified
100+        range of rows and columns, as a dense matrix.
101+
102+        INPUT:
103+
104+        - ``row``, ``col`` - index of the starting row and column.
105+          Indices start at zero.
106+
107+        - ``nrows``, ``ncols`` - (optional) number of rows and columns to
108+          take. If not provided, take all rows below and all columns to
109+          the right of the starting entry.
110+
111+        EXAMPLES::
112+
113+        Take a `3 \\times 3` submatrix of a sparse matrix::
114+
115+            sage: A = matrix(Integers(7), 100, 100, sparse=True)
116+            sage: A[25,25] = 1 ; A[26,24] = 2 ; A[24,26] = 3
117+            sage: A.dense_submatrix(24,24,3,3)
118+            [0 0 3]
119+            [0 1 0]
120+            [2 0 0]
121+
122+        Note that the result is a dense matrix::
123+
124+            sage: parent(A.dense_submatrix(20,20,50,50))
125+            Full MatrixSpace of 50 by 50 dense matrices over Ring of integers modulo 7
126+            sage: A.dense_submatrix(20,20,50,50) == A.submatrix(20,20,50,50)
127+            True
128+        """
129         cdef Py_ssize_t i, j, pos
130         cdef Matrix_modn_dense M
131 
132@@ -573,6 +661,10 @@
133         return M
134 
135     cdef set_block_unsafe(self, Py_ssize_t row, Py_ssize_t col, Matrix_modn_dense block):
136+        """
137+        Sets the sub-matrix of self, with upper left corner given by row,
138+        col to block. No checks.
139+        """
140         cdef Py_ssize_t i, j
141         for i from 0 <= i < block.nrows():
142             for j from 0 <= j < block.ncols():