Ticket #4260: trac_4260_more_doctests.patch

File trac_4260_more_doctests.patch, 90.4 KB (added by malb, 9 years ago)
  • sage/matrix/matrix_modn_dense_template.pxi

    # HG changeset patch
    # User Martin Albrecht <martinralbrecht@googlemail.com>
    # Date 1314340963 -3600
    # Node ID 66236f48a4e582eb5ee0235190480ce089829874
    # Parent  64c6dc325c7a1ca3a460e74f19a4390fc48efa9b
    #4260 more doctests
    
    diff -r 64c6dc325c7a -r 66236f48a4e5 sage/matrix/matrix_modn_dense_template.pxi
    a b  
    44FFLAS/FFPACK are libraries to provide BLAS/LAPACK-style routines for
    55working with finite fields. Additionally, these routines reduce to
    66BLAS/LAPACK routines using floating point arithmetic.
     7
     8EXAMPLES::
     9
     10    sage: A = matrix(GF(127), 7, 7, range(49))
     11    sage: A*A
     12    [  2  23  44  65  86 107   1]
     13    [ 15  85  28  98  41 111  54]
     14    [ 28  20  12   4 123 115 107]
     15    [ 41  82 123  37  78 119  33]
     16    [ 54  17 107  70  33 123  86]
     17    [ 67  79  91 103 115   0  12]
     18    [ 80  14  75   9  70   4  65]
     19    sage: A.rank()
     20    2
     21
     22    sage: A = matrix(GF(127), 4, 4, [106, 98, 24, 84, 108, 7, 94, 71, 96, 100, 15, 42, 80, 56, 72, 35])
     23    sage: A.rank()
     24    4
     25    sage: v = vector(GF(127), 4, (100, 93, 47, 110))
     26    sage: x = A\v
     27    sage: A*x == v
     28    True
     29
     30AUTHORS:
     31
     32- William Stein (2004-2006): some functions in this file were copied
     33  from ``matrix_modn_dense.pyx`` which was mainly written by William
     34  Stein
     35- Clement Pernet (2010): LinBox related functions in this file were
     36  taken from linbox-sage.C by Clement Pernet
     37- Burcin Erocal (2010-2011): most of the functions present in this file
     38- Martin Albrecht (2011): some polishing, bug fixes, documentation
     39- Rob Beezer (2011): documentation
    740"""
    841
    942###############################################################################
     
    1144#       Copyright (C) 2004,2005,2006 William Stein <wstein@gmail.com>
    1245#       Copyright (C) 2011 Burcin Erocal <burcin@erocal.org>
    1346#       Copyright (C) 2011 Martin Albrecht <martinralbrecht@googlemail.com>
     47#       Copyright (C) 2011 Rob Beezer
    1448#  Distributed under the terms of the GNU General Public License (GPL),
    1549#  version 2 or any later version.  The full text of the GPL is available at:
    1650#                  http://www.gnu.org/licenses/
     
    1953from sage.libs.linbox.fflas cimport fflas_trans_enum, fflas_no_trans, fflas_trans, \
    2054    fflas_right, vector, list as std_list
    2155
    22 import sage.ext.multi_modular
    2356cimport sage.rings.fast_arith
    2457cdef sage.rings.fast_arith.arith_int ArithIntObj
    2558ArithIntObj  = sage.rings.fast_arith.arith_int()
    2659
     60# for copying
    2761cdef extern from *:
    2862    void* memcpy(void* dst, void* src, long n)
    2963
     64# for pickling
    3065cdef extern from "stdio.h":
    3166    int snprintf(char *str, size_t size, char *format, ...)
    3267
     
    3671from sage.structure.element cimport ModuleElement
    3772
    3873cimport matrix_dense
    39 cimport matrix
    40 cimport matrix0
    41 cimport sage.structure.element
    4274
    4375from sage.structure.element cimport Matrix
    4476from sage.rings.finite_rings.integer_mod cimport IntegerMod_int, IntegerMod_abstract
     
    96128cdef inline linbox_echelonize(celement modulus, celement* entries, Py_ssize_t nrows, Py_ssize_t ncols):
    97129    """
    98130    Return the reduced row echelon form of this matrix.
    99 
    100     EXAMPLES::
    101 
    102         sage: A = random_matrix(GF(7), 10, 20); A
    103         [3 1 6 6 4 4 2 2 3 5 4 5 6 2 2 1 2 5 0 5]
    104         [3 2 0 5 0 1 5 4 2 3 6 4 5 0 2 4 2 0 6 3]
    105         [2 2 4 2 4 5 3 4 4 4 2 5 2 5 4 5 1 1 1 1]
    106         [0 6 3 4 2 2 3 5 1 1 4 2 6 5 6 3 4 5 5 3]
    107         [5 2 4 3 6 2 3 6 2 1 3 3 5 3 4 2 2 1 6 2]
    108         [0 5 6 3 2 5 6 6 3 2 1 4 5 0 2 6 5 2 5 1]
    109         [4 0 4 2 6 3 3 5 3 0 0 1 2 5 5 1 6 0 0 3]
    110         [2 0 1 0 0 3 0 2 4 2 2 4 4 4 5 4 1 2 3 4]
    111         [2 4 1 4 3 0 6 2 2 5 2 5 3 6 4 2 2 6 4 4]
    112         [0 0 2 2 1 6 2 0 5 0 4 3 1 6 0 6 0 4 6 5]
    113 
    114         sage: A.echelon_form()
    115         [1 0 0 0 0 0 0 0 0 0 6 2 6 0 1 1 2 5 6 2]
    116         [0 1 0 0 0 0 0 0 0 0 0 4 5 4 3 4 2 5 1 2]
    117         [0 0 1 0 0 0 0 0 0 0 6 3 4 6 1 0 3 6 5 6]
    118         [0 0 0 1 0 0 0 0 0 0 0 3 5 2 3 4 0 6 5 3]
    119         [0 0 0 0 1 0 0 0 0 0 0 6 3 4 5 3 0 4 3 2]
    120         [0 0 0 0 0 1 0 0 0 0 1 1 0 2 4 2 5 5 5 0]
    121         [0 0 0 0 0 0 1 0 0 0 1 0 1 3 2 0 0 0 5 3]
    122         [0 0 0 0 0 0 0 1 0 0 4 4 2 6 5 4 3 4 1 0]
    123         [0 0 0 0 0 0 0 0 1 0 1 0 4 2 3 5 4 6 4 0]
    124         [0 0 0 0 0 0 0 0 0 1 2 0 5 0 5 5 3 1 1 4]
    125 
    126     ::
    127 
    128         sage: A = random_matrix(GF(13), 10, 10); A
    129         [ 8  3 11 11  9  4  8  7  9  9]
    130         [ 2  9  6  5  7 12  3  4 11  5]
    131         [12  6 11 12  4  3  3  8  9  5]
    132         [ 4  2 10  5 10  1  1  1  6  9]
    133         [12  8  5  5 11  4  1  2  8 11]
    134         [ 2  6  9 11  4  7  1  0 12  2]
    135         [ 8  9  0  7  7  7 10  4  1  4]
    136         [ 0  8  2  6  7  5  7 12  2  3]
    137         [ 2 11 12  3  4  7  2  9  6  1]
    138         [ 0 11  5  9  4  5  5  8  7 10]
    139 
    140         sage: MS = parent(A)
    141         sage: B = A.augment(MS(1))
    142         sage: B.echelonize()
    143         sage: A.rank()
    144         10
    145         sage: C = B.submatrix(0,10,10,10); C
    146         [ 4  9  4  4  0  4  7 11  9 11]
    147         [11  7  6  8  2  8  6 11  9  5]
    148         [ 3  9  9  2  4  8  9  2  9  4]
    149         [ 7  0 11  4  0  9  6 11  8  1]
    150         [12 12  4 12  3 12  6  1  7 12]
    151         [12  2 11  6  6  6  7  0 10  6]
    152         [ 0  7  3  4  7 11 10 12  4  6]
    153         [ 5 11  0  5  3 11  4 12  5 12]
    154         [ 6  7  3  5  1  4 11  7  4  1]
    155         [ 4  9  6  7 11  1  2 12  6  7]
    156 
    157         sage: ~A == C
    158         True
    159        
    160     ::
    161        
    162         sage: A = random_matrix(Integers(10), 10, 20); A
    163         [1 8 0 7 7 8 0 5 9 1 3 6 7 1 5 9 6 1 1 6]
    164         [2 7 2 7 3 7 8 3 9 3 6 1 3 4 4 8 1 9 1 1]
    165         [8 6 2 1 0 0 9 0 9 1 1 2 6 8 5 7 6 3 7 0]
    166         [9 8 7 4 8 0 0 8 0 3 8 4 4 8 5 1 7 9 9 7]
    167         [3 5 9 2 2 0 6 7 1 7 4 0 9 4 3 6 8 3 5 1]
    168         [2 8 3 7 7 6 9 4 2 7 6 5 7 0 4 8 6 7 5 3]
    169         [1 4 1 2 5 3 4 8 1 3 7 5 8 9 7 8 7 6 8 1]
    170         [5 1 8 4 6 3 8 8 1 3 4 8 4 0 7 8 7 7 5 9]
    171         [7 9 6 7 4 3 7 1 0 3 1 7 5 0 4 2 1 7 1 7]
    172         [3 7 1 8 2 2 6 0 1 8 9 3 4 8 1 0 6 3 3 8]
    173 
    174         sage: A.echelon_form()
    175         Traceback (most recent call last):
    176         ...
    177         NotImplementedError: Echelon form not implemented over 'Ring of integers modulo 10'.
    178        
    179     ::
    180         sage: A = random_matrix(GF(16007), 10, 20); A
    181         [15455  1177 10072  4693  3887  4102 10746 15265  6684 14559  4535 13921  9757  9525  9301  8566  2460  9609  3887  6205]
    182         [ 8602 10035  1242  9776   162  7893 12619  6660 13250  1988 14263 11377  2216  1247  7261  8446 15081 14412  7371  7948]
    183         [12634  7602   905  9617 13557  2694 13039  4936 12208 15480  3787 11229   593 12462  5123 14167  6460  3649  5821  6736]
    184         [10554  2511 11685 12325 12287  6534 11636  5004  6468  3180  3607 11627 13436  5106  3138 13376  8641  9093  2297  5893]
    185         [ 1025 11376 10288   609 12330  3021   908 13012  2112 11505    56  5971   338  2317  2396  8561  5593  3782  7986 13173]
    186         [ 7607   588  6099 12749 10378   111  2852 10375  8996  7969   774 13498 12720  4378  6817  6707  5299  9406 13318  2863]
    187         [15545   538  4840  1885  8471  1303 11086 14168  1853 14263  3995 12104  1294  7184  1188 11901 15971  2899  4632   711]
    188         [  584 11745  7540 15826 15027  5953  7097 14329 10889 12532 13309 15041  6211  1749 10481  9999  2751 11068    21  2795]
    189         [  761 11453  3435 10596  2173  7752 15941 14610  1072  8012  9458  5440   612 10581 10400   101 11472 13068  7758  7898]
    190         [10658  4035  6662   655  7546  4107  6987  1877  4072  4221  7679 14579  2474  8693  8127 12999 11141   605  9404 10003]
    191         sage: A.echelon_form()
    192         [    1     0     0     0     0     0     0     0     0     0  8416  8364 10318  1782 13872  4566 14855  7678 11899  2652]
    193         [    0     1     0     0     0     0     0     0     0     0  4782 15571  3133 10964  5581 10435  9989 14303  5951  8048]
    194         [    0     0     1     0     0     0     0     0     0     0 15688  6716 13819  4144   257  5743 14865 15680  4179 10478]
    195         [    0     0     0     1     0     0     0     0     0     0  4307  9488  2992  9925 13984 15754  8185 11598 14701 10784]
    196         [    0     0     0     0     1     0     0     0     0     0   927  3404 15076  1040  2827  9317 14041 10566  5117  7452]
    197         [    0     0     0     0     0     1     0     0     0     0  1144 10861  5241  6288  9282  5748  3715 13482  7258  9401]
    198         [    0     0     0     0     0     0     1     0     0     0   769  1804  1879  4624  6170  7500 11883  9047   874   597]
    199         [    0     0     0     0     0     0     0     1     0     0 15591 13686  5729 11259 10219 13222 15177 15727  5082 11211]
    200         [    0     0     0     0     0     0     0     0     1     0  8375 14939 13471 12221  8103  4212 11744 10182  2492 11068]
    201         [    0     0     0     0     0     0     0     0     0     1  6534   396  6780 14734  1206  3848  7712  9770 10755   410]
    202 
    203     ::
    204 
    205         sage: A = random_matrix(Integers(10000), 10, 20); A
    206         [2286 1825 2376 1180 1432 3070 5298 1485 2315   11  486 8911  669 2420 8838 9006 5606 1815 1700 3259]
    207         [5553 3349 3416 9701  784 2614 7654   74 7642 7631 3667 7491 5417 8046  235 1350 8458 1781 7254 3230]
    208         [3899 2557 9043 1740 4704  408 5572 2540 6823 2684 2483 6333 6137 2803 5750 7792 5897 3759 6960 1399]
    209         [3576 6431 1352 9019  632 5164 6432 9946 9449  665 3808 8426 5446 1299 6781 8902 3723 9639 4571 5725]
    210         [7153 7274 4275 5090 7116  504 2323 8981 7961 6643 4822 8069 7183 2766 9492 2429 9059 2620 9328 6563]
    211         [4730 3360 8630 3700 1781 5762 1988 3441  487 6869 7931 2534 2783 4002 4040 9831 7860  925 8792 1284]
    212         [8437 3824 3088 2626 6094 9571 7214 2194 2261 7330 7443 8896 4586 6386 2736 4395 4433 7213 7654 5854]
    213         [2256 7334 3566 7224 8490 4137 2690 2999  609 7291 7241  908 4810 5162 4079 5581 5198 2563 7058  910]
    214         [ 160 5757 3867 1620 3893 5557 2491 5934 4831 9953 5663 8183 1187 9725 3137 3159 1374 5277 8498 5701]
    215         [2640 2586 7674 3417 4878 7052 9606 7388  459 9237 9381 9652  604 5572 2728 4393 4059 8574 7845 7072]
    216 
    217         sage: A.echelon_form()
    218         Traceback (most recent call last):
    219         ...
    220         NotImplementedError: Echelon form not implemented over 'Ring of integers modulo 10000'.
    221 
    222     TESTS::
    223 
    224         sage: A = random_matrix(GF(7),  0, 10)
    225         sage: A.echelon_form()
    226         []
    227 
    228         sage: A = random_matrix(GF(7), 10,  0)
    229         sage: A.echelon_form()
    230         []
    231 
    232         sage: A = random_matrix(GF(7),  0,  0)
    233         sage: A.echelon_form()
    234         []
    235 
    236         sage: A = matrix(GF(7),  10,  10)
    237         sage: A.echelon_form()
    238         [0 0 0 0 0 0 0 0 0 0]
    239         [0 0 0 0 0 0 0 0 0 0]
    240         [0 0 0 0 0 0 0 0 0 0]
    241         [0 0 0 0 0 0 0 0 0 0]
    242         [0 0 0 0 0 0 0 0 0 0]
    243         [0 0 0 0 0 0 0 0 0 0]
    244         [0 0 0 0 0 0 0 0 0 0]
    245         [0 0 0 0 0 0 0 0 0 0]
    246         [0 0 0 0 0 0 0 0 0 0]
    247         [0 0 0 0 0 0 0 0 0 0]
    248 
    249         sage: A = random_matrix(GF(16007),  0, 10)
    250         sage: A.echelon_form()
    251         []
    252 
    253         sage: A = random_matrix(GF(16007), 10,  0)
    254         sage: A.echelon_form()
    255         []
    256 
    257         sage: A = random_matrix(GF(16007),  0,  0)
    258         sage: A.echelon_form()
    259         []
    260 
    261         sage: A = matrix(GF(16007),  10,  10)
    262         sage: A.echelon_form()
    263         [0 0 0 0 0 0 0 0 0 0]
    264         [0 0 0 0 0 0 0 0 0 0]
    265         [0 0 0 0 0 0 0 0 0 0]
    266         [0 0 0 0 0 0 0 0 0 0]
    267         [0 0 0 0 0 0 0 0 0 0]
    268         [0 0 0 0 0 0 0 0 0 0]
    269         [0 0 0 0 0 0 0 0 0 0]
    270         [0 0 0 0 0 0 0 0 0 0]
    271         [0 0 0 0 0 0 0 0 0 0]
    272         [0 0 0 0 0 0 0 0 0 0]
    273131    """
    274132    if linbox_is_zero(modulus, entries, nrows, ncols):
    275133        return 0,[]
     
    309167cdef inline int linbox_rank(celement modulus, celement* entries, Py_ssize_t nrows, Py_ssize_t ncols) except -1:
    310168    """
    311169    Return the rank of this matrix.
    312 
    313     EXAMPLES::
    314 
    315         sage: A = random_matrix(GF(3), 100, 100)
    316         sage: B = copy(A)
    317         sage: A.rank()
    318         99
    319         sage: B == A
    320         True
    321 
    322         sage: A = random_matrix(GF(3), 100, 100, density=0.01)
    323         sage: A.rank()
    324         63
    325 
    326         sage: A = matrix(GF(3), 100, 100)
    327         sage: A.rank()
    328         0
    329        
    330     ::
    331 
    332         sage: A = random_matrix(GF(16007), 100, 100)
    333         sage: B = copy(A)
    334         sage: A.rank()
    335         100
    336         sage: B == A
    337         True
    338         sage: MS = A.parent()
    339         sage: MS(1) == ~A*A
    340         True
    341 
    342     TESTS::
    343 
    344         sage: A = random_matrix(GF(7), 0, 0)
    345         sage: A.rank()
    346         0
    347 
    348         sage: A = random_matrix(GF(7), 1, 0)
    349         sage: A.rank()
    350         0
    351 
    352         sage: A = random_matrix(GF(7), 0, 1)
    353         sage: A.rank()
    354         0
    355 
    356         sage: A = random_matrix(GF(16007), 0, 0)
    357         sage: A.rank()
    358         0
    359 
    360         sage: A = random_matrix(GF(16007), 1, 0)
    361         sage: A.rank()
    362         0
    363 
    364         sage: A = random_matrix(GF(16007), 0, 1)
    365         sage: A.rank()
    366         0
    367170    """
    368171    cdef ModField *F = new ModField(<long>modulus)
    369172   
     
    379182cdef inline celement linbox_det(celement modulus, celement* entries, Py_ssize_t nrows, Py_ssize_t ncols):
    380183    """
    381184    Return the determinant of this matrix.
    382 
    383     EXAMPLES::
    384 
    385         sage: A = random_matrix(GF(7), 10, 10); A
    386         [3 1 6 6 4 4 2 2 3 5]
    387         [4 5 6 2 2 1 2 5 0 5]
    388         [3 2 0 5 0 1 5 4 2 3]
    389         [6 4 5 0 2 4 2 0 6 3]
    390         [2 2 4 2 4 5 3 4 4 4]
    391         [2 5 2 5 4 5 1 1 1 1]
    392         [0 6 3 4 2 2 3 5 1 1]
    393         [4 2 6 5 6 3 4 5 5 3]
    394         [5 2 4 3 6 2 3 6 2 1]
    395         [3 3 5 3 4 2 2 1 6 2]
    396 
    397         sage: A.determinant()
    398         6
    399        
    400     ::
    401 
    402         sage: A = random_matrix(GF(7), 100, 100)
    403         sage: A.determinant()
    404         2
    405        
    406         sage: A.transpose().determinant()
    407         2
    408        
    409         sage: B = random_matrix(GF(7), 100, 100)
    410         sage: B.determinant()
    411         4
    412 
    413         sage: (A*B).determinant() == A.determinant() * B.determinant()
    414         True
    415        
    416     ::
    417 
    418         sage: A = random_matrix(GF(16007), 10, 10); A
    419         [ 5037  2388  4150  1400   345  5945  4240 14022 10514   700]
    420         [15552  8539  1927  3870  9867  3263 11637   609 15424  2443]
    421         [ 3761 15836 12246 15577 10178 13602 13183 15918 13942  2958]
    422         [ 4526 10817  6887  6678  1764  9964  6107  1705  5619  5811]
    423         [13537 15004  8307 11846 14779   550 14113  5477  7271  7091]
    424         [13338  4927 11406 13065  5437 12431  6318  5119 14198   496]
    425         [ 1044   179 12881   353 12975 12567  1092 10433 12304   954]
    426         [10072  8821 14118 13895  6543 13484 10685 14363  2612 11070]
    427         [15113   237  2612 14127 11589  5808   117  9656 15957 14118]
    428         [15233 11080  5716  9029 11402  9380 13045 13986 14544  5771]
    429 
    430         sage: A.determinant()
    431         10207
    432        
    433     ::
    434 
    435         sage: A = random_matrix(GF(16007), 100, 100)
    436         sage: A.determinant()
    437         3576
    438        
    439        
    440         sage: A.transpose().determinant()
    441         3576
    442 
    443         sage: B = random_matrix(GF(16007), 100, 100)
    444         sage: B.determinant()
    445         4075
    446 
    447         sage: (A*B).determinant() == A.determinant() * B.determinant()
    448         True
    449 
    450     TESTS::
    451 
    452         sage: A = random_matrix(GF(7), 0, 0); A.det()
    453         1
    454 
    455         sage: A = random_matrix(GF(7), 0, 1); A.det()
    456         Traceback (most recent call last):
    457         ...
    458         ValueError: self must be a square matrix
    459 
    460         sage: A = random_matrix(GF(7), 1, 0); A.det()
    461         Traceback (most recent call last):
    462         ...
    463         ValueError: self must be a square matrix
    464 
    465         sage: A = matrix(GF(7), 5, 5); A.det()
    466         0
    467 
    468     ::
    469 
    470         sage: A = random_matrix(GF(16007), 0, 0); A.det()
    471         1
    472 
    473         sage: A = random_matrix(GF(16007), 0, 1); A.det()
    474         Traceback (most recent call last):
    475         ...
    476         ValueError: self must be a square matrix
    477        
    478         sage: A = random_matrix(GF(16007), 1, 0); A.det()
    479         Traceback (most recent call last):
    480         ...
    481         ValueError: self must be a square matrix
    482 
    483         sage: A = matrix(GF(16007), 5, 5); A.det()
    484         0
    485185    """
    486186    cdef ModField *F = new ModField(<long>modulus)
    487187    cdef celement *cpy = linbox_copy(modulus, entries, nrows, ncols)
     
    495195cdef inline int linbox_matrix_matrix_multiply(celement modulus, celement* ans, celement* A, celement* B, Py_ssize_t m, Py_ssize_t n, Py_ssize_t k):
    496196    """
    497197    C = A*B
    498 
    499     EXAMPLES::
    500 
    501         sage: A = random_matrix(GF(7),2,2); A
    502         [3 1]
    503         [6 6]
    504 
    505         sage: B = random_matrix(GF(7),2,2); B
    506         [4 4]
    507         [2 2]
    508 
    509         sage: A*B
    510         [0 0]
    511         [1 1]
    512 
    513         sage: 3*A
    514         [2 3]
    515         [4 4]
    516 
    517         sage: MS = parent(A)
    518         sage: MS(3) * A
    519         [2 3]
    520         [4 4]
    521 
    522     ::
    523    
    524         sage: A = random_matrix(GF(17), 201, 117)
    525         sage: B = random_matrix(GF(17), 117, 195)
    526         sage: C = random_matrix(GF(17), 201, 117)
    527         sage: D = random_matrix(GF(17), 117, 195)
    528 
    529         sage: E = (A+C)*(B+D)
    530 
    531         sage: F = A*B + A*D + C*B + C*D
    532 
    533         sage: E == F
    534         True
    535 
    536     ::
    537 
    538         sage: A = random_matrix(GF(17), 200, 200)
    539         sage: MS = parent(A)
    540         sage: (MS(0) * A) == 0
    541         True
    542 
    543         sage: (MS(1) * A) == A
    544         True
    545 
    546     ::
    547 
    548         sage: A = random_matrix(Integers(8),2,2); A
    549         [7 2]
    550         [6 1]
    551 
    552         sage: B = random_matrix(Integers(8),2,2); B
    553         [4 0]
    554         [5 6]
    555 
    556         sage: A*B
    557         [6 4]
    558         [5 6]
    559 
    560         sage: 3*A
    561         [5 6]
    562         [2 3]
    563 
    564         sage: MS = parent(A)
    565         sage: MS(3) * A
    566         [5 6]
    567         [2 3]
    568 
    569     ::
    570    
    571         sage: A = random_matrix(Integers(16), 201, 117)
    572         sage: B = random_matrix(Integers(16), 117, 195)
    573         sage: C = random_matrix(Integers(16), 201, 117)
    574         sage: D = random_matrix(Integers(16), 117, 195)
    575 
    576         sage: E = (A+C)*(B+D)
    577 
    578         sage: F = A*B + A*D + C*B + C*D
    579 
    580         sage: E == F
    581         True
    582 
    583     ::
    584 
    585         sage: A = random_matrix(Integers(16), 200, 200)
    586         sage: MS = parent(A)
    587         sage: (MS(0) * A) == 0
    588         True
    589 
    590         sage: (MS(1) * A) == A
    591         True
    592 
    593     ::
    594 
    595         sage: A = random_matrix(GF(16007),2,2); A
    596         [ 7856  5786]
    597         [10134 14607]
    598 
    599         sage: B = random_matrix(GF(16007),2,2); B
    600         [10839  6194]
    601         [13327  5985]
    602 
    603         sage: A*B
    604         [14254  4853]
    605         [ 8754 15217]
    606 
    607         sage: 3*A
    608         [ 7561  1351]
    609         [14395 11807]
    610 
    611         sage: MS = parent(A)
    612         sage: MS(3) * A
    613         [ 7561  1351]
    614         [14395 11807]
    615 
    616     ::
    617    
    618         sage: A = random_matrix(GF(15991), 201, 117)
    619         sage: B = random_matrix(GF(15991), 117, 195)
    620         sage: C = random_matrix(GF(15991), 201, 117)
    621         sage: D = random_matrix(GF(15991), 117, 195)
    622 
    623         sage: E = (A+C)*(B+D)
    624 
    625         sage: F = A*B + A*D + C*B + C*D
    626 
    627         sage: E == F
    628         True
    629 
    630     ::
    631 
    632         sage: A = random_matrix(GF(16007), 200, 200)
    633         sage: MS = parent(A)
    634         sage: (MS(0) * A) == 0
    635         True
    636 
    637         sage: (MS(1) * A) == A
    638         True
    639 
    640     ::
    641 
    642         sage: A = random_matrix(Integers(1008),2,2); A
    643         [354 413]
    644         [307 499]
    645 
    646         sage: B = random_matrix(Integers(1008),2,2); B
    647         [952  41]
    648         [973 851]
    649 
    650         sage: A*B
    651         [1001   73]
    652         [ 623  772]
    653 
    654         sage: 3*A
    655         [ 54 231]
    656         [921 489]
    657 
    658         sage: MS = parent(A)
    659         sage: MS(3) * A
    660         [ 54 231]
    661         [921 489]
    662 
    663     ::
    664    
    665         sage: A = random_matrix(Integers(1600), 201, 117)
    666         sage: B = random_matrix(Integers(1600), 117, 195)
    667         sage: C = random_matrix(Integers(1600), 201, 117)
    668         sage: D = random_matrix(Integers(1600), 117, 195)
    669 
    670         sage: E = (A+C)*(B+D)
    671 
    672         sage: F = A*B + A*D + C*B + C*D
    673 
    674         sage: E == F
    675         True
    676198    """
    677199    cdef ModField *F = new ModField(<long>modulus)
    678200    cdef ModFieldElement one, mone, zero
     
    703225cdef inline linbox_minpoly(celement modulus, Py_ssize_t nrows, celement* entries):
    704226    """
    705227    Compute the minimal polynomial.
    706 
    707     EXAMPLE::
    708 
    709         sage: A = random_matrix(GF(17), 10, 10); A
    710         [ 2 14  0 15 11 10 16  2  9  4]
    711         [10 14  1 14  3 14 12 14  3 13]
    712         [10  1 14  6  2 14 13  7  6 14]
    713         [10  3  9 15  8  1  5  8 10 11]
    714         [ 5 12  4  9 15  2  6 11  2 12]
    715         [ 6 10 12  0  6  9  7  7  3  8]
    716         [ 2  9  1  5 12 13  7 16  7 11]
    717         [11  1  0  2  0  4  7  9  8 15]
    718         [ 5  3 16  2 11 10 12 14  0  7]
    719         [16  4  6  5  2  3 14 15 16  4]
    720 
    721         sage: B = copy(A)
    722         sage: min_p = A.minimal_polynomial(proof=True); min_p
    723         x^10 + 13*x^9 + 10*x^8 + 9*x^7 + 10*x^6 + 4*x^5 + 10*x^4 + 10*x^3 + 12*x^2 + 14*x + 7
    724         sage: min_p(A) == 0
    725         True
    726         sage: B == A
    727         True
    728        
    729         sage: char_p = A.characteristic_polynomial(); char_p
    730         x^10 + 13*x^9 + 10*x^8 + 9*x^7 + 10*x^6 + 4*x^5 + 10*x^4 + 10*x^3 + 12*x^2 + 14*x + 7
    731         sage: min_p.divides(char_p)
    732         True
    733 
    734     ::
    735 
    736         sage: A = random_matrix(GF(1214471), 10, 10); A
    737         [ 266673  745841  418200  521668  905837  160562  831940   65852  173001  515930]
    738         [ 714380  778254  844537  584888  392730  502193  959391  614352  775603  240043]
    739         [1156372  104118 1175992  612032 1049083  660489 1066446  809624   15010 1002045]
    740         [ 470722  314480 1155149 1173111   14213 1190467 1079166  786442  429883  563611]
    741         [ 625490 1015074  888047 1090092  892387    4724  244901  696350  384684  254561]
    742         [ 898612   44844   83752 1091581  349242  130212  580087  253296  472569  913613]
    743         [ 919150   38603  710029  438461  736442  943501  792110  110470  850040  713428]
    744         [ 668799 1122064  325250 1084368  520553 1179743  791517   34060 1183757 1118938]
    745         [ 642169   47513   73428 1076788  216479  626571  105273  400489 1041378 1186801]
    746         [ 158611  888598 1138220 1089631   56266 1092400  890773 1060810  211135  719636]
    747 
    748         sage: B = copy(A)
    749         sage: min_p = A.minimal_polynomial(proof=True); min_p
    750         x^10 + 283013*x^9 + 252503*x^8 + 512435*x^7 + 742964*x^6 + 130817*x^5 + 581471*x^4 + 899760*x^3 + 207023*x^2 + 470831*x + 381978
    751 
    752         sage: min_p(A) == 0
    753         True
    754         sage: B == A
    755         True
    756        
    757         sage: char_p = A.characteristic_polynomial(); char_p
    758         x^10 + 283013*x^9 + 252503*x^8 + 512435*x^7 + 742964*x^6 + 130817*x^5 + 581471*x^4 + 899760*x^3 + 207023*x^2 + 470831*x + 381978
    759 
    760         sage: min_p.divides(char_p)
    761         True       
    762 
    763     TESTS::
    764 
    765         sage: A = random_matrix(GF(17), 0, 0)
    766         sage: A.minimal_polynomial()
    767         1
    768 
    769         sage: A = random_matrix(GF(17), 0, 1)
    770         sage: A.minimal_polynomial()
    771         Traceback (most recent call last):
    772         ...
    773         ValueError: matrix must be square
    774 
    775         sage: A = random_matrix(GF(17), 1, 0)
    776         sage: A.minimal_polynomial()
    777         Traceback (most recent call last):
    778         ...
    779         ValueError: matrix must be square
    780 
    781         sage: A = matrix(GF(17), 10, 10)
    782         sage: A.minimal_polynomial()
    783         x
    784 
    785     ::
    786 
    787         sage: A = random_matrix(GF(2535919), 0, 0)
    788         sage: A.minimal_polynomial()
    789         1
    790 
    791         sage: A = random_matrix(GF(2535919), 0, 1)
    792         sage: A.minimal_polynomial()
    793         Traceback (most recent call last):
    794         ...
    795         ValueError: matrix must be square
    796 
    797         sage: A = random_matrix(GF(2535919), 1, 0)
    798         sage: A.minimal_polynomial()
    799         Traceback (most recent call last):
    800         ...
    801         ValueError: matrix must be square
    802 
    803         sage: A = matrix(GF(2535919), 10, 10)
    804         sage: A.minimal_polynomial()
    805         x
    806228    """
    807229    cdef Py_ssize_t i
    808230    cdef ModField *F = new ModField(<long>modulus)
     
    829251
    830252cdef inline linbox_charpoly(celement modulus, Py_ssize_t nrows, celement* entries):
    831253    """
    832     Compute the minimal polynomial.
    833 
    834     EXAMPLE::
    835 
    836         sage: A = random_matrix(GF(19), 10, 10); A
    837         [ 3  1  8 10  5 16 18  9  6  1]
    838         [ 5 14  4  4 14 15  5 11  3  0]
    839         [ 4  1  0  7 11  6 17  8  5  6]
    840         [ 4  6  9  4  8  1 18 17  8 18]
    841         [11  2  0  6 13  7  4 11 16 10]
    842         [12  6 12  3 15 10  5 11  3  8]
    843         [15  1 16  2 18 15 14  7  2 11]
    844         [16 16 17  7 14 12  7  7  0  5]
    845         [13 15  9  2 12 16  1 15 18  7]
    846         [10  8 16 18  9 18  2 13  5 10]
    847 
    848         sage: B = copy(A)
    849         sage: min_p = A.minimal_polynomial(proof=True); min_p
    850         x^10 + 2*x^9 + 18*x^8 + 4*x^7 + 13*x^6 + 11*x^5 + 2*x^4 + 5*x^3 + 7*x^2 + 16*x + 6
    851        
    852         sage: min_p(A) == 0
    853         True
    854         sage: B == A
    855         True
    856        
    857         sage: char_p = A.characteristic_polynomial(); char_p
    858         x^10 + 2*x^9 + 18*x^8 + 4*x^7 + 13*x^6 + 11*x^5 + 2*x^4 + 5*x^3 + 7*x^2 + 16*x + 6
    859 
    860         sage: min_p.divides(char_p)
    861         True
    862 
    863     ::
    864 
    865         sage: A = random_matrix(GF(2916337), 7, 7); A
    866         [ 446196 2267054   36722 2092388 1694559  514193 1196222]
    867         [1242955 1040744   99523 2447069   40527  930282 2685786]
    868         [2892660 1347146 1126775 2131459  869381 1853546 2266414]
    869         [2897342 1342067 1054026  373002   84731 1270068 2421818]
    870         [ 569466  537440  572533  297105 1415002 2079710  355705]
    871         [2546914 2299052 2883413 1558788 1494309 1027319 1572148]
    872         [ 250822  522367 2516720  585897 2296292 1797050 2128203]
    873 
    874         sage: B = copy(A)
    875         sage: min_p = A.minimal_polynomial(proof=True); min_p
    876         x^7 + 1191770*x^6 + 547840*x^5 + 215639*x^4 + 2434512*x^3 + 1039968*x^2 + 483592*x + 733817
    877 
    878         sage: min_p(A) == 0
    879         True
    880         sage: B == A
    881         True
    882        
    883         sage: char_p = A.characteristic_polynomial(); char_p
    884         x^7 + 1191770*x^6 + 547840*x^5 + 215639*x^4 + 2434512*x^3 + 1039968*x^2 + 483592*x + 733817
    885 
    886         sage: min_p.divides(char_p)
    887         True       
    888 
    889     TESTS::
    890 
    891         sage: A = random_matrix(GF(19), 0, 0)
    892         sage: A.minimal_polynomial()
    893         1
    894 
    895         sage: A = random_matrix(GF(19), 0, 1)
    896         sage: A.minimal_polynomial()
    897         Traceback (most recent call last):
    898         ...
    899         ValueError: matrix must be square
    900 
    901         sage: A = random_matrix(GF(19), 1, 0)
    902         sage: A.minimal_polynomial()
    903         Traceback (most recent call last):
    904         ...
    905         ValueError: matrix must be square
    906 
    907         sage: A = matrix(GF(19), 10, 10)
    908         sage: A.minimal_polynomial()
    909         x
    910 
    911     ::
    912 
    913         sage: A = random_matrix(GF(4198973), 0, 0)
    914         sage: A.minimal_polynomial()
    915         1
    916 
    917         sage: A = random_matrix(GF(4198973), 0, 1)
    918         sage: A.minimal_polynomial()
    919         Traceback (most recent call last):
    920         ...
    921         ValueError: matrix must be square
    922 
    923         sage: A = random_matrix(GF(4198973), 1, 0)
    924         sage: A.minimal_polynomial()
    925         Traceback (most recent call last):
    926         ...
    927         ValueError: matrix must be square
    928 
    929         sage: A = matrix(GF(4198973), 10, 10)
    930         sage: A.minimal_polynomial()
    931         x
     254    Compute the characteristic  polynomial.
    932255    """
    933256    cdef Py_ssize_t i
    934257    cdef ModField *F = new ModField(<long>modulus)
     
    1126449                k = k + 1
    1127450
    1128451    def __richcmp__(Matrix_modn_dense_template self, right, int op):  # always need for mysterious reasons.
     452        """
     453        EXAMPLES::
     454
     455            sage: A = matrix(ZZ, 10, 10, range(1000, 1100))
     456            sage: A.change_ring(GF(17)) == A.change_ring(GF(17))
     457            True
     458            sage: A.change_ring(GF(17)) == A.change_ring(GF(19))
     459            False
     460            sage: A.change_ring(GF(17)) == A.change_ring(Integers(2000))
     461            False
     462            sage: A.change_ring(GF(17)) == A.change_ring(Integers(2000))
     463            False
     464        """
    1129465        return self._richcmp(right, op)
    1130466
    1131467    def __hash__(self):
     
    1139475            [  4  57 112]
    1140476            [ 59  85  45]: 0}
    1141477
    1142         ::
    1143 
    1144478            sage: M = random_matrix(GF(7), 10, 10)
    1145479            sage: M.set_immutable()
    1146480            sage: hash(M)
     
    1205539        difference is taken care of in unpickling (optimizing for
    1206540        unpickling on the same platform things were pickled on).
    1207541
    1208         The upcoming buffer protocol would be useful to not have to do
    1209         any copying.
    1210 
    1211542        EXAMPLES::
    1212543
    1213544            sage: m = matrix(Integers(128), 3, 3, [ord(c) for c in "Hi there!"]); m
     
    1216547            [114 101  33]
    1217548            sage: m._pickle()
    1218549            ((1, ..., 'Hi there!'), 10)
     550
     551        .. todo::
     552
     553            The upcoming buffer protocol would be useful to not have
     554            to do any copying.
    1219555        """
    1220556        cdef Py_ssize_t i, j
    1221557        cdef unsigned char* us
     
    1251587
    1252588        return (word_size, little_endian, s), 10
    1253589
    1254 
    1255590    def _unpickle(self, data, int version):
    1256591        """
    1257592        TESTS:
     
    1282617            [  1   2]
    1283618            [255   0]
    1284619
    1285         ::
    1286 
    1287620            sage: A = matrix(Integers(1000), 1, 2)
    1288621            sage: A._unpickle((4, True, '\x02\x01\x00\x00\x01\x00\x00\x00'), 10)
    1289622            sage: A
     
    1362695        """
    1363696        EXAMPLES::
    1364697
    1365             sage: m = matrix(GF(19), 3, 3, range(9)); m
     698            sage: A = matrix(GF(19), 3, 3, range(9)); A
    1366699            [0 1 2]
    1367700            [3 4 5]
    1368701            [6 7 8]
    1369             sage: -m
     702
     703            sage: -A
    1370704            [ 0 18 17]
    1371705            [16 15 14]
    1372706            [13 12 11]
     
    1391725        """
    1392726        EXAMPLES::
    1393727       
    1394             sage: a = random_matrix(Integers(60), 400, 500)
    1395             sage: 3*a + 9*a == 12*a
     728            sage: A = random_matrix(Integers(60), 400, 500)
     729            sage: 3*A + 9*A == 12*A
    1396730            True
    1397731        """
    1398732        return self._rmul_(right)
     
    1401735        """
    1402736        EXAMPLES::
    1403737       
    1404             sage: a = matrix(GF(101), 3, 3, range(9)); a
     738            sage: A = matrix(GF(101), 3, 3, range(9)); A
    1405739            [0 1 2]
    1406740            [3 4 5]
    1407741            [6 7 8]
    1408             sage: a * 5
     742            sage: A * 5
    1409743            [ 0  5 10]
    1410744            [15 20 25]
    1411745            [30 35 40]
    1412             sage: a * 50
     746            sage: A * 50
    1413747            [  0  50 100]
    1414748            [ 49  99  48]
    1415749            [ 98  47  97]
     
    1428762        return M
    1429763
    1430764    def __copy__(self):
     765        """
     766        EXAMPLE::
     767
     768            sage: A = random_matrix(GF(127), 100, 100)
     769            sage: copy(A) == A
     770            True
     771            sage: copy(A) is A
     772            False
     773        """
    1431774        cdef Matrix_modn_dense_template A
    1432775        A = self.__class__.__new__(self.__class__, self._parent, 0, 0, 0)
    1433776        memcpy(A._entries, self._entries, sizeof(celement)*self._nrows*self._ncols)
     
    1438781
    1439782    cpdef ModuleElement _add_(self, ModuleElement right):
    1440783        """
    1441         Add two dense matrices over Z/nZ
     784        Add two dense matrices over `\Z/n\Z`
     785
     786        INPUT:
     787
     788        - ``right`` - a matrix
    1442789       
    1443790        EXAMPLES::
    1444791       
    1445             sage: a = MatrixSpace(GF(19),3)(range(9))
    1446             sage: a+a
     792            sage: A = MatrixSpace(GF(19),3)(range(9))
     793            sage: A+A
    1447794            [ 0  2  4]
    1448795            [ 6  8 10]
    1449796            [12 14 16]
    1450             sage: b = MatrixSpace(GF(19),3)(range(9))
    1451             sage: b.swap_rows(1,2)
    1452             sage: a+b
     797
     798            sage: B = MatrixSpace(GF(19),3)(range(9))
     799            sage: B.swap_rows(1,2)
     800            sage: A+B
    1453801            [ 0  2  4]
    1454802            [ 9 11 13]
    1455803            [ 9 11 13]
    1456             sage: b+a
     804
     805            sage: B+A
    1457806            [ 0  2  4]
    1458807            [ 9 11 13]
    1459808            [ 9 11 13]
     
    1475824
    1476825
    1477826    cpdef ModuleElement _sub_(self, ModuleElement right):
    1478         """
    1479         Subtract two dense matrices over Z/nZ
     827        r"""
     828        Subtract two dense matrices over `\Z/n\Z`
    1480829       
    1481830        EXAMPLES::
    1482831       
    1483             sage: a = matrix(GF(11), 3, 3, range(9)); a
     832            sage: A = matrix(GF(11), 3, 3, range(9)); A
    1484833            [0 1 2]
    1485834            [3 4 5]
    1486835            [6 7 8]
    1487             sage: a - 4
     836
     837            sage: A - 4
    1488838            [7 1 2]
    1489839            [3 0 5]
    1490840            [6 7 4]
    1491             sage: a - matrix(GF(11), 3, 3, range(1, 19, 2))
     841
     842            sage: A - matrix(GF(11), 3, 3, range(1, 19, 2))
    1492843            [10  9  8]
    1493844            [ 7  6  5]
    1494845            [ 4  3  2]
     
    1510861
    1511862
    1512863    cdef int _cmp_c_impl(self, Element right) except -2:
    1513         """
    1514         Compare two dense matrices over Z/nZ
     864        r"""
     865        Compare two dense matrices over `\Z/n\Z`
    1515866       
    1516867        EXAMPLES::
    1517868       
    1518             sage: a = matrix(GF(17), 4, range(3, 83, 5)); a
     869            sage: A = matrix(GF(17), 4, range(3, 83, 5)); A
    1519870            [ 3  8 13  1]
    1520871            [ 6 11 16  4]
    1521872            [ 9 14  2  7]
    1522873            [12  0  5 10]
    1523             sage: a == a
     874            sage: A == A
    1524875            True
    1525             sage: b = a - 3; b
     876            sage: B = A - 3; B
    1526877            [ 0  8 13  1]
    1527878            [ 6  8 16  4]
    1528879            [ 9 14 16  7]
    1529880            [12  0  5  7]
    1530             sage: b < a
     881            sage: B < A
    1531882            True
    1532             sage: b > a
     883            sage: B > A
    1533884            False
    1534             sage: b == a
     885            sage: B == A
    1535886            False
    1536             sage: b + 3 == a
     887            sage: B + 3 == A
    1537888            True
    1538889        """
    1539890        cdef Py_ssize_t i
     
    1552903
    1553904    cdef Matrix _matrix_times_matrix_(self, Matrix right):
    1554905        """
    1555         Multiply matrices using LinBox.
     906        return ``self*right``
    1556907
    1557908        INPUT:
    1558909
    1559         - ``right``- Matrix
    1560 
     910        - ``right``-  a matrix
     911
     912        EXAMPLES::
     913
     914            sage: A = random_matrix(GF(7),2,2); A
     915            [3 1]
     916            [6 6]
     917
     918            sage: B = random_matrix(GF(7),2,2); B
     919            [4 4]
     920            [2 2]
     921
     922            sage: A*B
     923            [0 0]
     924            [1 1]
     925
     926            sage: 3*A
     927            [2 3]
     928            [4 4]
     929
     930            sage: MS = parent(A)
     931            sage: MS(3) * A
     932            [2 3]
     933            [4 4]
     934
     935        ::
     936
     937            sage: A = random_matrix(GF(17), 201, 117)
     938            sage: B = random_matrix(GF(17), 117, 195)
     939            sage: C = random_matrix(GF(17), 201, 117)
     940            sage: D = random_matrix(GF(17), 117, 195)
     941
     942            sage: E = (A+C)*(B+D)
     943
     944            sage: F = A*B + A*D + C*B + C*D
     945
     946            sage: E == F
     947            True
     948
     949            sage: A = random_matrix(GF(17), 200, 200)
     950            sage: MS = parent(A)
     951            sage: (MS(0) * A) == 0
     952            True
     953
     954            sage: (MS(1) * A) == A
     955            True
     956
     957        ::
     958
     959            sage: A = random_matrix(Integers(8),2,2); A
     960            [7 2]
     961            [6 1]
     962
     963            sage: B = random_matrix(Integers(8),2,2); B
     964            [4 0]
     965            [5 6]
     966
     967            sage: A*B
     968            [6 4]
     969            [5 6]
     970
     971            sage: 3*A
     972            [5 6]
     973            [2 3]
     974
     975            sage: MS = parent(A)
     976            sage: MS(3) * A
     977            [5 6]
     978            [2 3]
     979
     980        ::
     981
     982            sage: A = random_matrix(Integers(16), 201, 117)
     983            sage: B = random_matrix(Integers(16), 117, 195)
     984            sage: C = random_matrix(Integers(16), 201, 117)
     985            sage: D = random_matrix(Integers(16), 117, 195)
     986
     987            sage: E = (A+C)*(B+D)
     988
     989            sage: F = A*B + A*D + C*B + C*D
     990
     991            sage: E == F
     992            True
     993
     994            sage: A = random_matrix(Integers(16), 200, 200)
     995            sage: MS = parent(A)
     996            sage: (MS(0) * A) == 0
     997            True
     998
     999            sage: (MS(1) * A) == A
     1000            True
     1001
     1002        ::
     1003
     1004            sage: A = random_matrix(GF(16007),2,2); A
     1005            [ 7856  5786]
     1006            [10134 14607]
     1007
     1008            sage: B = random_matrix(GF(16007),2,2); B
     1009            [10839  6194]
     1010            [13327  5985]
     1011
     1012            sage: A*B
     1013            [14254  4853]
     1014            [ 8754 15217]
     1015
     1016            sage: 3*A
     1017            [ 7561  1351]
     1018            [14395 11807]
     1019
     1020            sage: MS = parent(A)
     1021            sage: MS(3) * A
     1022            [ 7561  1351]
     1023            [14395 11807]
     1024
     1025        ::
     1026
     1027            sage: A = random_matrix(GF(15991), 201, 117)
     1028            sage: B = random_matrix(GF(15991), 117, 195)
     1029            sage: C = random_matrix(GF(15991), 201, 117)
     1030            sage: D = random_matrix(GF(15991), 117, 195)
     1031
     1032            sage: E = (A+C)*(B+D)
     1033
     1034            sage: F = A*B + A*D + C*B + C*D
     1035
     1036            sage: E == F
     1037            True
     1038
     1039        ::
     1040
     1041            sage: A = random_matrix(GF(16007), 200, 200)
     1042            sage: MS = parent(A)
     1043            sage: (MS(0) * A) == 0
     1044            True
     1045
     1046            sage: (MS(1) * A) == A
     1047            True
     1048
     1049        ::
     1050
     1051            sage: A = random_matrix(Integers(1008),2,2); A
     1052            [354 413]
     1053            [307 499]
     1054
     1055            sage: B = random_matrix(Integers(1008),2,2); B
     1056            [952  41]
     1057            [973 851]
     1058
     1059            sage: A*B
     1060            [1001   73]
     1061            [ 623  772]
     1062
     1063            sage: 3*A
     1064            [ 54 231]
     1065            [921 489]
     1066
     1067            sage: MS = parent(A)
     1068            sage: MS(3) * A
     1069            [ 54 231]
     1070            [921 489]
     1071
     1072        ::
     1073
     1074            sage: A = random_matrix(Integers(1600), 201, 117)
     1075            sage: B = random_matrix(Integers(1600), 117, 195)
     1076            sage: C = random_matrix(Integers(1600), 201, 117)
     1077            sage: D = random_matrix(Integers(1600), 117, 195)
     1078
     1079            sage: E = (A+C)*(B+D)
     1080
     1081            sage: F = A*B + A*D + C*B + C*D
     1082
     1083            sage: E == F
     1084            True
    15611085        """
    15621086        if get_verbose() >= 2:
    15631087            verbose('mod-p multiply of %s x %s matrix by %s x %s matrix modulo %s'%(
     
    15771101
    15781102    cdef Vector _vector_times_matrix_(self, Vector v):
    15791103        """
     1104        ``v*self``
     1105
     1106        INPUT:
     1107
     1108        - ``v`` - a vector
     1109
    15801110        EXAMPLES::
    15811111
    15821112            sage: A = random_matrix(GF(17), 10, 20)
     
    16221152        return c
    16231153
    16241154    cdef Vector _matrix_times_vector_(self, Vector v):
     1155        """
     1156        ``self*v``
     1157
     1158        EXAMPLES::
     1159
     1160            sage: A = random_matrix(GF(17), 10, 20)
     1161            sage: v = random_vector(GF(17), 20)
     1162            sage: matrix(A*v).transpose() == A*matrix(v).transpose()
     1163            True
     1164
     1165            sage: A = random_matrix(Integers(126), 10, 20)
     1166            sage: v = random_vector(Integers(126), 20)
     1167            sage: matrix(A*v).transpose() == A*matrix(v).transpose()
     1168            True
     1169
     1170            sage: A = random_matrix(GF(4796509), 10, 20)
     1171            sage: v = random_vector(GF(4796509), 20)
     1172            sage: matrix(A*v).transpose() == A*matrix(v).transpose()
     1173            True
     1174
     1175            sage: A = random_matrix(Integers(16337), 10, 20)
     1176            sage: v = random_vector(Integers(16337), 20)
     1177            sage: matrix(A*v).transpose() == A*matrix(v).transpose()
     1178            True
     1179        """
    16251180        if not isinstance(v, Vector_modn_dense):
    1626             return matrix_dense.Matrix_dense._matrix_times_vector(self, v)
     1181            r = (self * self.new_matrix(nrows=len(v), ncols=1, entries=v.list()))
     1182            from sage.modules.free_module_element import vector
     1183            return vector(r.list())
    16271184
    16281185        cdef Py_ssize_t i
    16291186        cdef Vector_modn_dense b = v
     
    16441201        sage_free(_c)
    16451202        return c
    16461203   
    1647 
    16481204    ########################################################################
    16491205    # LEVEL 3 functionality (Optional)
    16501206    #  x * cdef _sub_
     
    16571213    #        - Hessenberg forms of matrices
    16581214    ########################################################################
    16591215
    1660 
    16611216    def charpoly(self, var='x', algorithm='linbox'):
    16621217        """
    1663         Returns the characteristic polynomial of self.
     1218        Return the characteristic polynomial of ``self``.
    16641219       
    16651220        INPUT:
    16661221       
     1222        - ``var`` - a variable name
    16671223       
    1668         -  ``var`` - a variable name
    1669        
    1670         -  ``algorithm`` - 'generic', 'linbox' or 'all' (default)
    1671        
    1672        
    1673         EXAMPLES::
     1224        - ``algorithm`` - 'generic', 'linbox' or 'all' (default: linbox)
     1225
     1226        EXAMPLE::
     1227
     1228            sage: A = random_matrix(GF(19), 10, 10); A
     1229            [ 3  1  8 10  5 16 18  9  6  1]
     1230            [ 5 14  4  4 14 15  5 11  3  0]
     1231            [ 4  1  0  7 11  6 17  8  5  6]
     1232            [ 4  6  9  4  8  1 18 17  8 18]
     1233            [11  2  0  6 13  7  4 11 16 10]
     1234            [12  6 12  3 15 10  5 11  3  8]
     1235            [15  1 16  2 18 15 14  7  2 11]
     1236            [16 16 17  7 14 12  7  7  0  5]
     1237            [13 15  9  2 12 16  1 15 18  7]
     1238            [10  8 16 18  9 18  2 13  5 10]
     1239
     1240            sage: B = copy(A)
     1241            sage: char_p = A.characteristic_polynomial(); char_p
     1242            x^10 + 2*x^9 + 18*x^8 + 4*x^7 + 13*x^6 + 11*x^5 + 2*x^4 + 5*x^3 + 7*x^2 + 16*x + 6
     1243            sage: char_p(A) == 0
     1244            True
     1245            sage: B == A              # A is not modified
     1246            True
     1247
     1248            sage: min_p = A.minimal_polynomial(proof=True); min_p
     1249            x^10 + 2*x^9 + 18*x^8 + 4*x^7 + 13*x^6 + 11*x^5 + 2*x^4 + 5*x^3 + 7*x^2 + 16*x + 6
     1250            sage: min_p.divides(char_p)
     1251            True
     1252
     1253        ::
     1254
     1255            sage: A = random_matrix(GF(2916337), 7, 7); A
     1256            [ 446196 2267054   36722 2092388 1694559  514193 1196222]
     1257            [1242955 1040744   99523 2447069   40527  930282 2685786]
     1258            [2892660 1347146 1126775 2131459  869381 1853546 2266414]
     1259            [2897342 1342067 1054026  373002   84731 1270068 2421818]
     1260            [ 569466  537440  572533  297105 1415002 2079710  355705]
     1261            [2546914 2299052 2883413 1558788 1494309 1027319 1572148]
     1262            [ 250822  522367 2516720  585897 2296292 1797050 2128203]
     1263
     1264            sage: B = copy(A)
     1265            sage: char_p = A.characteristic_polynomial(); char_p
     1266            x^7 + 1191770*x^6 + 547840*x^5 + 215639*x^4 + 2434512*x^3 + 1039968*x^2 + 483592*x + 733817
     1267            sage: char_p(A) == 0
     1268            True
     1269            sage: B == A               # A is not modified
     1270            True
     1271
     1272            sage: min_p = A.minimal_polynomial(proof=True); min_p
     1273            x^7 + 1191770*x^6 + 547840*x^5 + 215639*x^4 + 2434512*x^3 + 1039968*x^2 + 483592*x + 733817
     1274            sage: min_p.divides(char_p)
     1275            True       
     1276
     1277            sage: A = Mat(Integers(6),3,3)(range(9))
     1278            sage: A.charpoly()
     1279            x^3
     1280
     1281        TESTS::
     1282
     1283            sage: for i in range(10):
     1284            ...       A = random_matrix(GF(17), 50, 50, density=0.1)
     1285            ...       _ = A.characteristic_polynomial(algorithm='all')
     1286
     1287            sage: A = random_matrix(GF(19), 0, 0)
     1288            sage: A.minimal_polynomial()
     1289            1
     1290
     1291            sage: A = random_matrix(GF(19), 0, 1)
     1292            sage: A.minimal_polynomial()
     1293            Traceback (most recent call last):
     1294            ...
     1295            ValueError: matrix must be square
     1296
     1297            sage: A = random_matrix(GF(19), 1, 0)
     1298            sage: A.minimal_polynomial()
     1299            Traceback (most recent call last):
     1300            ...
     1301            ValueError: matrix must be square
     1302
     1303            sage: A = matrix(GF(19), 10, 10)
     1304            sage: A.minimal_polynomial()
     1305            x
     1306
     1307            sage: A = random_matrix(GF(4198973), 0, 0)
     1308            sage: A.minimal_polynomial()
     1309            1
     1310
     1311            sage: A = random_matrix(GF(4198973), 0, 1)
     1312            sage: A.minimal_polynomial()
     1313            Traceback (most recent call last):
     1314            ...
     1315            ValueError: matrix must be square
     1316
     1317            sage: A = random_matrix(GF(4198973), 1, 0)
     1318            sage: A.minimal_polynomial()
     1319            Traceback (most recent call last):
     1320            ...
     1321            ValueError: matrix must be square
     1322
     1323            sage: A = matrix(GF(4198973), 10, 10)
     1324            sage: A.minimal_polynomial()
     1325            x
    16741326       
    16751327            sage: A = Mat(GF(7),3,3)(range(3)*3)
    16761328            sage: A.charpoly()
    16771329            x^3 + 4*x^2
    16781330       
    1679         ::
    1680        
    1681             sage: A = Mat(Integers(6),3,3)(range(9))
    1682             sage: A.charpoly()
    1683             x^3
    1684        
    1685         ALGORITHM: Uses LinBox if self.base_ring() is a field, otherwise
    1686         use Hessenberg form algorithm.
     1331        ALGORITHM: Uses LinBox if ``self.base_ring()`` is a field,
     1332        otherwise use Hessenberg form algorithm.
    16871333        """
    16881334        if algorithm == 'linbox' and (self.p == 2 or not self.base_ring().is_field()):
    16891335            algorithm = 'generic' # LinBox only supports Z/pZ (p prime)
     
    17101356
    17111357        - ``var`` - a variable name
    17121358           
    1713         - ``algorithm`` - ``generic`` or ``linbox`` (default: ``linbox``)
     1359        - ``algorithm`` - ``generic`` or ``linbox`` (default:
     1360          ``linbox``)
    17141361
    17151362        - ``proof`` -- (default: ``True``); whether to provably return
    17161363          the true minimal polynomial; if ``False``, we only guarantee
     
    17261373             default, unless you first type
    17271374             ``proof.linear_algebra(False)``.
    17281375
     1376        EXAMPLE::
     1377
     1378            sage: A = random_matrix(GF(17), 10, 10); A
     1379            [ 2 14  0 15 11 10 16  2  9  4]
     1380            [10 14  1 14  3 14 12 14  3 13]
     1381            [10  1 14  6  2 14 13  7  6 14]
     1382            [10  3  9 15  8  1  5  8 10 11]
     1383            [ 5 12  4  9 15  2  6 11  2 12]
     1384            [ 6 10 12  0  6  9  7  7  3  8]
     1385            [ 2  9  1  5 12 13  7 16  7 11]
     1386            [11  1  0  2  0  4  7  9  8 15]
     1387            [ 5  3 16  2 11 10 12 14  0  7]
     1388            [16  4  6  5  2  3 14 15 16  4]
     1389
     1390            sage: B = copy(A)
     1391            sage: min_p = A.minimal_polynomial(proof=True); min_p
     1392            x^10 + 13*x^9 + 10*x^8 + 9*x^7 + 10*x^6 + 4*x^5 + 10*x^4 + 10*x^3 + 12*x^2 + 14*x + 7
     1393            sage: min_p(A) == 0
     1394            True
     1395            sage: B == A
     1396            True
     1397
     1398            sage: char_p = A.characteristic_polynomial(); char_p
     1399            x^10 + 13*x^9 + 10*x^8 + 9*x^7 + 10*x^6 + 4*x^5 + 10*x^4 + 10*x^3 + 12*x^2 + 14*x + 7
     1400            sage: min_p.divides(char_p)
     1401            True
     1402
     1403        ::
     1404
     1405            sage: A = random_matrix(GF(1214471), 10, 10); A
     1406            [ 266673  745841  418200  521668  905837  160562  831940   65852  173001  515930]
     1407            [ 714380  778254  844537  584888  392730  502193  959391  614352  775603  240043]
     1408            [1156372  104118 1175992  612032 1049083  660489 1066446  809624   15010 1002045]
     1409            [ 470722  314480 1155149 1173111   14213 1190467 1079166  786442  429883  563611]
     1410            [ 625490 1015074  888047 1090092  892387    4724  244901  696350  384684  254561]
     1411            [ 898612   44844   83752 1091581  349242  130212  580087  253296  472569  913613]
     1412            [ 919150   38603  710029  438461  736442  943501  792110  110470  850040  713428]
     1413            [ 668799 1122064  325250 1084368  520553 1179743  791517   34060 1183757 1118938]
     1414            [ 642169   47513   73428 1076788  216479  626571  105273  400489 1041378 1186801]
     1415            [ 158611  888598 1138220 1089631   56266 1092400  890773 1060810  211135  719636]
     1416
     1417            sage: B = copy(A)
     1418            sage: min_p = A.minimal_polynomial(proof=True); min_p
     1419            x^10 + 283013*x^9 + 252503*x^8 + 512435*x^7 + 742964*x^6 + 130817*x^5 + 581471*x^4 + 899760*x^3 + 207023*x^2 + 470831*x + 381978
     1420
     1421            sage: min_p(A) == 0
     1422            True
     1423            sage: B == A
     1424            True
     1425
     1426            sage: char_p = A.characteristic_polynomial(); char_p
     1427            x^10 + 283013*x^9 + 252503*x^8 + 512435*x^7 + 742964*x^6 + 130817*x^5 + 581471*x^4 + 899760*x^3 + 207023*x^2 + 470831*x + 381978
     1428
     1429            sage: min_p.divides(char_p)
     1430            True       
     1431
     1432        TESTS::
     1433
     1434            sage: A = random_matrix(GF(17), 0, 0)
     1435            sage: A.minimal_polynomial()
     1436            1
     1437
     1438            sage: A = random_matrix(GF(17), 0, 1)
     1439            sage: A.minimal_polynomial()
     1440            Traceback (most recent call last):
     1441            ...
     1442            ValueError: matrix must be square
     1443
     1444            sage: A = random_matrix(GF(17), 1, 0)
     1445            sage: A.minimal_polynomial()
     1446            Traceback (most recent call last):
     1447            ...
     1448            ValueError: matrix must be square
     1449
     1450            sage: A = matrix(GF(17), 10, 10)
     1451            sage: A.minimal_polynomial()
     1452            x
     1453
     1454        ::
     1455
     1456            sage: A = random_matrix(GF(2535919), 0, 0)
     1457            sage: A.minimal_polynomial()
     1458            1
     1459
     1460            sage: A = random_matrix(GF(2535919), 0, 1)
     1461            sage: A.minimal_polynomial()
     1462            Traceback (most recent call last):
     1463            ...
     1464            ValueError: matrix must be square
     1465
     1466            sage: A = random_matrix(GF(2535919), 1, 0)
     1467            sage: A.minimal_polynomial()
     1468            Traceback (most recent call last):
     1469            ...
     1470            ValueError: matrix must be square
     1471
     1472            sage: A = matrix(GF(2535919), 10, 10)
     1473            sage: A.minimal_polynomial()
     1474            x
     1475
    17291476        EXAMPLES::
    17301477
    17311478            sage: R.<x>=GF(3)[]
     
    17681515    def _charpoly_linbox(self, var='x'):
    17691516        """
    17701517        Computes the characteristic polynomial using LinBox. No checks
    1771         are performed.
     1518        are performed.
     1519
     1520        This function is called internally by ``charpoly``.
     1521       
     1522        INPUT:
     1523       
     1524        - ``var`` - a variable name
     1525       
     1526        EXAMPLE::
     1527
     1528            sage: A = random_matrix(GF(19), 10, 10); A
     1529            [ 3  1  8 10  5 16 18  9  6  1]
     1530            [ 5 14  4  4 14 15  5 11  3  0]
     1531            [ 4  1  0  7 11  6 17  8  5  6]
     1532            [ 4  6  9  4  8  1 18 17  8 18]
     1533            [11  2  0  6 13  7  4 11 16 10]
     1534            [12  6 12  3 15 10  5 11  3  8]
     1535            [15  1 16  2 18 15 14  7  2 11]
     1536            [16 16 17  7 14 12  7  7  0  5]
     1537            [13 15  9  2 12 16  1 15 18  7]
     1538            [10  8 16 18  9 18  2 13  5 10]
     1539
     1540            sage: B = copy(A)
     1541            sage: char_p = A._charpoly_linbox(); char_p
     1542            x^10 + 2*x^9 + 18*x^8 + 4*x^7 + 13*x^6 + 11*x^5 + 2*x^4 + 5*x^3 + 7*x^2 + 16*x + 6
     1543            sage: char_p(A) == 0
     1544            True
     1545            sage: B == A              # A is not modified
     1546            True
     1547
     1548            sage: min_p = A.minimal_polynomial(proof=True); min_p
     1549            x^10 + 2*x^9 + 18*x^8 + 4*x^7 + 13*x^6 + 11*x^5 + 2*x^4 + 5*x^3 + 7*x^2 + 16*x + 6
     1550            sage: min_p.divides(char_p)
     1551            True
    17721552        """
    17731553        verbose('_charpoly_linbox...')
    17741554       
     
    17861566
    17871567    def echelonize(self, algorithm="linbox", **kwds):
    17881568        """
    1789         Puts self in row echelon form.
     1569        Put ``self`` in reduced row echelon form.
    17901570
    17911571        INPUT:
    17921572               
    17931573        - ``self`` - a mutable matrix
    1794         - ``algorithm`` - 'linbox' - uses the C++ linbox library
    1795         - ``'gauss'`` - uses a custom slower `O(n^3)` Gauss
    1796            elimination implemented in Sage.
    1797         - ``'all'`` - compute using both algorithms and verify that
    1798            the results are the same (for the paranoid).
     1574
     1575        - ``algorithm``
     1576
     1577          - ``linbox`` - uses the LinBox library
     1578
     1579          - ``gauss`` - uses a custom slower `O(n^3)` Gauss
     1580            elimination implemented in Sage.
     1581
     1582          - ``all`` - compute using both algorithms and verify that
     1583           the results are the same.
     1584
    17991585        - ``**kwds`` - these are all ignored
    18001586               
    18011587        OUTPUT:
    18021588               
    18031589        - ``self`` is put in reduced row echelon form.
     1590
    18041591        - the rank of self is computed and cached
     1592
    18051593        - the pivot columns of self are computed and cached.
     1594
    18061595        - the fact that self is now in echelon form is recorded and
    18071596          cached so future calls to echelonize return immediately.
    18081597               
    18091598        EXAMPLES::
     1599
     1600            sage: A = random_matrix(GF(7), 10, 20); A
     1601            [3 1 6 6 4 4 2 2 3 5 4 5 6 2 2 1 2 5 0 5]
     1602            [3 2 0 5 0 1 5 4 2 3 6 4 5 0 2 4 2 0 6 3]
     1603            [2 2 4 2 4 5 3 4 4 4 2 5 2 5 4 5 1 1 1 1]
     1604            [0 6 3 4 2 2 3 5 1 1 4 2 6 5 6 3 4 5 5 3]
     1605            [5 2 4 3 6 2 3 6 2 1 3 3 5 3 4 2 2 1 6 2]
     1606            [0 5 6 3 2 5 6 6 3 2 1 4 5 0 2 6 5 2 5 1]
     1607            [4 0 4 2 6 3 3 5 3 0 0 1 2 5 5 1 6 0 0 3]
     1608            [2 0 1 0 0 3 0 2 4 2 2 4 4 4 5 4 1 2 3 4]
     1609            [2 4 1 4 3 0 6 2 2 5 2 5 3 6 4 2 2 6 4 4]
     1610            [0 0 2 2 1 6 2 0 5 0 4 3 1 6 0 6 0 4 6 5]
     1611
     1612            sage: A.echelon_form()
     1613            [1 0 0 0 0 0 0 0 0 0 6 2 6 0 1 1 2 5 6 2]
     1614            [0 1 0 0 0 0 0 0 0 0 0 4 5 4 3 4 2 5 1 2]
     1615            [0 0 1 0 0 0 0 0 0 0 6 3 4 6 1 0 3 6 5 6]
     1616            [0 0 0 1 0 0 0 0 0 0 0 3 5 2 3 4 0 6 5 3]
     1617            [0 0 0 0 1 0 0 0 0 0 0 6 3 4 5 3 0 4 3 2]
     1618            [0 0 0 0 0 1 0 0 0 0 1 1 0 2 4 2 5 5 5 0]
     1619            [0 0 0 0 0 0 1 0 0 0 1 0 1 3 2 0 0 0 5 3]
     1620            [0 0 0 0 0 0 0 1 0 0 4 4 2 6 5 4 3 4 1 0]
     1621            [0 0 0 0 0 0 0 0 1 0 1 0 4 2 3 5 4 6 4 0]
     1622            [0 0 0 0 0 0 0 0 0 1 2 0 5 0 5 5 3 1 1 4]
     1623
     1624        ::
     1625
     1626            sage: A = random_matrix(GF(13), 10, 10); A
     1627            [ 8  3 11 11  9  4  8  7  9  9]
     1628            [ 2  9  6  5  7 12  3  4 11  5]
     1629            [12  6 11 12  4  3  3  8  9  5]
     1630            [ 4  2 10  5 10  1  1  1  6  9]
     1631            [12  8  5  5 11  4  1  2  8 11]
     1632            [ 2  6  9 11  4  7  1  0 12  2]
     1633            [ 8  9  0  7  7  7 10  4  1  4]
     1634            [ 0  8  2  6  7  5  7 12  2  3]
     1635            [ 2 11 12  3  4  7  2  9  6  1]
     1636            [ 0 11  5  9  4  5  5  8  7 10]
     1637
     1638            sage: MS = parent(A)
     1639            sage: B = A.augment(MS(1))
     1640            sage: B.echelonize()
     1641            sage: A.rank()
     1642            10
     1643            sage: C = B.submatrix(0,10,10,10); C
     1644            [ 4  9  4  4  0  4  7 11  9 11]
     1645            [11  7  6  8  2  8  6 11  9  5]
     1646            [ 3  9  9  2  4  8  9  2  9  4]
     1647            [ 7  0 11  4  0  9  6 11  8  1]
     1648            [12 12  4 12  3 12  6  1  7 12]
     1649            [12  2 11  6  6  6  7  0 10  6]
     1650            [ 0  7  3  4  7 11 10 12  4  6]
     1651            [ 5 11  0  5  3 11  4 12  5 12]
     1652            [ 6  7  3  5  1  4 11  7  4  1]
     1653            [ 4  9  6  7 11  1  2 12  6  7]
     1654
     1655            sage: ~A == C
     1656            True
     1657
     1658        ::
     1659
     1660            sage: A = random_matrix(Integers(10), 10, 20)
     1661            sage: A.echelon_form()
     1662            Traceback (most recent call last):
     1663            ...
     1664            NotImplementedError: Echelon form not implemented over 'Ring of integers modulo 10'.
     1665
     1666        ::
     1667            sage: A = random_matrix(GF(16007), 10, 20); A
     1668            [15455  1177 10072  4693  3887  4102 10746 15265  6684 14559  4535 13921  9757  9525  9301  8566  2460  9609  3887  6205]
     1669            [ 8602 10035  1242  9776   162  7893 12619  6660 13250  1988 14263 11377  2216  1247  7261  8446 15081 14412  7371  7948]
     1670            [12634  7602   905  9617 13557  2694 13039  4936 12208 15480  3787 11229   593 12462  5123 14167  6460  3649  5821  6736]
     1671            [10554  2511 11685 12325 12287  6534 11636  5004  6468  3180  3607 11627 13436  5106  3138 13376  8641  9093  2297  5893]
     1672            [ 1025 11376 10288   609 12330  3021   908 13012  2112 11505    56  5971   338  2317  2396  8561  5593  3782  7986 13173]
     1673            [ 7607   588  6099 12749 10378   111  2852 10375  8996  7969   774 13498 12720  4378  6817  6707  5299  9406 13318  2863]
     1674            [15545   538  4840  1885  8471  1303 11086 14168  1853 14263  3995 12104  1294  7184  1188 11901 15971  2899  4632   711]
     1675            [  584 11745  7540 15826 15027  5953  7097 14329 10889 12532 13309 15041  6211  1749 10481  9999  2751 11068    21  2795]
     1676            [  761 11453  3435 10596  2173  7752 15941 14610  1072  8012  9458  5440   612 10581 10400   101 11472 13068  7758  7898]
     1677            [10658  4035  6662   655  7546  4107  6987  1877  4072  4221  7679 14579  2474  8693  8127 12999 11141   605  9404 10003]
     1678            sage: A.echelon_form()
     1679            [    1     0     0     0     0     0     0     0     0     0  8416  8364 10318  1782 13872  4566 14855  7678 11899  2652]
     1680            [    0     1     0     0     0     0     0     0     0     0  4782 15571  3133 10964  5581 10435  9989 14303  5951  8048]
     1681            [    0     0     1     0     0     0     0     0     0     0 15688  6716 13819  4144   257  5743 14865 15680  4179 10478]
     1682            [    0     0     0     1     0     0     0     0     0     0  4307  9488  2992  9925 13984 15754  8185 11598 14701 10784]
     1683            [    0     0     0     0     1     0     0     0     0     0   927  3404 15076  1040  2827  9317 14041 10566  5117  7452]
     1684            [    0     0     0     0     0     1     0     0     0     0  1144 10861  5241  6288  9282  5748  3715 13482  7258  9401]
     1685            [    0     0     0     0     0     0     1     0     0     0   769  1804  1879  4624  6170  7500 11883  9047   874   597]
     1686            [    0     0     0     0     0     0     0     1     0     0 15591 13686  5729 11259 10219 13222 15177 15727  5082 11211]
     1687            [    0     0     0     0     0     0     0     0     1     0  8375 14939 13471 12221  8103  4212 11744 10182  2492 11068]
     1688            [    0     0     0     0     0     0     0     0     0     1  6534   396  6780 14734  1206  3848  7712  9770 10755   410]
     1689
     1690        ::
     1691
     1692            sage: A = random_matrix(Integers(10000), 10, 20)
     1693            sage: A.echelon_form()
     1694            Traceback (most recent call last):
     1695            ...
     1696            NotImplementedError: Echelon form not implemented over 'Ring of integers modulo 10000'.
     1697
     1698        TESTS::
     1699
     1700            sage: A = random_matrix(GF(7),  0, 10)
     1701            sage: A.echelon_form()
     1702            []
     1703            sage: A = random_matrix(GF(7), 10,  0)
     1704            sage: A.echelon_form()
     1705            []
     1706            sage: A = random_matrix(GF(7),  0,  0)
     1707            sage: A.echelon_form()
     1708            []
     1709            sage: A = matrix(GF(7),  10,  10)
     1710            sage: A.echelon_form()
     1711            [0 0 0 0 0 0 0 0 0 0]
     1712            [0 0 0 0 0 0 0 0 0 0]
     1713            [0 0 0 0 0 0 0 0 0 0]
     1714            [0 0 0 0 0 0 0 0 0 0]
     1715            [0 0 0 0 0 0 0 0 0 0]
     1716            [0 0 0 0 0 0 0 0 0 0]
     1717            [0 0 0 0 0 0 0 0 0 0]
     1718            [0 0 0 0 0 0 0 0 0 0]
     1719            [0 0 0 0 0 0 0 0 0 0]
     1720            [0 0 0 0 0 0 0 0 0 0]
     1721            sage: A = random_matrix(GF(16007),  0, 10)
     1722            sage: A.echelon_form()
     1723            []
     1724            sage: A = random_matrix(GF(16007), 10,  0)
     1725            sage: A.echelon_form()
     1726            []
     1727            sage: A = random_matrix(GF(16007),  0,  0)
     1728            sage: A.echelon_form()
     1729            []
     1730            sage: A = matrix(GF(16007),  10,  10)
     1731            sage: A.echelon_form()
     1732            [0 0 0 0 0 0 0 0 0 0]
     1733            [0 0 0 0 0 0 0 0 0 0]
     1734            [0 0 0 0 0 0 0 0 0 0]
     1735            [0 0 0 0 0 0 0 0 0 0]
     1736            [0 0 0 0 0 0 0 0 0 0]
     1737            [0 0 0 0 0 0 0 0 0 0]
     1738            [0 0 0 0 0 0 0 0 0 0]
     1739            [0 0 0 0 0 0 0 0 0 0]
     1740            [0 0 0 0 0 0 0 0 0 0]
     1741            [0 0 0 0 0 0 0 0 0 0]
    18101742       
    18111743            sage: A = matrix(GF(97),3,4,range(12))
    18121744            sage: A.echelonize(); A
     
    18451777
    18461778    def _echelonize_linbox(self):
    18471779        """
    1848         Puts self in row echelon form using LinBox.
     1780        Puts ``self`` in row echelon form using LinBox.
     1781
     1782        This function is called by echelonize if
     1783        ``algorithm='linbox'``.
     1784
     1785        EXAMPLES::
     1786
     1787            sage: A = random_matrix(GF(7), 10, 20); A
     1788            [3 1 6 6 4 4 2 2 3 5 4 5 6 2 2 1 2 5 0 5]
     1789            [3 2 0 5 0 1 5 4 2 3 6 4 5 0 2 4 2 0 6 3]
     1790            [2 2 4 2 4 5 3 4 4 4 2 5 2 5 4 5 1 1 1 1]
     1791            [0 6 3 4 2 2 3 5 1 1 4 2 6 5 6 3 4 5 5 3]
     1792            [5 2 4 3 6 2 3 6 2 1 3 3 5 3 4 2 2 1 6 2]
     1793            [0 5 6 3 2 5 6 6 3 2 1 4 5 0 2 6 5 2 5 1]
     1794            [4 0 4 2 6 3 3 5 3 0 0 1 2 5 5 1 6 0 0 3]
     1795            [2 0 1 0 0 3 0 2 4 2 2 4 4 4 5 4 1 2 3 4]
     1796            [2 4 1 4 3 0 6 2 2 5 2 5 3 6 4 2 2 6 4 4]
     1797            [0 0 2 2 1 6 2 0 5 0 4 3 1 6 0 6 0 4 6 5]
     1798
     1799            sage: A._echelonize_linbox(); A
     1800            [1 0 0 0 0 0 0 0 0 0 6 2 6 0 1 1 2 5 6 2]
     1801            [0 1 0 0 0 0 0 0 0 0 0 4 5 4 3 4 2 5 1 2]
     1802            [0 0 1 0 0 0 0 0 0 0 6 3 4 6 1 0 3 6 5 6]
     1803            [0 0 0 1 0 0 0 0 0 0 0 3 5 2 3 4 0 6 5 3]
     1804            [0 0 0 0 1 0 0 0 0 0 0 6 3 4 5 3 0 4 3 2]
     1805            [0 0 0 0 0 1 0 0 0 0 1 1 0 2 4 2 5 5 5 0]
     1806            [0 0 0 0 0 0 1 0 0 0 1 0 1 3 2 0 0 0 5 3]
     1807            [0 0 0 0 0 0 0 1 0 0 4 4 2 6 5 4 3 4 1 0]
     1808            [0 0 0 0 0 0 0 0 1 0 1 0 4 2 3 5 4 6 4 0]
     1809            [0 0 0 0 0 0 0 0 0 1 2 0 5 0 5 5 3 1 1 4]
    18491810        """
    18501811        self.check_mutability()
    18511812        self.clear_cache()
     
    18591820        self.cache('pivots', tuple(pivots))
    18601821
    18611822    def _echelon_in_place_classical(self):
     1823        """
     1824        Puts ``self`` in row echelon form using LinBox.
     1825
     1826        This function is called by echelonize if
     1827        ``algorithm='gauss'``.
     1828
     1829        EXAMPLES::
     1830
     1831            sage: A = random_matrix(GF(7), 10, 20); A
     1832            [3 1 6 6 4 4 2 2 3 5 4 5 6 2 2 1 2 5 0 5]
     1833            [3 2 0 5 0 1 5 4 2 3 6 4 5 0 2 4 2 0 6 3]
     1834            [2 2 4 2 4 5 3 4 4 4 2 5 2 5 4 5 1 1 1 1]
     1835            [0 6 3 4 2 2 3 5 1 1 4 2 6 5 6 3 4 5 5 3]
     1836            [5 2 4 3 6 2 3 6 2 1 3 3 5 3 4 2 2 1 6 2]
     1837            [0 5 6 3 2 5 6 6 3 2 1 4 5 0 2 6 5 2 5 1]
     1838            [4 0 4 2 6 3 3 5 3 0 0 1 2 5 5 1 6 0 0 3]
     1839            [2 0 1 0 0 3 0 2 4 2 2 4 4 4 5 4 1 2 3 4]
     1840            [2 4 1 4 3 0 6 2 2 5 2 5 3 6 4 2 2 6 4 4]
     1841            [0 0 2 2 1 6 2 0 5 0 4 3 1 6 0 6 0 4 6 5]
     1842
     1843            sage: A._echelon_in_place_classical(); A
     1844            [1 0 0 0 0 0 0 0 0 0 6 2 6 0 1 1 2 5 6 2]
     1845            [0 1 0 0 0 0 0 0 0 0 0 4 5 4 3 4 2 5 1 2]
     1846            [0 0 1 0 0 0 0 0 0 0 6 3 4 6 1 0 3 6 5 6]
     1847            [0 0 0 1 0 0 0 0 0 0 0 3 5 2 3 4 0 6 5 3]
     1848            [0 0 0 0 1 0 0 0 0 0 0 6 3 4 5 3 0 4 3 2]
     1849            [0 0 0 0 0 1 0 0 0 0 1 1 0 2 4 2 5 5 5 0]
     1850            [0 0 0 0 0 0 1 0 0 0 1 0 1 3 2 0 0 0 5 3]
     1851            [0 0 0 0 0 0 0 1 0 0 4 4 2 6 5 4 3 4 1 0]
     1852            [0 0 0 0 0 0 0 0 1 0 1 0 4 2 3 5 4 6 4 0]
     1853            [0 0 0 0 0 0 0 0 0 1 2 0 5 0 5 5 3 1 1 4]
     1854        """
    18621855        self.check_mutability()
    18631856        self.clear_cache()
    18641857
     
    18981891        self.cache('pivots', tuple(pivots))
    18991892        self.cache('in_echelon_form',True)
    19001893
    1901     cdef xgcd_eliminate(self, celement * row1, celement* row2, Py_ssize_t start_col):
    1902         """
    1903         Reduces row1 and row2 by a unimodular transformation using the xgcd
    1904         relation between their first coefficients a and b.
    1905 
    1906         INPUT:
    1907        
    1908         - ``row1, row2`` - the two rows to be transformed (within
    1909           self)
    1910        
    1911         -``start_col`` - the column of the pivots in ``row1`` and
    1912          ``row2``. It is assumed that all entries before ``start_col``
    1913          in ``row1`` and ``row2`` are zero.
    1914        
    1915        
    1916         OUTPUT:
    1917                
    1918         - g: the gcd of the first elements of row1 and
    1919           row2 at column start_col
    1920 
    1921         - put row1 = s \* row1 + t \* row2 row2 = w \*
    1922           row1 + t \* row2 where g = sa + tb
    1923         """
    1924         cdef int p = <int>self.p
    1925         cdef celement * row1_p, * row2_p
    1926         cdef celement tmp
    1927         cdef int g, s, t, v, w
    1928         cdef Py_ssize_t nc, i
    1929         cdef int a = <int>row1[start_col]
    1930         cdef int b = <int>row2[start_col]
    1931         g = ArithIntObj.c_xgcd_int (a,b,<int*>&s,<int*>&t)
    1932         v = a/g
    1933         w = -<int>b/g
    1934         nc = self.ncols()
    1935 
    1936         for i from start_col <= i < nc:
    1937             tmp = ( s * <int>row1[i] + t * <int>row2[i]) % p
    1938             row2[i] = (w* <int>row1[i] + v*<int>row2[i]) % p
    1939             row1[i] = tmp
    1940         return g
    1941 
    1942     cdef rescale_row_c(self, Py_ssize_t row, multiple, Py_ssize_t start_col):
    1943         cdef celement r, p
    1944         cdef celement* v
    1945         cdef Py_ssize_t i
    1946         p = self.p
    1947         v = self._matrix[row]
    1948         for i from start_col <= i < self._ncols:
    1949             v[i] = (v[i]*<celement>multiple) % p
    1950 
    1951     cdef rescale_col_c(self, Py_ssize_t col, multiple, Py_ssize_t start_row):
    1952         """
    1953         EXAMPLES::
    1954 
    1955             sage: n=3; b = MatrixSpace(Integers(37),n,n,sparse=False)([1]*n*n)
    1956             sage: b
    1957             [1 1 1]
    1958             [1 1 1]
    1959             [1 1 1]
    1960             sage: b.rescale_col(1,5)
    1961             sage: b
    1962             [1 5 1]
    1963             [1 5 1]
    1964             [1 5 1]
    1965 
    1966         Recaling need not include the entire row.::
    1967 
    1968             sage: b.rescale_col(0,2,1); b
    1969             [1 5 1]
    1970             [2 5 1]
    1971             [2 5 1]           
    1972        
    1973         Bounds are checked.::
    1974        
    1975             sage: b.rescale_col(3,2)
    1976             Traceback (most recent call last):
    1977             ...
    1978             IndexError: matrix column index out of range
    1979        
    1980         Rescaling by a negative number::
    1981 
    1982             sage: b.rescale_col(2,-3); b
    1983             [ 1  5 34]
    1984             [ 2  5 34]
    1985             [ 2  5 34]
    1986         """
    1987         cdef celement r, p
    1988         cdef celement* v
    1989         cdef Py_ssize_t i
    1990         p = self.p
    1991         for i from start_row <= i < self._nrows:
    1992             self._matrix[i][col] = (self._matrix[i][col]*<celement>multiple) % p
    1993 
    1994     cdef add_multiple_of_row_c(self, Py_ssize_t row_to, Py_ssize_t row_from, multiple, Py_ssize_t start_col):
    1995         cdef celement p
    1996         cdef celement *v_from, *v_to
    1997 
    1998         p = self.p
    1999         v_from = self._matrix[row_from]
    2000         v_to = self._matrix[row_to]
    2001 
    2002         cdef Py_ssize_t i, nc
    2003         nc = self._ncols
    2004         for i from start_col <= i < nc:
    2005             v_to[i] = ((<celement>multiple) * v_from[i] +  v_to[i]) % p
    2006 
    2007     cdef add_multiple_of_column_c(self, Py_ssize_t col_to, Py_ssize_t col_from, multiple, Py_ssize_t start_row):
    2008         cdef celement  p
    2009         cdef celement **m
    2010 
    2011         m = self._matrix
    2012         p = self.p
    2013 
    2014         cdef Py_ssize_t i, nr
    2015         nr = self._nrows
    2016         for i from start_row <= i < self._nrows:
    2017             m[i][col_to] = (m[i][col_to] + (<celement>multiple) * m[i][col_from]) %p
    2018 
    2019     cdef swap_rows_c(self, Py_ssize_t row1, Py_ssize_t row2):
    2020         """
    2021         EXAMPLES::
    2022        
    2023             sage: A = matrix(Integers(8), 2,[1,2,3,4])
    2024             sage: A.swap_rows(0,1)
    2025             sage: A
    2026             [3 4]
    2027             [1 2]
    2028         """
    2029         cdef celement* r1 = self._matrix[row1]
    2030         cdef celement* r2 = self._matrix[row2]
    2031         cdef celement temp
    2032         for i in range(self._ncols):
    2033             temp = r1[i]
    2034             r1[i] = r2[i]
    2035             r2[i] = temp
    2036 
    2037     cdef swap_columns_c(self, Py_ssize_t col1, Py_ssize_t col2):
    2038         cdef Py_ssize_t i, nr
    2039         cdef celement t
    2040         cdef celement **m
    2041         m = self._matrix
    2042         nr = self._nrows
    2043         for i from 0 <= i < nr:
    2044             t = m[i][col1]
    2045             m[i][col1] = m[i][col2]
    2046             m[i][col2] = t
    2047            
    20481894    def hessenbergize(self):
    20491895        """
    20501896        Transforms self in place to its Hessenberg form.
     1897
     1898        EXAMPLE::
     1899
     1900            sage: A = random_matrix(GF(17), 10, 10, density=0.1); A
     1901            [ 0  0  0  0 12  0  0  0  0  0]
     1902            [ 0  0  0  4  0  0  0  0  0  0]
     1903            [ 0  0  0  0  2  0  0  0  0  0]
     1904            [ 0 14  0  0  0  0  0  0  0  0]
     1905            [ 0  0  0  0  0 10  0  0  0  0]
     1906            [ 0  0  0  0  0 16  0  0  0  0]
     1907            [ 0  0  0  0  0  0  6  0  0  0]
     1908            [15  0  0  0  0  0  0  0  0  0]
     1909            [ 0  0  0 16  0  0  0  0  0  0]
     1910            [ 0  5  0  0  0  0  0  0  0  0]
     1911            sage: A.hessenbergize(); A
     1912            [ 0  0  0  0  0  0  0 12  0  0]
     1913            [15  0  0  0  0  0  0  0  0  0]
     1914            [ 0  0  0  0  0  0  0  2  0  0]
     1915            [ 0  0  0  0 14  0  0  0  0  0]
     1916            [ 0  0  0  4  0  0  0  0  0  0]
     1917            [ 0  0  0  0  5  0  0  0  0  0]
     1918            [ 0  0  0  0  0  0  6  0  0  0]
     1919            [ 0  0  0  0  0  0  0  0  0 10]
     1920            [ 0  0  0  0  0  0  0  0  0  0]
     1921            [ 0  0  0  0  0  0  0  0  0 16]
    20511922        """
    20521923        self.check_mutability()
    20531924        x = self.fetch('in_hessenberg_form')
     
    21071978
    21081979    def _charpoly_hessenberg(self, var):
    21091980        """
    2110         Transforms self in place to its Hessenberg form then computes and
    2111         returns the coefficients of the characteristic polynomial of this
    2112         matrix.
     1981        Transforms self in place to its Hessenberg form then computes
     1982        and returns the coefficients of the characteristic polynomial
     1983        of this matrix.
    21131984       
    21141985        INPUT:
    2115        
    2116        
    2117         -  ``var`` - name of the indeterminate of the
    2118            charpoly.
    2119        
    2120        
    2121         The characteristic polynomial is represented as a vector of ints,
    2122         where the constant term of the characteristic polynomial is the 0th
    2123         coefficient of the vector.
     1986               
     1987        - ``var`` - name of the indeterminate of the charpoly.
     1988               
     1989        OUTPUT:
     1990
     1991           The characteristic polynomial is represented as a vector of
     1992           ints, where the constant term of the characteristic
     1993           polynomial is the 0th coefficient of the vector.
     1994
     1995        EXAMPLE::
     1996
     1997            sage: A = random_matrix(GF(17), 10, 10, density=0.1); A
     1998            [ 0  0  0  0 12  0  0  0  0  0]
     1999            [ 0  0  0  4  0  0  0  0  0  0]
     2000            [ 0  0  0  0  2  0  0  0  0  0]
     2001            [ 0 14  0  0  0  0  0  0  0  0]
     2002            [ 0  0  0  0  0 10  0  0  0  0]
     2003            [ 0  0  0  0  0 16  0  0  0  0]
     2004            [ 0  0  0  0  0  0  6  0  0  0]
     2005            [15  0  0  0  0  0  0  0  0  0]
     2006            [ 0  0  0 16  0  0  0  0  0  0]
     2007            [ 0  5  0  0  0  0  0  0  0  0]
     2008            sage: A.characteristic_polynomial()
     2009            x^10 + 12*x^9 + 6*x^8 + 8*x^7 + 13*x^6
     2010            sage: P.<x> = GF(17)[]
     2011            sage: A._charpoly_hessenberg(x)
     2012            x^10 + 12*x^9 + 6*x^8 + 8*x^7 + 13*x^6
    21242013        """
    21252014        if self._nrows != self._ncols:
    21262015            raise ArithmeticError, "charpoly not defined for non-square matrix."
     
    21372026        H = self.__copy__()
    21382027        H.hessenbergize()
    21392028
    2140 
    21412029        # We represent the intermediate polynomials that come up in
    21422030        # the calculations as rows of an (n+1)x(n+1) matrix, since
    21432031        # we've implemented basic arithmetic with such a matrix.
     
    21782066        Return the rank of this matrix.
    21792067       
    21802068        EXAMPLES::
     2069
     2070            sage: A = random_matrix(GF(3), 100, 100)
     2071            sage: B = copy(A)
     2072            sage: A.rank()
     2073            99
     2074            sage: B == A
     2075            True
     2076
     2077            sage: A = random_matrix(GF(3), 100, 100, density=0.01)
     2078            sage: A.rank()
     2079            63
     2080
     2081            sage: A = matrix(GF(3), 100, 100)
     2082            sage: A.rank()
     2083            0
     2084
     2085        Rank is not implemented over the integers modulo a composite
     2086        yet.::
    21812087       
    2182             sage: m = matrix(GF(7),5,range(25))
    2183             sage: m.rank()
    2184             2
    2185        
    2186         Rank is not implemented over the integers modulo a composite yet.::
    2187        
    2188             sage: m = matrix(Integers(4), 2, [2,2,2,2])
    2189             sage: m.rank()
     2088            sage: M = matrix(Integers(4), 2, [2,2,2,2])
     2089            sage: M.rank()
    21902090            Traceback (most recent call last):
    21912091            ...
    21922092            NotImplementedError: Echelon form not implemented over 'Ring of integers modulo 4'.
     2093
     2094        ::
     2095
     2096            sage: A = random_matrix(GF(16007), 100, 100)
     2097            sage: B = copy(A)
     2098            sage: A.rank()
     2099            100
     2100            sage: B == A
     2101            True
     2102            sage: MS = A.parent()
     2103            sage: MS(1) == ~A*A
     2104            True
     2105
     2106        TESTS::
     2107
     2108            sage: A = random_matrix(GF(7), 0, 0)
     2109            sage: A.rank()
     2110            0
     2111            sage: A = random_matrix(GF(7), 1, 0)
     2112            sage: A.rank()
     2113            0
     2114            sage: A = random_matrix(GF(7), 0, 1)
     2115            sage: A.rank()
     2116            0
     2117            sage: A = random_matrix(GF(16007), 0, 0)
     2118            sage: A.rank()
     2119            0
     2120            sage: A = random_matrix(GF(16007), 1, 0)
     2121            sage: A.rank()
     2122            0
     2123            sage: A = random_matrix(GF(16007), 0, 1)
     2124            sage: A.rank()
     2125            0
    21932126        """
    21942127        cdef Matrix_modn_dense_template A
    21952128        if self.p > 2 and is_prime(self.p):
     
    22002133            self.cache('rank', r)
    22012134            return r
    22022135        else:
    2203             # linbox is very buggy for p=2
     2136            # linbox is very buggy for p=2, but this code should never
     2137            # be called since p=2 is handled via M4RI
    22042138            return matrix_dense.Matrix_dense.rank(self)
    22052139 
    22062140    def determinant(self):
     
    22082142        Return the determinant of this matrix.
    22092143       
    22102144        EXAMPLES::
    2211        
    2212             sage: m = matrix(GF(101),5,range(25))     
    2213             sage: m.det()                             
    2214             0
    2215        
     2145
     2146            sage: A = random_matrix(GF(7), 10, 10); A
     2147            [3 1 6 6 4 4 2 2 3 5]
     2148            [4 5 6 2 2 1 2 5 0 5]
     2149            [3 2 0 5 0 1 5 4 2 3]
     2150            [6 4 5 0 2 4 2 0 6 3]
     2151            [2 2 4 2 4 5 3 4 4 4]
     2152            [2 5 2 5 4 5 1 1 1 1]
     2153            [0 6 3 4 2 2 3 5 1 1]
     2154            [4 2 6 5 6 3 4 5 5 3]
     2155            [5 2 4 3 6 2 3 6 2 1]
     2156            [3 3 5 3 4 2 2 1 6 2]
     2157
     2158            sage: A.determinant()
     2159            6
     2160
     2161       ::
     2162           
     2163            sage: A = random_matrix(GF(7), 100, 100)
     2164            sage: A.determinant()
     2165            2
     2166
     2167            sage: A.transpose().determinant()
     2168            2
     2169
     2170            sage: B = random_matrix(GF(7), 100, 100)
     2171            sage: B.determinant()
     2172            4
     2173
     2174            sage: (A*B).determinant() == A.determinant() * B.determinant()
     2175            True
     2176
    22162177        ::
    2217        
    2218             sage: m = matrix(Integers(4), 2, [2,2,2,2])           
    2219             sage: m.det()                             
    2220             0
    2221        
     2178
     2179            sage: A = random_matrix(GF(16007), 10, 10); A
     2180            [ 5037  2388  4150  1400   345  5945  4240 14022 10514   700]
     2181            [15552  8539  1927  3870  9867  3263 11637   609 15424  2443]
     2182            [ 3761 15836 12246 15577 10178 13602 13183 15918 13942  2958]
     2183            [ 4526 10817  6887  6678  1764  9964  6107  1705  5619  5811]
     2184            [13537 15004  8307 11846 14779   550 14113  5477  7271  7091]
     2185            [13338  4927 11406 13065  5437 12431  6318  5119 14198   496]
     2186            [ 1044   179 12881   353 12975 12567  1092 10433 12304   954]
     2187            [10072  8821 14118 13895  6543 13484 10685 14363  2612 11070]
     2188            [15113   237  2612 14127 11589  5808   117  9656 15957 14118]
     2189            [15233 11080  5716  9029 11402  9380 13045 13986 14544  5771]
     2190
     2191            sage: A.determinant()
     2192            10207
     2193
     2194        ::
     2195
     2196            sage: A = random_matrix(GF(16007), 100, 100)
     2197            sage: A.determinant()
     2198            3576
     2199
     2200
     2201            sage: A.transpose().determinant()
     2202            3576
     2203
     2204            sage: B = random_matrix(GF(16007), 100, 100)
     2205            sage: B.determinant()
     2206            4075
     2207
     2208            sage: (A*B).determinant() == A.determinant() * B.determinant()
     2209            True
     2210
    22222211        TESTS::
    22232212
    2224             sage: m = random_matrix(GF(3), 3, 4)
    2225             sage: m.determinant()
     2213            sage: A = random_matrix(GF(7), 0, 0); A.det()
     2214            1
     2215
     2216            sage: A = random_matrix(GF(7), 0, 1); A.det()
    22262217            Traceback (most recent call last):
    22272218            ...
    22282219            ValueError: self must be a square matrix
     2220
     2221            sage: A = random_matrix(GF(7), 1, 0); A.det()
     2222            Traceback (most recent call last):
     2223            ...
     2224            ValueError: self must be a square matrix
     2225
     2226            sage: A = matrix(GF(7), 5, 5); A.det()
     2227            0
     2228
     2229            sage: A = random_matrix(GF(16007), 0, 0); A.det()
     2230            1
     2231
     2232            sage: A = random_matrix(GF(16007), 0, 1); A.det()
     2233            Traceback (most recent call last):
     2234            ...
     2235            ValueError: self must be a square matrix
     2236
     2237            sage: A = random_matrix(GF(16007), 1, 0); A.det()
     2238            Traceback (most recent call last):
     2239            ...
     2240            ValueError: self must be a square matrix
     2241
     2242            sage: A = matrix(GF(16007), 5, 5); A.det()
     2243            0
    22292244        """
    22302245        if self._nrows != self._ncols:
    22312246            raise ValueError, "self must be a square matrix"
     
    22432258        else:
    22442259            return matrix_dense.Matrix_dense.determinant(self)
    22452260
     2261    cdef xgcd_eliminate(self, celement * row1, celement* row2, Py_ssize_t start_col):
     2262        """
     2263        Reduces ``row1`` and ``row2`` by a unimodular transformation
     2264        using the xgcd relation between their first coefficients ``a`` and
     2265        ``b``.
     2266
     2267        INPUT:
     2268       
     2269        - ``row1, row2`` - the two rows to be transformed (within
     2270          self)
     2271       
     2272        -``start_col`` - the column of the pivots in ``row1`` and
     2273         ``row2``. It is assumed that all entries before ``start_col``
     2274         in ``row1`` and ``row2`` are zero.
     2275       
     2276       
     2277        OUTPUT:
     2278               
     2279        - g: the gcd of the first elements of row1 and
     2280          row2 at column start_col
     2281
     2282        - put row1 = s \* row1 + t \* row2 row2 = w \*
     2283          row1 + t \* row2 where g = sa + tb
     2284        """
     2285        cdef int p = <int>self.p
     2286        cdef celement * row1_p, * row2_p
     2287        cdef celement tmp
     2288        cdef int g, s, t, v, w
     2289        cdef Py_ssize_t nc, i
     2290        cdef int a = <int>row1[start_col]
     2291        cdef int b = <int>row2[start_col]
     2292        g = ArithIntObj.c_xgcd_int (a,b,<int*>&s,<int*>&t)
     2293        v = a/g
     2294        w = -<int>b/g
     2295        nc = self.ncols()
     2296
     2297        for i from start_col <= i < nc:
     2298            tmp = ( s * <int>row1[i] + t * <int>row2[i]) % p
     2299            row2[i] = (w* <int>row1[i] + v*<int>row2[i]) % p
     2300            row1[i] = tmp
     2301        return g
     2302
     2303    cdef rescale_row_c(self, Py_ssize_t row, multiple, Py_ssize_t start_col):
     2304        """
     2305        Rescale ``self[row]`` by ``multiple`` but only start at column
     2306        index ``start_col``.
     2307
     2308        INPUT:
     2309       
     2310        - ``row`` - integer
     2311        - ``multiple`` - finite field element
     2312        - ``start_col`` - integer
     2313
     2314        EXAMPLE::
     2315
     2316            sage: A = matrix(GF(19), 4, 4, range(16)); A
     2317            [ 0  1  2  3]
     2318            [ 4  5  6  7]
     2319            [ 8  9 10 11]
     2320            [12 13 14 15]
     2321
     2322            sage: A.rescale_row(1, 17, 2); A
     2323            [ 0  1  2  3]
     2324            [ 4  5  7  5]
     2325            [ 8  9 10 11]
     2326            [12 13 14 15]
     2327
     2328            sage: 6*17 % 19 == A[1,2]
     2329            True
     2330
     2331            sage: A = matrix(Integers(2^4), 4, 4, range(16)); A
     2332            [ 0  1  2  3]
     2333            [ 4  5  6  7]
     2334            [ 8  9 10 11]
     2335            [12 13 14 15]
     2336
     2337            sage: A.rescale_row(1, 3, 2); A
     2338            [ 0  1  2  3]
     2339            [ 4  5  2  5]
     2340            [ 8  9 10 11]
     2341            [12 13 14 15]
     2342
     2343            sage: 6*3 % 16 == A[1,2]
     2344            True           
     2345        """
     2346        cdef celement r, p
     2347        cdef celement* v
     2348        cdef Py_ssize_t i
     2349        p = self.p
     2350        v = self._matrix[row]
     2351        for i from start_col <= i < self._ncols:
     2352            v[i] = (v[i]*<celement>multiple) % p
     2353
     2354    cdef rescale_col_c(self, Py_ssize_t col, multiple, Py_ssize_t start_row):
     2355        """
     2356        EXAMPLES::
     2357
     2358            sage: B = MatrixSpace(Integers(37),3,3)([1]*9)
     2359            sage: B
     2360            [1 1 1]
     2361            [1 1 1]
     2362            [1 1 1]
     2363            sage: B.rescale_col(1,5)
     2364            sage: B
     2365            [1 5 1]
     2366            [1 5 1]
     2367            [1 5 1]
     2368
     2369        Recaling need not include the entire row.::
     2370
     2371            sage: B.rescale_col(0,2,1); B
     2372            [1 5 1]
     2373            [2 5 1]
     2374            [2 5 1]           
     2375       
     2376        Bounds are checked.::
     2377       
     2378            sage: B.rescale_col(3,2)
     2379            Traceback (most recent call last):
     2380            ...
     2381            IndexError: matrix column index out of range
     2382       
     2383        Rescaling by a negative number::
     2384
     2385            sage: B.rescale_col(2,-3); B
     2386            [ 1  5 34]
     2387            [ 2  5 34]
     2388            [ 2  5 34]
     2389        """
     2390        cdef celement r, p
     2391        cdef celement* v
     2392        cdef Py_ssize_t i
     2393        p = self.p
     2394        for i from start_row <= i < self._nrows:
     2395            self._matrix[i][col] = (self._matrix[i][col]*<celement>multiple) % p
     2396
     2397    cdef add_multiple_of_row_c(self, Py_ssize_t row_to, Py_ssize_t row_from, multiple, Py_ssize_t start_col):
     2398        """
     2399        Add ``multiple`` times ``self[row_from]`` to ``self[row_to]``
     2400        statting in column ``start_col``.
     2401
     2402        EXAMPLE::
     2403
     2404            sage: A = random_matrix(GF(37), 10, 10); A
     2405            [24 15  7 27 32 34 16 32 25 23]
     2406            [11  3 22 13 35 33  1 10 33 25]
     2407            [33  9 25  3 15 27 30 30  7 12]
     2408            [10  0 35  4 12 34 32 16 19 17]
     2409            [36  4 21 17  3 34 11 10 10 17]
     2410            [32 15 23  2 23 32  5  8 18 11]
     2411            [24  5 28 13 21 22 29 18 33 30]
     2412            [26 18 10 26 17 31 35 18 25 30]
     2413            [21  1  4 14 11 17 29 16 18 12]
     2414            [34 19 14 11 35 30 35 34 25 33]
     2415
     2416            sage: A[2] + 10*A[3]
     2417            (22, 9, 5, 6, 24, 34, 17, 5, 12, 34)
     2418
     2419            sage: A.add_multiple_of_row(2, 3, 10)
     2420            sage: A
     2421            [24 15  7 27 32 34 16 32 25 23]
     2422            [11  3 22 13 35 33  1 10 33 25]
     2423            [22  9  5  6 24 34 17  5 12 34]
     2424            [10  0 35  4 12 34 32 16 19 17]
     2425            [36  4 21 17  3 34 11 10 10 17]
     2426            [32 15 23  2 23 32  5  8 18 11]
     2427            [24  5 28 13 21 22 29 18 33 30]
     2428            [26 18 10 26 17 31 35 18 25 30]
     2429            [21  1  4 14 11 17 29 16 18 12]
     2430            [34 19 14 11 35 30 35 34 25 33]
     2431
     2432            sage: A.add_multiple_of_row(2, 3, 10, 4)
     2433            sage: A       
     2434            [24 15  7 27 32 34 16 32 25 23]
     2435            [11  3 22 13 35 33  1 10 33 25]
     2436            [22  9  5  6 33  4  4 17 17 19]
     2437            [10  0 35  4 12 34 32 16 19 17]
     2438            [36  4 21 17  3 34 11 10 10 17]
     2439            [32 15 23  2 23 32  5  8 18 11]
     2440            [24  5 28 13 21 22 29 18 33 30]
     2441            [26 18 10 26 17 31 35 18 25 30]
     2442            [21  1  4 14 11 17 29 16 18 12]
     2443            [34 19 14 11 35 30 35 34 25 33]           
     2444        """
     2445        cdef celement p
     2446        cdef celement *v_from, *v_to
     2447
     2448        p = self.p
     2449        v_from = self._matrix[row_from]
     2450        v_to = self._matrix[row_to]
     2451
     2452        cdef Py_ssize_t i, nc
     2453        nc = self._ncols
     2454        for i from start_col <= i < nc:
     2455            v_to[i] = ((<celement>multiple) * v_from[i] +  v_to[i]) % p
     2456
     2457    cdef add_multiple_of_column_c(self, Py_ssize_t col_to, Py_ssize_t col_from, multiple, Py_ssize_t start_row):
     2458        """
     2459        Add ``multiple`` times ``self[row_from]`` to ``self[row_to]``
     2460        statting in column ``start_col``.
     2461
     2462        EXAMPLE::
     2463
     2464            sage: A = random_matrix(GF(37), 10, 10); A
     2465            [24 15  7 27 32 34 16 32 25 23]
     2466            [11  3 22 13 35 33  1 10 33 25]
     2467            [33  9 25  3 15 27 30 30  7 12]
     2468            [10  0 35  4 12 34 32 16 19 17]
     2469            [36  4 21 17  3 34 11 10 10 17]
     2470            [32 15 23  2 23 32  5  8 18 11]
     2471            [24  5 28 13 21 22 29 18 33 30]
     2472            [26 18 10 26 17 31 35 18 25 30]
     2473            [21  1  4 14 11 17 29 16 18 12]
     2474            [34 19 14 11 35 30 35 34 25 33]
     2475
     2476            sage: A.column(2) + 10*A.column(3)
     2477            (18, 4, 18, 1, 6, 6, 10, 11, 33, 13)
     2478
     2479            sage: A.add_multiple_of_column(2, 3, 10)
     2480            sage: A
     2481            [24 15 18 27 32 34 16 32 25 23]
     2482            [11  3  4 13 35 33  1 10 33 25]
     2483            [33  9 18  3 15 27 30 30  7 12]
     2484            [10  0  1  4 12 34 32 16 19 17]
     2485            [36  4  6 17  3 34 11 10 10 17]
     2486            [32 15  6  2 23 32  5  8 18 11]
     2487            [24  5 10 13 21 22 29 18 33 30]
     2488            [26 18 11 26 17 31 35 18 25 30]
     2489            [21  1 33 14 11 17 29 16 18 12]
     2490            [34 19 13 11 35 30 35 34 25 33]
     2491           
     2492            sage: A.add_multiple_of_column(2, 3, 10, 4)
     2493            sage: A       
     2494            [24 15 18 27 32 34 16 32 25 23]
     2495            [11  3  4 13 35 33  1 10 33 25]
     2496            [33  9 18  3 15 27 30 30  7 12]
     2497            [10  0  1  4 12 34 32 16 19 17]
     2498            [36  4 28 17  3 34 11 10 10 17]
     2499            [32 15 26  2 23 32  5  8 18 11]
     2500            [24  5 29 13 21 22 29 18 33 30]
     2501            [26 18 12 26 17 31 35 18 25 30]
     2502            [21  1 25 14 11 17 29 16 18 12]
     2503            [34 19 12 11 35 30 35 34 25 33]
     2504        """
     2505        cdef celement  p
     2506        cdef celement **m
     2507
     2508        m = self._matrix
     2509        p = self.p
     2510
     2511        cdef Py_ssize_t i, nr
     2512        nr = self._nrows
     2513        for i from start_row <= i < self._nrows:
     2514            m[i][col_to] = (m[i][col_to] + (<celement>multiple) * m[i][col_from]) %p
     2515
     2516    cdef swap_rows_c(self, Py_ssize_t row1, Py_ssize_t row2):
     2517        """
     2518        EXAMPLES::
     2519       
     2520            sage: A = matrix(Integers(8), 2,[1,2,3,4])
     2521            sage: A.swap_rows(0,1)
     2522            sage: A
     2523            [3 4]
     2524            [1 2]
     2525        """
     2526        cdef celement* r1 = self._matrix[row1]
     2527        cdef celement* r2 = self._matrix[row2]
     2528        cdef celement temp
     2529        for i in range(self._ncols):
     2530            temp = r1[i]
     2531            r1[i] = r2[i]
     2532            r2[i] = temp
     2533
     2534    cdef swap_columns_c(self, Py_ssize_t col1, Py_ssize_t col2):
     2535        """
     2536        EXAMPLES::
     2537       
     2538            sage: A = matrix(Integers(8), 2,[1,2,3,4])
     2539            sage: A.swap_columns(0,1)
     2540            sage: A
     2541            [2 1]
     2542            [4 3]
     2543        """
     2544        cdef Py_ssize_t i, nr
     2545        cdef celement t
     2546        cdef celement **m
     2547        m = self._matrix
     2548        nr = self._nrows
     2549        for i from 0 <= i < nr:
     2550            t = m[i][col1]
     2551            m[i][col1] = m[i][col2]
     2552            m[i][col2] = t
     2553           
    22462554    def randomize(self, density=1, nonzero=False):
    22472555        """
    2248         Randomize ``density`` proportion of the entries of this matrix,
    2249         leaving the rest unchanged.
     2556        Randomize ``density`` proportion of the entries of this
     2557        matrix, leaving the rest unchanged.
    22502558       
    22512559        INPUT:
    22522560       
    2253         -  ``density`` - Integer; proportion (roughly) to be considered for
    2254            changes
    2255         -  ``nonzero`` - Bool (default: ``False``); whether the new entries
    2256            are forced to be non-zero
     2561        - ``density`` - Integer; proportion (roughly) to be considered
     2562           for changes
     2563        - ``nonzero`` - Bool (default: ``False``); whether the new
     2564           entries are forced to be non-zero
    22572565       
    22582566        OUTPUT:
    22592567       
     
    22682576            [4 0 0 0 0]
    22692577            [4 0 0 0 0]
    22702578            [0 1 0 0 0]
     2579
    22712580            sage: A.randomize(); A
    22722581            [3 3 2 1 2]
    22732582            [4 3 3 2 2]
    22742583            [0 3 3 3 3]
    22752584            [3 3 2 2 4]
    22762585            [2 2 2 1 4]
     2586
     2587        The matrix is updated instead of overwritten::
     2588
     2589            sage: A = random_matrix(GF(5), 100, 100, density=0.1)
     2590            sage: A.density()
     2591            961/10000
     2592
     2593            sage: A.randomize(density=0.1)
     2594            sage: A.density()
     2595            801/5000
    22772596        """
    22782597        density = float(density)
    22792598        if density <= 0:
     
    23212640
    23222641    def _magma_init_(self, magma):
    23232642        """
    2324         Returns a string representation of self in Magma form.
     2643        Returns a string representation of ``self`` in Magma form.
    23252644       
    23262645        INPUT:
    2327        
    2328        
     2646               
    23292647        -  ``magma`` - a Magma session
    2330        
    2331        
     2648               
    23322649        OUTPUT: string
    23332650       
    23342651        EXAMPLES::
     
    23562673
    23572674        EXAMPLES::
    23582675
    2359             sage: w = matrix(GF(997),2,3,[1,2,5,-3,8,2]); w
     2676            sage: A = matrix(GF(997),2,3,[1,2,5,-3,8,2]); A
    23602677            [  1   2   5]
    23612678            [994   8   2]
    2362             sage: w._export_as_string()
     2679            sage: A._export_as_string()
    23632680            '1 2 5 994 8 2'
    23642681        """
    23652682        cdef int ndigits = len(str(self.p))
     
    23842701
    23852702    def _list(self):
    23862703        """
    2387         Return list of elements of self.  This method is called by ``self.list()``.
     2704        Return list of elements of ``self``.  This method is called by ``self.list()``.
    23882705
    23892706        EXAMPLES::
    23902707
     
    24192736            sage: A.lift().parent()
    24202737            Full MatrixSpace of 2 by 3 dense matrices over Integer Ring
    24212738
    2422 
    24232739            sage: A = matrix(GF(16007),2,3,[1..6])
    24242740            sage: A.lift()
    24252741            [1 2 3]
     
    24622778       
    24632779        INPUT:
    24642780       
    2465         - ``nrows, ncols`` - integers
     2781        - ``nrows`` - integer
     2782
     2783        - ``ncols`` - integer
     2784           
     2785        EXAMPLE::
     2786
     2787            sage: A = matrix(GF(127), 4, 4, range(16))
     2788            sage: A
     2789            [ 0  1  2  3]
     2790            [ 4  5  6  7]
     2791            [ 8  9 10 11]
     2792            [12 13 14 15]           
     2793            sage: A._matrices_from_rows(2,2)
     2794            [
     2795            [0 1]  [4 5]  [ 8  9]  [12 13]
     2796            [2 3], [6 7], [10 11], [14 15]
     2797            ]
    24662798           
    24672799        OUTPUT:
    24682800           
     
    24892821        return ans
    24902822
    24912823    def __nonzero__(self):
     2824        """
     2825        Test whether this matrix is zero.
     2826
     2827        EXAMPLE::
     2828
     2829            sage: A = matrix(GF(7), 10, 10, range(100))
     2830            sage: A == 0 # indirect doctest
     2831            False
     2832            sage: A.is_zero()
     2833            False
     2834
     2835            sage: A = matrix(Integers(10), 10, 10)
     2836            sage: bool(A)
     2837            False
     2838
     2839            sage: A = matrix(GF(16007), 0, 0)
     2840            sage: A.is_zero()
     2841            True
     2842
     2843            sage: A = matrix(GF(16007), 1, 0)
     2844            sage: A.is_zero()
     2845            True
     2846
     2847            sage: A = matrix(GF(16007), 0, 1)
     2848            sage: A.is_zero()
     2849            True
     2850        """
    24922851        return not linbox_is_zero(self.p, self._entries, self._nrows, self._ncols)
    24932852
    24942853    _matrix_from_rows_of_matrices = staticmethod(__matrix_from_rows_of_matrices)
     
    25012860
    25022861cpdef __matrix_from_rows_of_matrices(X):
    25032862    """
     2863    Return a matrix whose row ``i`` is constructed from the entries of
     2864    matrix ``X[i]``.
     2865
    25042866    INPUT:
    25052867       
    25062868    - ``X`` - a nonempty list of matrices of the same size mod a
     
    25372899        [ 4 10 11 15 11  2  9 14 12  5  4  4  2  0 12  8]
    25382900        [13 12  5  1 16 13 16  7 12  2  0 11 13 11  6 15]           
    25392901   
    2540     OUTPUT: A single matrix mod p whose ith row is X[i].list().
     2902    OUTPUT: A single matrix mod ``p`` whose ``i``-th row is ``X[i].list()``.
     2903
     2904    .. note::
     2905       
     2906         Do not call this function directly but use the static method
     2907         ``Matrix_modn_dense_float/double._matrix_from_rows_of_matrices``
    25412908    """
    25422909    # The code below is just a fast version of the following:
    25432910    ##     from constructor import matrix