# HG changeset patch
# User Simon King <simon.king@unijena.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


82  82  def __init__(self, parent, value, value_from_pari=False): 
83  83  """ 
84  84  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. 
85  106  
86  107  EXAMPLES:: 
87  108  
… 
… 

129  150  sage: k([ R(1), x/x ]) 
130  151  t + 2 
131  152  
 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  
132  170  TESTS: 
133  171  
134  172  Check that zeros are created correctly (#11685):: 
… 
… 

168  206  sage: v = a*0; pari(K(v)).lift() 
169  207  Mod(0, 3) 
170  208  
 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  
171  229  """ 
172  230  field_element.FieldElement.__init__(self, parent) 
173  231  self.__class__ = dynamic_FiniteField_ext_pariElement 