Ticket #11685: 11685_referee.patch

File 11685_referee.patch, 3.2 KB (added by SimonKing, 11 years ago)

Referee patch, adding documentation

  • sage/rings/finite_rings/element_ext_pari.py

    # HG changeset patch
    # User Simon King <simon.king@uni-jena.de>
    # Date 1313599645 -7200
    # Node ID 345cdb236169ddc9bf9eb071e912958e8ae3d2d9
    # Parent  44f029067ed77386eecd2e8ac521e15aca1a9318
    #11685: Referee patch; add documentation.
    
    diff --git a/sage/rings/finite_rings/element_ext_pari.py b/sage/rings/finite_rings/element_ext_pari.py
    a b  
    8282    def __init__(self, parent, value, value_from_pari=False):
    8383        """
    8484        Create element of a finite field.
     85
     86        INPUT:
     87
     88        - ``parent``: A finite field, the parent of this element.
     89        - ``value``: Anything that can be converted into the Pari
     90          interface and can be interpreted as an element of ``parent``.
     91        - ``value_from_pari``: optional bool, default False. If it evaluates
     92          as true, then ``value`` *must* be an element of the
     93          Pari interface, and there will be no conversion.
     94
     95        NOTE:
     96
     97        If the given value is a list or an element of the vector space
     98        associated with the given parent, then it is interpreted as
     99        the list of coefficients of a polynomial over the prime subfield,
     100        and that polynomial is interpreted as an element of the given
     101        parent. The empty list results in zero.
     102
     103        If ``value_from_pari==True`` then it is assumed that the given value
     104        is a suitable representation of the element in Pari, and there is no
     105        conversion. Hence, it is very fast, but must be used with care.
    85106       
    86107        EXAMPLES::
    87108       
     
    129150            sage: k([ R(-1), x/x ])
    130151            t + 2
    131152
     153        We demonstrate the creation of an element via polynomials::
     154
     155            sage: k.polynomial()
     156            t^11 + 2*t^2 + 1
     157            sage: P = k.polynomial_ring()
     158            sage: k(P.0^11)
     159            t^2 + 2
     160
     161        We demonstrate the creation of an element via a vector::
     162
     163            sage: V = k.vector_space()
     164            sage: V
     165            Vector space of dimension 11 over Finite Field of size 3
     166            sage: v = V([0,1,2,0,1,2,0,1,2,0,1])
     167            sage: k(v)
     168            t^10 + 2*t^8 + t^7 + 2*t^5 + t^4 + 2*t^2 + t
     169
    132170        TESTS:
    133171
    134172        Check that zeros are created correctly (#11685)::
     
    168206            sage: v = a*0; pari(K(v)).lift()
    169207            Mod(0, 3)
    170208
     209        The following test documents the optional argument ``value_from_pari``. It is
     210        for internal use only and greatly improves the speed in arithmetic
     211        operations. However, the example shows why it must only be used
     212        carefully::
     213
     214            sage: from sage.rings.finite_rings.element_ext_pari import FiniteField_ext_pariElement
     215            sage: a = FiniteField_ext_pariElement(K,pari(0),value_from_pari=True)
     216            sage: a
     217            0
     218            sage: a == K(0)
     219            False
     220
     221        The reason is that the pari elements representing ``a`` and ``K(0)`` are
     222        different::
     223
     224            sage: pari(a).lift()
     225            0
     226            sage: pari(K(0)).lift()
     227            Mod(0, 3)
     228
    171229        """
    172230        field_element.FieldElement.__init__(self, parent)
    173231        self.__class__ = dynamic_FiniteField_ext_pariElement