Ticket #10210: 10210_algdep_doc.patch

File 10210_algdep_doc.patch, 6.3 KB (added by Jeroen Demeyer, 12 years ago)
  • sage/rings/arith.py

    # HG changeset patch
    # User Jeroen Demeyer <jdemeyer@cage.ugent.be>
    # Date 1288955445 -3600
    # Node ID 51bf45bcedac01260c3ec082c97044a57f5aac65
    # Parent  55d3c8d9db4684d46ea30f6aa676eb255f315231
    #10210: fix docstring of algdep
    
    diff -r 55d3c8d9db46 -r 51bf45bcedac sage/rings/arith.py
    a b  
    4040def algdep(z, degree, known_bits=None, use_bits=None, known_digits=None, use_digits=None, height_bound=None, proof=False):
    4141    """
    4242    Returns a polynomial of degree at most `degree` which is
    43     approximately satisfied by the number `z`. Note that the
    44     returned polynomial need not be irreducible, and indeed usually
    45     won't be if `z` is a good approximation to an algebraic
    46     number of degree less than `degree`.
    47    
    48     You can specify the number of known bits or digits with ``known_bits=k`` or
    49     ``known_digits=k``; Pari is then told to compute the result using `0.8k`
    50     of these bits/digits. (The Pari documentation recommends using a factor
    51     between .6 and .9, but internally defaults to .8.) Or, you can specify the
    52     precision to use directly with ``use_bits=k`` or ``use_digits=k``. If none
    53     of these are specified, then the precision is taken from the input value.
    54    
    55     A height bound may specified to indicate the maximum coefficient size of
    56     the returned polynomial; if a sufficiently small polyomial is not found
    57     then ``None`` wil be returned. If ``proof=True`` then the result is returned
    58     only if it can be proved correct (i.e. the only possible minimal polynomial
    59     satisfying the height bound, or no such polynomial exists). Otherwise a
    60     ``ValueError`` is raised indicating that higher precision is required.
    61    
    62     ALGORITHM: Uses LLL for real/complex inputs, PARI C-library algdep command otherwise.
     43    approximately satisfied by the number `z`. Note that the returned
     44    polynomial need not be irreducible, and indeed usually won't be if
     45    `z` is a good approximation to an algebraic number of degree less
     46    than `degree`.
     47   
     48    You can specify the number of known bits or digits of `z` with
     49    ``known_bits=k`` or ``known_digits=k``. PARI is then told to
     50    compute the result using `0.8k` of these bits/digits. Or, you can
     51    specify the precision to use directly with ``use_bits=k`` or
     52    ``use_digits=k``. If none of these are specified, then the precision
     53    is taken from the input value.
     54   
     55    A height bound may be specified to indicate the maximum coefficient
     56    size of the returned polynomial; if a sufficiently small polynomial
     57    is not found, then ``None`` will be returned. If ``proof=True`` then
     58    the result is returned only if it can be proved correct (i.e. the
     59    only possible minimal polynomial satisfying the height bound, or no
     60    such polynomial exists). Otherwise a ``ValueError`` is raised
     61    indicating that higher precision is required.
     62   
     63    ALGORITHM: Uses LLL for real/complex inputs, PARI C-library
     64    ``algdep`` command otherwise.
    6365   
    6466    Note that ``algebraic_dependency`` is a synonym for ``algdep``.
    6567
     
    7072   
    7173    -  ``degree`` - an integer
    7274   
    73     -  ``height_bound`` - an integer (default ``None``) specifying the maximum
     75    -  ``height_bound`` - an integer (default: ``None``) specifying the maximum
    7476                          coefficient size for the returned polynomial
    7577
    76     -  ``proof`` - a boolean (default ``False``), requres height_bound to be set
     78    -  ``proof`` - a boolean (default: ``False``), requires height_bound to be set
    7779
    7880   
    7981    EXAMPLES::
     
    8587        sage: algdep(sqrt(2),2)
    8688        x^2 - 2
    8789   
    88     This example involves a complex number.
    89    
    90     ::
     90    This example involves a complex number::
    9191   
    9292        sage: z = (1/2)*(1 + RDF(sqrt(3)) *CC.0); z
    9393        0.500000000000000 + 0.866025403784439*I
     
    9898        sage: z^2 - z + 1
    9999        0
    100100   
    101     This example involves a `p`-adic number.
    102    
    103     ::
     101    This example involves a `p`-adic number::
    104102   
    105103        sage: K = Qp(3, print_mode = 'series')
    106104        sage: a = K(7/19); a
     
    109107        19*x - 7
    110108   
    111109    These examples show the importance of proper precision control. We
    112     compute a 200-bit approximation to sqrt(2) which is wrong in the
    113     33'rd bit.
    114    
    115     ::
     110    compute a 200-bit approximation to `sqrt(2)` which is wrong in the
     111    33'rd bit::
    116112   
    117113        sage: z = sqrt(RealField(200)(2)) + (1/2)^33
    118114        sage: p = algdep(z, 4); p
     
    128124        sage: algdep(z, 4, use_digits=8)
    129125        x^2 - 2
    130126   
    131     Using the ``height_bound`` and ``proof`` parameters, we can see that
    132     `pi` is not the root of an integer polynomial of degree at most 5
    133     and coefficients bounded above by 10.
    134    
    135     ::
     127    Using the ``height_bound`` and ``proof`` parameters, we can see that
     128    `pi` is not the root of an integer polynomial of degree at most 5
     129    and coefficients bounded above by 10::
    136130
    137131        sage: algdep(pi.n(), 5, height_bound=10, proof=True) is None
    138132        True
    139133   
    140     For stronger results, we need more precicion.
    141          
    142     ::
     134    For stronger results, we need more precicion::
    143135   
    144136        sage: algdep(pi.n(), 5, height_bound=100, proof=True) is None
    145137        Traceback (most recent call last):
     
    155147        sage: algdep(pi.n(200), 10, height_bound=10, proof=True) is None
    156148        True
    157149   
    158     We can also use ``proof=True`` to get positive results.
    159    
    160     ::
     150    We can also use ``proof=True`` to get positive results::
    161151   
    162152        sage: a = sqrt(2) + sqrt(3) + sqrt(5)
    163153        sage: algdep(a.n(), 8, height_bound=1000, proof=True)
     
    589579    INPUT:   
    590580   
    591581        -  ``n`` - an integer
    592         -  ``bound (default 1024)`` - int: highest power to test.
     582        -  ``bound (default: 1024)`` - int: highest power to test.
    593583        -  ``get_data`` - boolean: return small pseudoprime and the power.
    594584   
    595585    EXAMPLES::
     
    21932183   
    21942184       - ``'magma'`` - use Magma (requires magma be installed)
    21952185   
    2196     -  ``verbose`` - integer (default 0); pari's debug
     2186    -  ``verbose`` - integer (default: 0); PARI's debug
    21972187       variable is set to this; e.g., set to 4 or 8 to see lots of output
    21982188       during factorization.
    21992189