Ticket #12777: 12777_libecm_sig.patch

File 12777_libecm_sig.patch, 6.0 KB (added by jdemeyer, 10 years ago)
  • doc/en/reference/libs.rst

    # HG changeset patch
    # User Jeroen Demeyer <jdemeyer@cage.ugent.be>
    # Date 1333378230 -7200
    # Node ID 7bb540c65f7caa83e55b4518e50c42ee489f4d39
    # Parent  3230731594472e3e9ae5e8e164de624893570826
    Add signal handling and documentation to libecm.pyx
    
    diff --git a/doc/en/reference/libs.rst b/doc/en/reference/libs.rst
    a b  
    2626   :maxdepth: 2
    2727   
    2828   sage/libs/flint/fmpz_poly
     29   sage/libs/libecm
    2930   sage/libs/pari/gen
    3031   sage/libs/ntl/all
    3132   sage/libs/mwrank/all
  • sage/libs/libecm.pyx

    diff --git a/sage/libs/libecm.pyx b/sage/libs/libecm.pyx
    a b  
    11r"""
    2 The Elliptic Curve Factorization Method, via libecm.
     2The Elliptic Curve Method for Integer Factorization (ECM)
    33
    4 \sage includes GMP-ECM, which is a highly optimized implementation
    5 of Lenstra's elliptic curve factorization method.  See
    6 \url{http://ecm.gforge.inria.fr/}
    7 for more about GMP-ECM.
     4Sage includes GMP-ECM, which is a highly optimized implementation of
     5Lenstra's elliptic curve factorization method.
     6See http://ecm.gforge.inria.fr/ for more about GMP-ECM.
     7This file provides a Cython interface to the GMP-ECM library.
    88
    9 AUTHOR:
    10     Robert L Miller (2008-01-21) -- library interface (clone of ecmfactor.c)
     9AUTHORS:
    1110
    12 EXAMPLE:
     11- Robert L Miller (2008-01-21): library interface (clone of ecmfactor.c)
    1312
    14     sage: import sage.libs.libecm
     13- Jeroen Demeyer (2012-03-29): signal handling, documentation
     14
     15EXAMPLES::
     16
    1517    sage: from sage.libs.libecm import ecmfactor
    1618    sage: result = ecmfactor(999, 0.00)
    1719    sage: result in [(True, 27), (True, 37), (True, 999)]
     
    2123    Found factor in step 1: ...
    2224    sage: result in [(True, 27), (True, 37), (True, 999)]
    2325    True
    24 
    2526"""
     27#*****************************************************************************
     28#       Copyright (C) 2008 Robert Miller
     29#       Copyright (C) 2012 Jeroen Demeyer <jdemeyer@cage.ugent.be>
     30#
     31#  Distributed under the terms of the GNU General Public License (GPL)
     32#  as published by the Free Software Foundation; either version 2 of
     33#  the License, or (at your option) any later version.
     34#                  http://www.gnu.org/licenses/
     35#*****************************************************************************
    2636
    2737include '../ext/cdefs.pxi'
     38include '../ext/interrupt.pxi'
    2839
    2940from sage.rings.integer cimport Integer
    3041
     
    3546    int ecm_factor (mpz_t, mpz_t, double, ecm_params)
    3647    int ECM_NO_FACTOR_FOUND
    3748
    38 def ecmfactor(number, py_B1, verbose=False):
     49def ecmfactor(number, double B1, verbose=False):
     50    """
     51    Try to find a factor of a positive integer using ECM (Elliptic Curve Method).
     52    This function tries one elliptic curve.
     53
     54    INPUT:
     55
     56    - ``number`` -- positive integer to be factored
     57
     58    - ``B1`` -- bound for step 1 of ECM
     59
     60    - ``verbose`` (default: False) -- print some debugging information
     61
     62    OUTPUT:
     63
     64    Either ``(False, None)`` if no factor was found, or ``(True, f)``
     65    if the factor ``f`` was found.
     66
     67    EXAMPLES::
     68
     69        sage: from sage.libs.libecm import ecmfactor
     70
     71    This number has a small factor which is easy to find for ECM::
     72
     73        sage: N = 2^167 - 1
     74        sage: factor(N)
     75        2349023 * 79638304766856507377778616296087448490695649
     76        sage: ecmfactor(N, 2e5)
     77        (True, 2349023)
     78
     79    With a smaller B1 bound, we may or may not succeed::
     80
     81        sage: ecmfactor(N, 1e2)  # random
     82        (False, None)
     83
     84    The following number is a Mersenne prime, so we don't expect to
     85    find any factors (there is an extremely small chance that we get
     86    the input number back as factorization)::
     87
     88        sage: N = 2^127 - 1
     89        sage: N.is_prime()
     90        True
     91        sage: ecmfactor(N, 1e3)
     92        (False, None)
     93
     94    If we have several small prime factors, it is possible to find a
     95    product of primes as factor::
     96
     97        sage: N = 2^179 - 1
     98        sage: factor(N)
     99        359 * 1433 * 1489459109360039866456940197095433721664951999121
     100        sage: ecmfactor(N, 1e3)  # random
     101        (True, 514447)
     102
     103    We can ask for verbose output::
     104
     105        sage: N = 12^97 - 1
     106        sage: factor(N)
     107        11 * 43570062353753446053455610056679740005056966111842089407838902783209959981593077811330507328327968191581
     108        sage: ecmfactor(N, 100, verbose=True)
     109        Performing one curve with B1=100
     110        Found factor in step 1: 11
     111        (True, 11)
     112        sage: ecmfactor(N/11, 100, verbose=True)
     113        Performing one curve with B1=100
     114        Found no factor.
     115        (False, None)
     116
     117    TESTS:
     118
     119    Check that ``ecmfactor`` can be interrupted (factoring a large
     120    prime number)::
     121
     122        sage: import sage.tests.interrupt
     123        sage: try:
     124        ...     sage.tests.interrupt.interrupt_after_delay()
     125        ...     ecmfactor(2^521-1, 1e7)
     126        ... except KeyboardInterrupt:
     127        ...     print "Caught KeyboardInterrupt"
     128        Caught KeyboardInterrupt
     129
     130    Some special cases::
     131
     132        sage: ecmfactor(1, 100)
     133        (True, 1)
     134        sage: ecmfactor(0, 100)
     135        Traceback (most recent call last):
     136        ...
     137        ValueError: Input number (0) must be positive
     138    """
    39139    cdef mpz_t n, f
    40140    cdef int res
    41     cdef double B1
    42141    cdef Integer sage_int_f, sage_int_number
    43142   
    44143    sage_int_f = Integer(0)
    45144    sage_int_number = Integer(number)
    46     B1 = py_B1
    47145
     146    if number <= 0:
     147        raise ValueError("Input number (%s) must be positive"%number)
     148
     149    if verbose:
     150        print "Performing one curve with B1=%1.0f"%B1
     151
     152    sig_on()
    48153    mpz_init(n)
    49154    mpz_set(n, sage_int_number.value)
    50155    mpz_init(f) # For potential factor
    51156
    52     if verbose:
    53         print "Performing one curve with B1=%1.0f"%B1
    54 
    55157    res = ecm_factor(f, n, B1, NULL)
    56158
    57159    if res > 0:
     
    59161
    60162    mpz_clear(f)
    61163    mpz_clear(n)
     164    sig_off()
    62165
    63166    if res > 0:
    64167        if verbose:
     
    70173        return (False, None)
    71174    else:
    72175        raise RuntimeError( "ECM lib error" )
    73