Ticket #12034: trac_12034.patch

File trac_12034.patch, 17.0 KB (added by was, 18 months ago)

  • sage/matrix/benchmark.py 

    # HG changeset patch
# User William Stein <wstein@gmail.com>
# Date 1321321277 28800
# Node ID 06d60d896e52fe9474699e928b4944bdde019a71
# Parent  d95ee8f31642cba95103e54dc10ee356c831c7f0
trac 12034: improve doctest coverage of matrix/benchmark.py to 100%

diff --git a/sage/matrix/benchmark.py b/sage/matrix/benchmark.py
    a b  
    44 
    55timeout = 60 
    66 
    7 def report(F, title): 
    8     systems = ['sage', 'magma'] 
    9     print '\n\n' 
     7def report(F, title, systems = ['sage', 'magma']): 
     8    """ 
     9    Run benchmarks with default arguments for each function in the list F. 
     10         
     11    EXAMPLES:: 
     12 
     13        sage: import sage.matrix.benchmark as b 
     14        sage: b.report([b.det_ZZ], 'Test', systems=['sage']) 
     15        ====================================================================== 
     16                  Test 
     17        ====================================================================== 
     18        ... 
     19        ====================================================================== 
     20    """ 
     21    if len(systems) > 2: 
     22        raise NotImplementedError, "at most two systems ('sage' or 'magma')" 
    1023    print '='*70 
    1124    print ' '*10 + title 
    1225    print '='*70 
    … …  
    2538                t = -timeout 
    2639            alarm(0) 
    2740            w.append(float(t)) 
    28         if w[1] == 0: 
    29             w.append(0.0) 
    30         else: 
    31             w.append(w[0]/w[1]) 
     41        if len(w) > 1: 
     42            if w[1] == 0: 
     43                w.append(0.0) 
     44            else: 
     45                w.append(w[0]/w[1]) 
     46                 
    3247        w = tuple(w) 
    33  
    3448        print ('%15.3f'*len(w))%w 
     49    print '='*70 
    3550     
    3651 
    3752####################################################################### 
    3853# Dense Benchmarks over ZZ 
    3954####################################################################### 
    4055 
    41 def report_ZZ(): 
     56def report_ZZ(**kwds): 
    4257    """ 
    4358    Reports all the benchmarks for integer matrices and few 
    4459    rational matrices. 
    45     TODO: Probably I should start report_QQ as well. 
     60 
     61    EXAMPLES:: 
     62     
     63        sage: import sage.matrix.benchmark as b 
     64        sage: b.report_ZZ(systems=['sage']) 
     65        ====================================================================== 
     66        Dense benchmarks over ZZ 
     67        ====================================================================== 
     68        ... 
     69        ====================================================================== 
    4670    """ 
    4771    F = [vecmat_ZZ, rank_ZZ, rank2_ZZ, charpoly_ZZ, smithform_ZZ, 
    4872         det_ZZ, det_QQ, matrix_multiply_ZZ, matrix_add_ZZ, 
    … …  
    5074         nullspace_ZZ] 
    5175 
    5276    title = 'Dense benchmarks over ZZ' 
    53     report(F, title) 
     77    report(F, title, **kwds) 
    5478 
    5579# Integer Nullspace 
    5680 
    57 def nullspace_ZZ(n=400, min=0, max=2**32, system='sage'): 
     81def nullspace_ZZ(n=200, min=0, max=2**32, system='sage'): 
    5882    """ 
    5983    Nullspace over ZZ: 
    6084    Given a n+1 x n (with n=400) matrix over ZZ with random entries 
    6185    with 32 bits, compute the nullspace. 
     86 
     87    EXAMPLES:: 
     88 
     89        sage: import sage.matrix.benchmark as b 
     90        sage: ts = b.nullspace_ZZ(200) 
     91        sage: tm = b.nullspace_ZZ(200, system='magma')  # optional - magma 
    6292    """ 
    6393    if system == 'sage': 
    6494        A = random_matrix(ZZ, n+1, n, x=min, y=max+1).change_ring(QQ) 
    … …  
    80110        raise ValueError, 'unknown system "%s"'%system 
    81111         
    82112 
    83 def charpoly_ZZ(n=300, min=0, max=9, system='sage'): 
     113def charpoly_ZZ(n=100, min=0, max=9, system='sage'): 
    84114    """ 
    85115    Characteristic polynomial over ZZ: 
    86116    Given a n x n (with n=300) matrix over ZZ with random entries 
    87117    between min=0 and max=9, compute the charpoly. 
     118 
     119    EXAMPLES:: 
     120 
     121        sage: import sage.matrix.benchmark as b 
     122        sage: ts = b.charpoly_ZZ(100) 
     123        sage: tm = b.charpoly_ZZ(100, system='magma')  # optional - magma 
    88124    """ 
    89125    if system == 'sage': 
    90126        A = random_matrix(ZZ, n, n, x=min, y=max+1) 
    … …  
    111147    Rank over ZZ: 
    112148    Given a n x (n+10) (with n=700) matrix over ZZ with random entries 
    113149    between min=0 and max=9, compute the rank. 
     150 
     151 
     152    EXAMPLES:: 
     153 
     154        sage: import sage.matrix.benchmark as b 
     155        sage: ts = b.rank_ZZ(300) 
     156        sage: tm = b.rank_ZZ(300, system='magma')  # optional - magma 
    114157    """ 
    115158    if system == 'sage': 
    116159        A = random_matrix(ZZ, n, n+10, x=min, y=max+1) 
    … …  
    136179    Rank 2 over ZZ: 
    137180    Given a (n + 10) x n (with n=400) matrix over ZZ with random entries 
    138181    between with 64 bits, compute the rank. 
     182 
     183    EXAMPLES:: 
     184     
     185        sage: import sage.matrix.benchmark as b 
     186        sage: ts = b.rank2_ZZ(300) 
     187        sage: tm = b.rank2_ZZ(300, system='magma')  # optional - magma 
    139188    """ 
    140189    if system == 'sage': 
    141190        A = random_matrix(ZZ, n+10, n, x=min, y=max+1) 
    … …  
    163212    Smith Form over ZZ: 
    164213    Given a n x n (with n=128) matrix over ZZ with random entries 
    165214    between min=0 and max=9, compute the Smith normal form. 
     215 
     216    EXAMPLES:: 
     217     
     218        sage: import sage.matrix.benchmark as b 
     219        sage: ts = b.smithform_ZZ(100) 
     220        sage: tm = b.smithform_ZZ(100, system='magma')  # optional - magma 
    166221    """ 
    167222    if system == 'sage': 
    168223        A = random_matrix(ZZ, n, n, x=min, y=max+1) 
    … …  
    189244    Matrix multiplication over ZZ 
    190245    Given an n x n (with n=300) matrix A over ZZ with random entries 
    191246    between min=-9 and max=9, inclusive, compute A * (A+1). 
     247 
     248    EXAMPLES:: 
     249     
     250        sage: import sage.matrix.benchmark as b 
     251        sage: ts = b.matrix_multiply_ZZ(200) 
     252        sage: tm = b.matrix_multiply_ZZ(200, system='magma')  # optional - magma 
    192253    """ 
    193254    if system == 'sage': 
    194255        A = random_matrix(ZZ, n, n, x=min, y=max+1) 
    … …  
    214275    else: 
    215276        raise ValueError, 'unknown system "%s"'%system 
    216277     
    217 def matrix_add_ZZ(n=500, min=-9, max=9, system='sage', times=50): 
     278def matrix_add_ZZ(n=200, min=-9, max=9, system='sage', times=50): 
    218279    """ 
    219280    Matrix addition over ZZ 
    220281    Given an n x n (with n=500) matrix A and B over ZZ with random entries 
    221282    between min=-9 and max=9, inclusive, compute A + B 50 times. 
     283 
     284    EXAMPLES:: 
     285     
     286        sage: import sage.matrix.benchmark as b 
     287        sage: ts = b.matrix_add_ZZ(200) 
     288        sage: tm = b.matrix_add_ZZ(200, system='magma')  # optional - magma 
    222289    """ 
    223290    if system == 'sage': 
    224291        A = random_matrix(ZZ, n, n, x=min, y=max+1) 
    … …  
    246313    else: 
    247314        raise ValueError, 'unknown system "%s"'%system 
    248315  
    249 def matrix_add_ZZ_2(n=500, bits=16, system='sage', times=50): 
     316def matrix_add_ZZ_2(n=200, bits=16, system='sage', times=50): 
    250317    """ 
    251318    Matrix addition over ZZ. 
    252319    Given an n x n (with n=500) matrix A and B over ZZ with random 16-bit 
    253320    entries, compute A + B 50 times. 
     321 
     322    EXAMPLES:: 
     323     
     324        sage: import sage.matrix.benchmark as b 
     325        sage: ts = b.matrix_add_ZZ_2(200) 
     326        sage: tm = b.matrix_add_ZZ_2(200, system='magma')  # optional - magma 
    254327    """ 
    255328    b = 2**bits 
    256329    return matrix_add_ZZ(n=n, min=-b, max=b,system=system, times=times) 
    257330 
    258 def det_ZZ(n=400, min=1, max=100, system='sage'): 
     331def det_ZZ(n=200, min=1, max=100, system='sage'): 
    259332    """ 
    260333    Dense integer determinant over ZZ. 
    261334    Given an n x n (with n=400) matrix A over ZZ with random entries 
    262335    between min=1 and max=100, inclusive, compute det(A). 
     336 
     337    EXAMPLES:: 
     338 
     339        sage: import sage.matrix.benchmark as b 
     340        sage: ts = b.det_ZZ(200) 
     341        sage: tm = b.det_ZZ(200, system='magma')  # optional - magma 
    263342    """ 
    264343    if system == 'sage': 
    265344        A = random_matrix(ZZ, n, n, x=min, y=max+1) 
    … …  
    287366    Given an n x n (with n=300) matrix A over QQ with random entries 
    288367    with numerator and denominator between min=-10 and 10, 
    289368    inclusive, compute det(A). 
     369 
     370    EXAMPLES:: 
     371 
     372        sage: import sage.matrix.benchmark as b 
     373        sage: ts = b.det_QQ(200) 
     374        sage: ts = b.det_QQ(10, num_bound=100000, den_bound=10000) 
     375        sage: tm = b.det_QQ(200, system='magma')  # optional - magma 
    290376    """ 
    291377    if system == 'sage': 
    292378        A = random_matrix(QQ, n, n, num_bound=num_bound, den_bound=den_bound) 
    … …  
    308394        raise ValueError, 'unknown system "%s"'%system 
    309395 
    310396 
    311 def vecmat_ZZ(n=750, system='sage', min=-9, max=9, times=200): 
     397def vecmat_ZZ(n=300, system='sage', min=-9, max=9, times=200): 
    312398    """ 
    313399    Vector matrix multiplication over ZZ. 
    314400     
    315401    Given an n x n (with n=750) matrix A over ZZ with random entries 
    316402    between min=-9 and max=9, inclusive, and v the first row of A, 
    317     compute the product v * A  200 times.  
     403    compute the product v * A  200 times. 
     404 
     405    EXAMPLES:: 
     406 
     407        sage: import sage.matrix.benchmark as b 
     408        sage: ts = b.vecmat_ZZ(300) 
     409        sage: tm = b.vecmat_ZZ(300, system='magma')  # optional - magma 
    318410    """ 
    319411    if system == 'sage': 
    320412        A = random_matrix(ZZ, n, n, x=min, y=max+1) 
    … …  
    347439# Dense Benchmarks over GF(p), for small p. 
    348440####################################################################### 
    349441 
    350 def report_GF(p=16411): 
     442def report_GF(p=16411, **kwds): 
    351443    """ 
    352444    Runs all the reports for finite field matrix operations, for 
    353445    prime p=16411.  
    354446    Note: right now, even though p is an input, it is being ignored! 
    355447    If you need to check the performance for other primes, you can 
    356448    call individual benchmark functions. 
     449 
     450    EXAMPLES:: 
     451 
     452        sage: import sage.matrix.benchmark as b 
     453        sage: b.report_GF(systems=['sage']) 
     454        ====================================================================== 
     455        Dense benchmarks over GF with prime 16411 
     456        ====================================================================== 
     457        ... 
     458        ====================================================================== 
    357459    """ 
    358460    F = [rank_GF, rank2_GF, nullspace_GF, charpoly_GF,  
    359461         matrix_multiply_GF, det_GF] 
    360462    title = 'Dense benchmarks over GF with prime %i' % p 
    361     report(F, title) 
     463    report(F, title, **kwds) 
    362464 
    363465# Nullspace over GF 
    364466 
    … …  
    366468    """ 
    367469    Given a n+1 x n (with n=300) matrix over GF(p) p=16411 with random 
    368470    entries, compute the nullspace. 
     471 
     472    EXAMPLES:: 
     473 
     474        sage: import sage.matrix.benchmark as b 
     475        sage: ts = b.nullspace_GF(300) 
     476        sage: tm = b.nullspace_GF(300, system='magma')  # optional - magma 
    369477    """ 
    370478    if system == 'sage': 
    371479        A = random_matrix(GF(p), n, n+1) 
    … …  
    393501    """ 
    394502    Given a n x n (with n=100) matrix over GF with random entries, 
    395503    compute the charpoly. 
     504 
     505    EXAMPLES:: 
     506 
     507        sage: import sage.matrix.benchmark as b 
     508        sage: ts = b.charpoly_GF(100) 
     509        sage: tm = b.charpoly_GF(100, system='magma')  # optional - magma 
    396510    """ 
    397511    if system == 'sage': 
    398512        A = random_matrix(GF(p), n, n) 
    … …  
    417531    """ 
    418532    Given two n x n (with n=1000) matrix over GF with random entries, 
    419533    add them. 
     534 
     535    EXAMPLES:: 
     536 
     537        sage: import sage.matrix.benchmark as b 
     538        sage: ts = b.matrix_add_GF(500, p=19) 
     539        sage: tm = b.matrix_add_GF(500, p=19, system='magma')  # optional - magma 
    420540    """ 
    421541    if system == 'sage': 
    422542        A = random_matrix(GF(p), n, n) 
    … …  
    450570    """ 
    451571    Given an n x n (with n=100) matrix A over GF(p) with random 
    452572    entries, compute A * (A+1). 
     573 
     574    EXAMPLES:: 
     575 
     576        sage: import sage.matrix.benchmark as b 
     577        sage: ts = b.matrix_multiply_GF(100, p=19) 
     578        sage: tm = b.matrix_multiply_GF(100, p=19, system='magma')  # optional - magma 
    453579    """ 
    454580    if system == 'sage': 
    455581        A = random_matrix(GF(p), n) 
    … …  
    481607    Rank over GF: 
    482608    Given a n x (n+10) (with n=500) matrix over ZZ with random entries 
    483609    between min=0 and max=9, compute the rank. 
     610 
     611    EXAMPLES:: 
     612 
     613        sage: import sage.matrix.benchmark as b 
     614        sage: ts = b.rank_GF(1000) 
     615        sage: tm = b.rank_GF(1000, system='magma')  # optional - magma 
    484616    """ 
    485617    if system == 'sage': 
    486618        A = random_matrix(GF(p), n, n+10) 
    … …  
    506638    Rank over GF(p): 
    507639    Given a (n + 10) x n (with n=500) matrix over GF(p) with random entries 
    508640    between min=0 and max=9, compute the rank. 
     641 
     642    EXAMPLES:: 
     643 
     644        sage: import sage.matrix.benchmark as b 
     645        sage: ts = b.rank2_GF(500) 
     646        sage: tm = b.rank2_GF(500, system='magma')  # optional - magma 
    509647    """ 
    510648    if system == 'sage': 
    511649        A = random_matrix(GF(p), n+10, n) 
    … …  
    531669    Dense integer determinant over GF. 
    532670    Given an n x n (with n=400) matrix A over GF with random entries 
    533671    compute det(A). 
     672 
     673    EXAMPLES:: 
     674 
     675        sage: import sage.matrix.benchmark as b 
     676        sage: ts = b.det_GF(1000) 
     677        sage: tm = b.det_GF(1000, system='magma')  # optional - magma 
    534678    """ 
    535679    if system == 'sage': 
    536680        A = random_matrix(GF(p), n, n) 
    … …  
    562706def hilbert_matrix(n): 
    563707    """ 
    564708    Returns the Hilbert matrix of size n over rationals. 
     709 
     710    EXAMPLES:: 
     711 
     712        sage: import sage.matrix.benchmark as b 
     713        sage: b.hilbert_matrix(3) 
     714        [  1 1/2 1/3] 
     715        [1/2 1/3 1/4] 
     716        [1/3 1/4 1/5] 
    565717    """ 
    566718    A = Matrix(QQ,n,n) 
    567719    for i in range(A.nrows()): 
    … …  
    575727    """ 
    576728    Given a n x (2*n) (with n=100) matrix over QQ with random integer entries 
    577729    between min=0 and max=9, compute the reduced row echelon form. 
     730 
     731    EXAMPLES:: 
     732 
     733        sage: import sage.matrix.benchmark as b 
     734        sage: ts = b.echelon_QQ(100) 
     735        sage: tm = b.echelon_QQ(100, system='magma')  # optional - magma 
    578736    """ 
    579737    if system == 'sage': 
    580738        A = random_matrix(ZZ, n, 2*n, x=min, y=max+1).change_ring(QQ) 
    … …  
    601759    """ 
    602760    Given a n x n (with n=100) matrix over QQ with random integer entries 
    603761    between min=0 and max=9, compute the reduced row echelon form. 
     762 
     763    EXAMPLES:: 
     764 
     765        sage: import sage.matrix.benchmark as b 
     766        sage: ts = b.inverse_QQ(100) 
     767        sage: tm = b.inverse_QQ(100, system='magma')  # optional - magma 
    604768    """ 
    605769    if system == 'sage': 
    606770        A = random_matrix(ZZ, n, n, x=min, y=max+1).change_ring(QQ) 
    … …  
    628792    Given an n x n (with n=100) matrix A over QQ with random entries 
    629793    whose numerators and denominators are bounded by b, compute A * 
    630794    (A+1). 
     795 
     796    EXAMPLES:: 
     797 
     798        sage: import sage.matrix.benchmark as b 
     799        sage: ts = b.matrix_multiply_QQ(100) 
     800        sage: tm = b.matrix_multiply_QQ(100, system='magma')  # optional - magma 
    631801    """ 
    632802    if system == 'sage': 
    633803        A = random_matrix(QQ, n, n, num_bound=bnd, den_bound=bnd) 
    … …  
    660830    """ 
    661831    Runs the benchmark for calculating the determinant of the hilbert 
    662832    matrix over rationals of dimension n. 
     833 
     834 
     835    EXAMPLES:: 
     836 
     837        sage: import sage.matrix.benchmark as b 
     838        sage: ts = b.det_hilbert_QQ(50) 
     839        sage: tm = b.det_hilbert_QQ(50, system='magma')  # optional - magma 
    663840    """ 
    664841    if system == 'sage': 
    665842        A = hilbert_matrix(n) 
    … …  
    683860    """ 
    684861    Runs the benchmark for calculating the inverse of the hilbert 
    685862    matrix over rationals of dimension n. 
     863 
     864    EXAMPLES:: 
     865 
     866        sage: import sage.matrix.benchmark as b 
     867        sage: ts = b.invert_hilbert_QQ(30) 
     868        sage: tm = b.invert_hilbert_QQ(30, system='magma')  # optional - magma 
    686869    """ 
    687870    if system == 'sage': 
    688871        A = hilbert_matrix(n) 
    … …  
    702885        return float(magma.eval('s')) 
    703886 
    704887def MatrixVector_QQ(n=1000,h=100,system='sage',times=1): 
     888    """ 
     889    Compute product of square n matrix by random vector with num and 
     890    denom bounded by 100 the given number of times.  
     891     
     892    EXAMPLES:: 
     893     
     894        sage: import sage.matrix.benchmark as b 
     895        sage: ts = b.MatrixVector_QQ(500) 
     896        sage: tm = b.MatrixVector_QQ(500, system='magma')  # optional - magma 
     897    """ 
    705898    if system=='sage': 
    706899        V=QQ**n 
    707900        v=V.random_element(h) 
    … …  
    743936    Nullspace over RR: 
    744937    Given a n+1 x n (with n=300) matrix over RR with random entries 
    745938    between min=0 and max=10, compute the nullspace. 
     939 
     940    EXAMPLES:: 
     941 
     942        sage: import sage.matrix.benchmark as b 
     943        sage: ts = b.nullspace_RR(100) 
     944        sage: tm = b.nullspace_RR(100, system='magma')  # optional - magma 
    746945    """ 
    747946    if system == 'sage': 
    748947        A = random_matrix(ZZ, n+1, n, x=min, y=max+1).change_ring(RR) 
    … …  
    764963        raise ValueError, 'unknown system "%s"'%system 
    765964         
    766965 
     966def nullspace_RDF(n=300, min=0, max=10, system='sage'): 
     967    """ 
     968    Nullspace over RDF: 
     969    Given a n+1 x n (with n=300) matrix over RDF with random entries 
     970    between min=0 and max=10, compute the nullspace. 
     971 
     972    EXAMPLES:: 
     973 
     974        sage: import sage.matrix.benchmark as b 
     975        sage: ts = b.nullspace_RDF(100) 
     976        sage: tm = b.nullspace_RDF(100, system='magma')  # optional - magma 
     977    """ 
     978    if system == 'sage': 
     979        A = random_matrix(ZZ, n+1, n, x=min, y=max+1).change_ring(RDF) 
     980        t = cputime() 
     981        v = A.kernel() 
     982        return cputime(t) 
     983    elif system == 'magma': 
     984        code = """ 
     985n := %s; 
     986A := RMatrixSpace(RealField(16), n+1,n)![Random(%s,%s) : i in [1..n*(n+1)]]; 
     987t := Cputime(); 
     988K := Kernel(A); 
     989s := Cputime(t); 
     990"""%(n,min,max) 
     991        if verbose: print code 
     992        magma.eval(code) 
     993        return float(magma.eval('s')) 
     994    else: 
     995        raise ValueError, 'unknown system "%s"'%system 
     996         
     997