Skip to content

Commit 4e155c5

Browse files
Biffo89Biffo89
committed
update documentation
1 parent fc7856a commit 4e155c5

17 files changed

+585
-34
lines changed

‎src/sage/matrix/matrix0.pyx‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -558,11 +558,25 @@ cdef class Matrix(sage.structure.element.Matrix):
558558

559559
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
560560
"""
561-
Copy from one matrix to another. It is assumed ``src`` is the same type of matrix as ``self``, with the same base ring.
561+
Copy element (iSrc, jSrc) from ``src`` to position (iDst, jDst) in
562+
``self``. It is assumed ``src`` is the same type of matrix as``self``,
563+
with the same base ring.
562564
563-
This is fast because it avoids the type conversion that often is necessary in ``get_unsafe`` and ``set_unsafe``.
565+
This should generally be reimplemented in subclasses to avoid the type
566+
conversion that often is necessary in ``get_unsafe`` and
567+
``set_unsafe``.
568+
569+
INPUT:
570+
571+
- ``iDst`` - the row to be copied to in ``self``.
572+
- ``jDst`` - the column to be copied to in ``self``.
573+
- ``src`` - the matrix to copy from. Should be the same type as
574+
``self`` with the same base ring.
575+
- ``iSrc`` - the row to be copied from in ``src``.
576+
- ``jSrc`` - the column to be copied from in ``src``.
564577
"""
565-
raise NotImplementedError("this must be defined in the derived type.")
578+
cdef Matrix _src = <Matrix>src
579+
self.set_unsafe(iDst, jDst, _src.get_unsafe(iSrc, jSrc))
566580

567581
cdef bint get_is_zero_unsafe(self, Py_ssize_t i, Py_ssize_t j) except -1:
568582
"""

‎src/sage/matrix/matrix_complex_ball_dense.pyx‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -309,13 +309,47 @@ cdef class Matrix_complex_ball_dense(Matrix_dense):
309309

310310
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
311311
"""
312-
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)`` entry of this matrix.
312+
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
313+
entry of ``self``.
313314
314315
.. warning::
315316
316-
This is very unsafe; it assumes ``iSrc``, ``jSrc``, ``iDst`` and ``jDst`` are in the right
317-
range, and that ``src`` is a
317+
This is very unsafe; it assumes ``iSrc``, ``jSrc``, ``iDst`` and
318+
``jDst`` are in the right range, and that ``src`` is a
318319
Matrix_complex_ball_dense with the same base ring as ``self``.
320+
321+
INPUT:
322+
323+
- ``iDst`` - the row to be copied to in ``self``.
324+
- ``jDst`` - the column to be copied to in ``self``.
325+
- ``src`` - the matrix to copy from. Should be a
326+
Matrix_complex_ball_dense with the same base ring as
327+
``self``.
328+
- ``iSrc`` - the row to be copied from in ``src``.
329+
- ``jSrc`` - the column to be copied from in ``src``.
330+
331+
TESTS::
332+
333+
sage: m = MatrixSpace(CBF,3,4)(range(12))
334+
sage: m
335+
[ 0 1.000000000000000 2.000000000000000 3.000000000000000]
336+
[4.000000000000000 5.000000000000000 6.000000000000000 7.000000000000000]
337+
[8.000000000000000 9.000000000000000 10.00000000000000 11.00000000000000]
338+
sage: m.transpose()
339+
[ 0 4.000000000000000 8.000000000000000]
340+
[1.000000000000000 5.000000000000000 9.000000000000000]
341+
[2.000000000000000 6.000000000000000 10.00000000000000]
342+
[3.000000000000000 7.000000000000000 11.00000000000000]
343+
sage: m.matrix_from_rows([0,2])
344+
[ 0 1.000000000000000 2.000000000000000 3.000000000000000]
345+
[8.000000000000000 9.000000000000000 10.00000000000000 11.00000000000000]
346+
sage: m.matrix_from_columns([1,3])
347+
[1.000000000000000 3.000000000000000]
348+
[5.000000000000000 7.000000000000000]
349+
[9.000000000000000 11.00000000000000]
350+
sage: m.matrix_from_rows_and_columns([1,2],[0,3])
351+
[4.000000000000000 7.000000000000000]
352+
[8.000000000000000 11.00000000000000]
319353
"""
320354
cdef Matrix_complex_ball_dense _src = <Matrix_complex_ball_dense> src
321355
acb_set(acb_mat_entry(self.value, iDst, jDst), acb_mat_entry(_src.value, iSrc, jSrc))

‎src/sage/matrix/matrix_cyclo_dense.pyx‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -409,10 +409,45 @@ cdef class Matrix_cyclo_dense(Matrix_dense):
409409

410410
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
411411
"""
412-
Copy the (iSrc,jSrc)-th entry of ``src`` to the (iDst,jDst)-th entry ``self``.
412+
Copy the (iSrc,jSrc)-th entry of ``src`` to the (iDst,jDst)-th entry
413+
``self``.
413414
414-
WARNING: As the name suggests, expect segfaults if iSrc,jSrc,iDst,jDst are out
415-
of bounds!! This is for internal use only. This method assumes ``src`` is a Matrix_cyclo_dense with the same base ring as ``self``.
415+
WARNING: As the name suggests, expect segfaults if iSrc,jSrc,iDst,jDst
416+
are out of bounds!! This is for internal use only. This method assumes
417+
``src`` is a Matrix_cyclo_dense with the same base ring as ``self``.
418+
419+
INPUT:
420+
421+
- ``iDst`` - the row to be copied to in ``self``.
422+
- ``jDst`` - the column to be copied to in ``self``.
423+
- ``src`` - the matrix to copy from. Should be a Matrix_cyclo_dense
424+
with the same base ring as ``self``.
425+
- ``iSrc`` - the row to be copied from in ``src``.
426+
- ``jSrc`` - the column to be copied from in ``src``.
427+
428+
TESTS::
429+
430+
sage: K.<z> = CyclotomicField(3)
431+
sage: M = matrix(K,3,4,[i + z/(i+1) for i in range(12)])
432+
sage: M
433+
[ z 1/2*z + 1 1/3*z + 2 1/4*z + 3]
434+
[ 1/5*z + 4 1/6*z + 5 1/7*z + 6 1/8*z + 7]
435+
[ 1/9*z + 8 1/10*z + 9 1/11*z + 10 1/12*z + 11]
436+
sage: M.transpose()
437+
[ z 1/5*z + 4 1/9*z + 8]
438+
[ 1/2*z + 1 1/6*z + 5 1/10*z + 9]
439+
[ 1/3*z + 2 1/7*z + 6 1/11*z + 10]
440+
[ 1/4*z + 3 1/8*z + 7 1/12*z + 11]
441+
sage: M.matrix_from_rows([0,2])
442+
[ z 1/2*z + 1 1/3*z + 2 1/4*z + 3]
443+
[ 1/9*z + 8 1/10*z + 9 1/11*z + 10 1/12*z + 11]
444+
sage: M.matrix_from_columns([1,3])
445+
[ 1/2*z + 1 1/4*z + 3]
446+
[ 1/6*z + 5 1/8*z + 7]
447+
[ 1/10*z + 9 1/12*z + 11]
448+
sage: M.matrix_from_rows_and_columns([1,2],[0,3])
449+
[ 1/5*z + 4 1/8*z + 7]
450+
[ 1/9*z + 8 1/12*z + 11]
416451
"""
417452
cdef Matrix_cyclo_dense _src = src
418453
cdef int a

‎src/sage/matrix/matrix_gap.pyx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,42 @@ cdef class Matrix_gap(Matrix_dense):
205205
self._libgap[i,j] = x
206206

207207
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
208+
r"""
209+
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
210+
entry of ``self``.
211+
212+
INPUT:
213+
214+
- ``iDst`` - the row to be copied to in ``self``.
215+
- ``jDst`` - the column to be copied to in ``self``.
216+
- ``src`` - the matrix to copy from. Should be a Matrix_gap with the
217+
same base ring as ``self``.
218+
- ``iSrc`` - the row to be copied from in ``src``.
219+
- ``jSrc`` - the column to be copied from in ``src``.
220+
221+
TESTS::
222+
223+
sage: M = MatrixSpace(ZZ, 3, 4, implementation='gap')(range(12))
224+
sage: M
225+
[ 0 1 2 3]
226+
[ 4 5 6 7]
227+
[ 8 9 10 11]
228+
sage: M.transpose()
229+
[ 0 4 8]
230+
[ 1 5 9]
231+
[ 2 6 10]
232+
[ 3 7 11]
233+
sage: M.matrix_from_rows([0,2])
234+
[ 0 1 2 3]
235+
[ 8 9 10 11]
236+
sage: M.matrix_from_columns([1,3])
237+
[ 1 3]
238+
[ 5 7]
239+
[ 9 11]
240+
sage: M.matrix_from_rows_and_columns([1,2],[0,3])
241+
[ 4 7]
242+
[ 8 11]
243+
"""
208244
cdef Matrix_gap _src = <Matrix_gap>src
209245
self._libgap[iDst,jDst] = _src._libgap[iSrc,jSrc]
210246

‎src/sage/matrix/matrix_generic_dense.pyx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,43 @@ cdef class Matrix_generic_dense(matrix_dense.Matrix_dense):
100100
return self._entries[i*self._ncols + j]
101101

102102
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
103+
r"""
104+
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
105+
entry of ``self``.
106+
107+
INPUT:
108+
109+
- ``iDst`` - the row to be copied to in ``self``.
110+
- ``jDst`` - the column to be copied to in ``self``.
111+
- ``src`` - the matrix to copy from. Should be a Matrix_generic_dense
112+
with the same base ring as ``self``.
113+
- ``iSrc`` - the row to be copied from in ``src``.
114+
- ``jSrc`` - the column to be copied from in ``src``.
115+
116+
TESTS::
117+
118+
sage: K.<z> = GF(9)
119+
sage: m = matrix(K,3,4,[((i%9)//3)*z + i%3 for i in range(12)])
120+
sage: m
121+
[ 0 1 2 z]
122+
[ z + 1 z + 2 2*z 2*z + 1]
123+
[2*z + 2 0 1 2]
124+
sage: m.transpose()
125+
[ 0 z + 1 2*z + 2]
126+
[ 1 z + 2 0]
127+
[ 2 2*z 1]
128+
[ z 2*z + 1 2]
129+
sage: m.matrix_from_rows([0,2])
130+
[ 0 1 2 z]
131+
[2*z + 2 0 1 2]
132+
sage: m.matrix_from_columns([1,3])
133+
[ 1 z]
134+
[ z + 2 2*z + 1]
135+
[ 0 2]
136+
sage: m.matrix_from_rows_and_columns([1,2],[0,3])
137+
[ z + 1 2*z + 1]
138+
[2*z + 2 2]
139+
"""
103140
cdef Matrix_generic_dense _src = <Matrix_generic_dense>src
104141
self._entries[iDst*self._ncols + jDst] = _src._entries[iSrc*_src._ncols + jSrc]
105142

‎src/sage/matrix/matrix_generic_sparse.pyx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,43 @@ cdef class Matrix_generic_sparse(matrix_sparse.Matrix_sparse):
201201
return self._entries.get((i,j), self._zero)
202202

203203
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
204+
r"""
205+
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
206+
entry of ``self``.
207+
208+
INPUT:
209+
210+
- ``iDst`` - the row to be copied to in ``self``.
211+
- ``jDst`` - the column to be copied to in ``self``.
212+
- ``src`` - the matrix to copy from. Should be a Matrix_generic_sparse
213+
with the same base ring as ``self``.
214+
- ``iSrc`` - the row to be copied from in ``src``.
215+
- ``jSrc`` - the column to be copied from in ``src``.
216+
217+
TESTS::
218+
219+
sage: K.<z> = GF(9)
220+
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)
221+
sage: m
222+
[ 0 0 2 z]
223+
[ 0 z + 2 0 2*z + 1]
224+
[ 0 0 0 2]
225+
sage: m.transpose()
226+
[ 0 0 0]
227+
[ 0 z + 2 0]
228+
[ 2 0 0]
229+
[ z 2*z + 1 2]
230+
sage: m.matrix_from_rows([0,2])
231+
[0 0 2 z]
232+
[0 0 0 2]
233+
sage: m.matrix_from_columns([1,3])
234+
[ 0 z]
235+
[ z + 2 2*z + 1]
236+
[ 0 2]
237+
sage: m.matrix_from_rows_and_columns([1,2],[0,3])
238+
[ 0 2*z + 1]
239+
[ 0 2]
240+
"""
204241
cdef Matrix_generic_sparse _src = <Matrix_generic_sparse>src
205242
if (iSrc,jSrc) in _src._entries:
206243
self._entries[(iDst,jDst)] = _src._entries.get((iSrc, jSrc), _src._zero)

‎src/sage/matrix/matrix_gf2e_dense.pyx‎

Lines changed: 33 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -286,16 +286,42 @@ cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense):
286286
return cache.fetch_int(r)
287287

288288
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
289-
"""
290-
A[iDst,jDst] = B[iSrc,jSrc] without bound checks.
289+
r"""
290+
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
291+
entry of ``self``.
291292
292293
INPUT:
293294
294-
- ``iDst`` -- row index
295-
- ``jDst`` -- column index
296-
- ``src`` -- source matrix, assumed to be a Matrix_gf2e_dense, with same base ring
297-
- ``iSrc`` -- row index
298-
- ``jSrc`` -- column index
295+
- ``iDst`` - the row to be copied to in ``self``.
296+
- ``jDst`` - the column to be copied to in ``self``.
297+
- ``src`` - the matrix to copy from. Should be a Matrix_gf2e_dense with
298+
the same base ring as ``self``.
299+
- ``iSrc`` - the row to be copied from in ``src``.
300+
- ``jSrc`` - the column to be copied from in ``src``.
301+
302+
TESTS::
303+
304+
sage: K.<z> = GF(512)
305+
sage: m = matrix(K,3,4,[sum([(i//(2^j))%2 * z^j for j in range(4)]) for i in range(12)])
306+
sage: m
307+
[ 0 1 z z + 1]
308+
[ z^2 z^2 + 1 z^2 + z z^2 + z + 1]
309+
[ z^3 z^3 + 1 z^3 + z z^3 + z + 1]
310+
sage: m.transpose()
311+
[ 0 z^2 z^3]
312+
[ 1 z^2 + 1 z^3 + 1]
313+
[ z z^2 + z z^3 + z]
314+
[ z + 1 z^2 + z + 1 z^3 + z + 1]
315+
sage: m.matrix_from_rows([0,2])
316+
[ 0 1 z z + 1]
317+
[ z^3 z^3 + 1 z^3 + z z^3 + z + 1]
318+
sage: m.matrix_from_columns([1,3])
319+
[ 1 z + 1]
320+
[ z^2 + 1 z^2 + z + 1]
321+
[ z^3 + 1 z^3 + z + 1]
322+
sage: m.matrix_from_rows_and_columns([1,2],[0,3])
323+
[ z^2 z^2 + z + 1]
324+
[ z^3 z^3 + z + 1]
299325
"""
300326
cdef Matrix_gf2e_dense _src = <Matrix_gf2e_dense>src
301327
mzed_write_elem(self._entries, iDst, jDst, mzed_read_elem(_src._entries, iSrc, jSrc))

‎src/sage/matrix/matrix_gfpn_dense.pyx‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -674,8 +674,42 @@ cdef class Matrix_gfpn_dense(Matrix_dense):
674674
sig_off()
675675

676676
cdef copy_from_unsafe(self, Py_ssize_t iDst, Py_ssize_t jDst, src, Py_ssize_t iSrc, Py_ssize_t jSrc):
677-
"""
678-
Copies values without bound or type checking.
677+
r"""
678+
Copy the ``(iSrc, jSrc)`` entry of ``src`` into the ``(iDst, jDst)``
679+
entry of ``self``.
680+
681+
INPUT:
682+
683+
- ``iDst`` - the row to be copied to in ``self``.
684+
- ``jDst`` - the column to be copied to in ``self``.
685+
- ``src`` - the matrix to copy from. Should be a Matrix_gfpn_dense with
686+
the same base ring as ``self``.
687+
- ``iSrc`` - the row to be copied from in ``src``.
688+
- ``jSrc`` - the column to be copied from in ``src``.
689+
690+
TESTS::
691+
692+
sage: K.<z> = GF(59)
693+
sage: M = MatrixSpace(K, 3, 4, implementation=Matrix_gfpn_dense)(range(12))
694+
sage: M
695+
[ 0 1 2 3]
696+
[ 4 5 6 7]
697+
[ 8 9 10 11]
698+
sage: M.transpose()
699+
[ 0 4 8]
700+
[ 1 5 9]
701+
[ 2 6 10]
702+
[ 3 7 11]
703+
sage: M.matrix_from_rows([0,2])
704+
[ 0 1 2 3]
705+
[ 8 9 10 11]
706+
sage: M.matrix_from_columns([1,3])
707+
[ 1 3]
708+
[ 5 7]
709+
[ 9 11]
710+
sage: M.matrix_from_rows_and_columns([1,2],[0,3])
711+
[ 4 7]
712+
[ 8 11]
679713
"""
680714
cdef Matrix_gfpn_dense _src = <Matrix_gfpn_dense>src
681715
FfInsert(FfGetPtr(self.Data.Data, iDst), jDst, FfExtract(MatGetPtr(_src.Data,iSrc), jSrc))

0 commit comments

Comments
 (0)