Trac #33941: Implement from_integer and to_integer for all finite fields, extending and replacing fetch_int and integer_representation

Finite fields have `.fetch_int()` to decode integers into finite-field
elements by reinterpreting the base-`p` representation as a polynomial:
{{{#!sage
sage: F.<t> = GF(7^10)
sage: el = F.fetch_int(2424); el
t^4 + 3*t + 2
}}}

However, the inverse operation is a bit cumbersome:
{{{#!sage
sage: el.polynomial().change_ring(ZZ)(el.parent().characteristic())
2424
}}}

In this patch, we add an inverse to `.fetch_int()`, named
`.to_integer()` in resemblance with the Python method `int.to_bytes()`.

For symmetry, we then rename `.fetch_int()` to `.from_integer()`: I, for
one, could never remember if `.fetch_int()` refers to "fetching an
element from an int" or "fetching this element into an int", so I think
the new name makes a lot more sense.

Also, some code cleanup and optimization while we're at it.

URL: https://trac.sagemath.org/33941
Reported by: lorenz
Ticket author(s): Lorenz Panny
Reviewer(s): Kwankyu Lee

Author: Release Manager

src/sage/crypto/mq/rijndael_gf.py

@@ -785,7 +785,7 @@ def _GF_to_hex(self, GF):
                not GF.parent().order() == 2**8:
                 msg = "keyword 'GF' must be in"
                 raise TypeError(msg.format(self._F))
-            return hex(GF.integer_representation())[2:].zfill(2)
+            return hex(GF.to_integer())[2:].zfill(2)
 
     def _bin_to_GF(self, B, matrix=True):
         r"""
@@ -911,7 +911,7 @@ def _GF_to_bin(self, GF):
                not GF.parent().order() == 2**8:
                 msg = "keyword 'GF' must be in"
                 raise TypeError(msg.format(self._F))
-            return bin(GF.integer_representation())[2:].zfill(8)
+            return bin(GF.to_integer())[2:].zfill(8)
 
     def encrypt(self, plain, key, format='hex'):
         r"""

src/sage/crypto/mq/sr.py

@@ -762,9 +762,9 @@ def sub_byte(self, b):
 
             # constant addition
             if e == 4:
-                b = b + k.fetch_int(6)
+                b = b + k.from_integer(6)
             elif e == 8:
-                b = b + k.fetch_int(99)
+                b = b + k.from_integer(99)
 
             return b
 
@@ -782,9 +782,9 @@ def sbox_constant(self):
         """
         k = self.k
         if self.e == 4:
-            return k.fetch_int(6)
+            return k.from_integer(6)
         elif self.e == 8:
-            return k.fetch_int(99)
+            return k.from_integer(99)
         else:
             raise TypeError("sbox constant only defined for e in (4, 8)")
 
@@ -1006,7 +1006,7 @@ def state_array(self, d=None):
 
             sage: sr = mq.SR(2, 2, 2, 4)
             sage: k = sr.base_ring()
-            sage: e1 = [k.fetch_int(e) for e in range(2*2)]; e1
+            sage: e1 = [k.from_integer(e) for e in range(2*2)]; e1
             [0, 1, a, a + 1]
             sage: e2 = sr.phi( Matrix(k, 2*2, 1, e1) )
             sage: sr.state_array(e1) # note the column major ordering
@@ -1229,8 +1229,8 @@ def __call__(self, P, K):
 
             sage: sr = mq.SR(10, 4, 4, 8, star=True, allow_zero_inversions=True)
             sage: k = sr.base_ring()
-            sage: plaintext = sr.state_array([k.fetch_int(e) for e in range(16)])
-            sage: key = sr.state_array([k.fetch_int(e) for e in range(16)])
+            sage: plaintext = sr.state_array([k.from_integer(e) for e in range(16)])
+            sage: key = sr.state_array([k.from_integer(e) for e in range(16)])
             sage: print(sr.hex_str_matrix( sr(plaintext, key) ))
             0A 41 F1 C6
             94 6E C3 53
@@ -1301,9 +1301,9 @@ def __call__(self, P, K):
         F = self.base_ring()
 
         if isinstance(P, str):
-            P = self.state_array([F.fetch_int(ZZ(P[i:i+2], 16)) for i in range(0, len(P), 2)])
+            P = self.state_array([F.from_integer(ZZ(P[i: i + 2], 16)) for i in range(0, len(P), 2)])
         if isinstance(K, str):
-            K = self.state_array([F.fetch_int(ZZ(K[i:i+2], 16)) for i in range(0, len(K), 2)])
+            K = self.state_array([F.from_integer(ZZ(K[i: i + 2], 16)) for i in range(0, len(K), 2)])
 
         if self.is_state_array(P) and self.is_state_array(K):
             _type = self.state_array
@@ -1433,9 +1433,9 @@ def hex_str_matrix(self, M):
         for x in range(M.nrows()):
             for y in range(M.ncols()):
                 if e == 8:
-                    st.append("%02X" % M[x, y].integer_representation())
+                    st.append("%02X" % M[x, y].to_integer())
                 else:
-                    st.append("%X" % M[x, y].integer_representation())
+                    st.append("%X" % M[x, y].to_integer())
             st.append("\n")
         return " ".join(st)
 
@@ -1464,9 +1464,9 @@ def hex_str_vector(self, M):
         for y in range(M.ncols()):
             for x in range(M.nrows()):
                 if e == 8:
-                    st.append("%02X" % M[x, y].integer_representation())
+                    st.append("%02X" % M[x, y].to_integer())
                 else:
-                    st.append("%X" % M[x, y].integer_representation())
+                    st.append("%X" % M[x, y].to_integer())
             #st.append("\n")
         return "".join(st)
 
@@ -2321,13 +2321,13 @@ def lin_matrix(self, length = None):
 
         lin = Matrix(self.base_ring(), length*e, length*e)
         if e == 4:
-            l = [ k.fetch_int(x) for x in  (5, 1, 12, 5) ]
+            l = [k.from_integer(x) for x in (5, 1, 12, 5)]
             for k in range( 0, length ):
                 for i in range(0, 4):
                     for j in range(0, 4):
                         lin[k*4+j, k*4+i] = l[(i-j)%4] ** (2**j)
         elif e == 8:
-            l = [ k.fetch_int(x) for x in  (5, 9, 249, 37, 244, 1, 181, 143) ]
+            l = [k.from_integer(x) for x in (5, 9, 249, 37, 244, 1, 181, 143)]
             for k in range( 0, length ):
                 for i in range(0, 8):
                     for j in range(0, 8):

src/sage/libs/ntl/ntl_GF2X.pyx

@@ -160,7 +160,7 @@ cdef class ntl_GF2X():
             if x.characteristic() == 2:
                 x = list(x.modulus())
         elif isinstance(x, FiniteField_givaroElement):
-            x = "0x"+hex(x.integer_representation())[2:][::-1]
+            x = "0x" + hex(x.to_integer())[2:][::-1]
         elif isinstance(x, FiniteField_ntl_gf2eElement):
             x = x.polynomial().list()
         s = str(x).replace(","," ")

src/sage/libs/ntl/ntl_mat_GF2E.pyx

@@ -78,7 +78,7 @@ cdef class ntl_mat_GF2E():
             [0x0 0x0 0x0 0x0 0x0]
             [0x0 0x0 0x0 0x0 0x0]
             ]
-            sage: A= matrix(k,5,5,[k.fetch_int(_%(2^4)) for _ in range(25)])
+            sage: A = matrix(k, 5, 5, [k.from_integer(i % 2^4) for i in range(25)])
             sage: ntl.mat_GF2E(ctx, A)
             [[0x0 0x1 0x2 0x3 0x4]
             [0x5 0x6 0x7 0x8 0x9]

src/sage/matrix/matrix_gf2e_dense.pyx

@@ -129,7 +129,7 @@ cdef class M4RIE_finite_field:
             gf2e_free(self.ff)
 
 cdef m4ri_word poly_to_word(f):
-    return f.integer_representation()
+    return f.to_integer()
 
 
 cdef class Matrix_gf2e_dense(matrix_dense.Matrix_dense):

src/sage/matrix/matrix_gfpn_dense.pyx

@@ -105,11 +105,11 @@ cdef class FieldConverter_class:
         sage: C = M._converter
         sage: C.fel_to_field(15)
         3*y
-        sage: F.fetch_int(15)
+        sage: F.from_integer(15)
         3*y
         sage: C.field_to_fel(y)
         5
-        sage: y.integer_representation()
+        sage: y.to_integer()
         5
     """
     def __init__(self, field):
@@ -139,7 +139,7 @@ cdef class FieldConverter_class:
             sage: C = FieldConverter_class(F)
             sage: C.fel_to_field(15)
             3*y
-            sage: F.fetch_int(15)
+            sage: F.from_integer(15)
             3*y
         """
         return self.field(FfToInt(x))
@@ -155,7 +155,7 @@ cdef class FieldConverter_class:
             sage: C = FieldConverter_class(F)
             sage: C.field_to_fel(y)
             5
-            sage: y.integer_representation()
+            sage: y.to_integer()
             5
 
         TESTS:
@@ -165,9 +165,9 @@ cdef class FieldConverter_class:
             sage: C.field_to_fel('foo')
             Traceback (most recent call last):
             ...
-            AttributeError: 'str' object has no attribute 'integer_representation'
+            AttributeError: 'str' object has no attribute 'to_integer'
         """
-        return FfFromInt(x.integer_representation())
+        return FfFromInt(x.to_integer())
 
 
 cdef class PrimeFieldConverter_class(FieldConverter_class):

src/sage/rings/finite_rings/element_base.pyx

@@ -19,7 +19,9 @@ AUTHORS:
 
 from sage.structure.element cimport Element
 from sage.structure.parent cimport Parent
+from sage.rings.integer_ring import ZZ
 from sage.rings.integer import Integer
+from sage.misc.superseded import deprecated_function_alias
 
 def is_FiniteFieldElement(x):
     """
@@ -213,7 +215,7 @@ cdef class FinitePolyExtElement(FiniteRingElement):
 
     def __getitem__(self, n):
         r"""
-        Return the `n`\th coefficient of this finite-field element when
+        Return the `n`\th coefficient of this finite field element when
         written as a polynomial in the generator.
 
         EXAMPLES::
@@ -250,7 +252,7 @@ cdef class FinitePolyExtElement(FiniteRingElement):
     def list(self):
         r"""
         Return the list of coefficients (in little-endian) of this
-        finite-field element when written as a polynomial in the
+        finite field element when written as a polynomial in the
         generator.
 
         Equivalent to calling ``list()`` on this element.
@@ -266,7 +268,7 @@ cdef class FinitePolyExtElement(FiniteRingElement):
             True
 
         The coefficients returned are those of a fully reduced
-        representative of the finite-field element::
+        representative of the finite field element::
 
             sage: b = u^777
             sage: b.list()
@@ -288,7 +290,7 @@ cdef class FinitePolyExtElement(FiniteRingElement):
 
     def __iter__(self):
         r"""
-        Return an iterator over the coefficients of this finite-field
+        Return an iterator over the coefficients of this finite field
         element, in the same order as :meth:`list`.
 
         EXAMPLES::
@@ -670,7 +672,6 @@ cdef class FinitePolyExtElement(FiniteRingElement):
             1
         """
         if self.is_zero():
-            from sage.rings.integer import Integer
             return Integer(1)
         return self.parent().characteristic()
 
@@ -878,7 +879,6 @@ cdef class FinitePolyExtElement(FiniteRingElement):
                 else: raise ValueError
         if extend:
             raise NotImplementedError
-        from sage.rings.integer import Integer
         n = Integer(n)
         return self._nth_root_common(n, all, algorithm, cunningham)
 
@@ -983,6 +983,67 @@ cdef class FinitePolyExtElement(FiniteRingElement):
 
         return self.pth_power(k=k)
 
+    def to_integer(self, reverse=False):
+        r"""
+        Return an integer representation of this finite field element
+        obtained by lifting its representative polynomial to `\ZZ` and
+        evaluating it at the characteristic `p`.
+
+        If ``reverse`` is set to ``True`` (default: ``False``),
+        the list of coefficients is reversed prior to evaluation.
+
+        Inverse of :meth:`sage.rings.finite_rings.finite_field_base.FiniteField.from_integer`.
+
+        EXAMPLES::
+
+            sage: F.<t> = GF(7^5)
+            sage: F(5).to_integer()
+            5
+            sage: t.to_integer()
+            7
+            sage: (t^2).to_integer()
+            49
+            sage: (t^2+1).to_integer()
+            50
+            sage: (t^2+t+1).to_integer()
+            57
+
+        ::
+
+            sage: F.<t> = GF(2^8)
+            sage: u = F.from_integer(0xd1)
+            sage: bin(u.to_integer(False))
+            '0b11010001'
+            sage: bin(u.to_integer(True))
+            '0b10001011'
+
+        TESTS::
+
+            sage: p = random_prime(2^99)
+            sage: k = randrange(2,10)
+            sage: F.<t> = GF((p, k))
+            sage: rev = bool(randrange(2))
+            sage: u = F.random_element()
+            sage: 0 <= u.to_integer(rev) < F.cardinality()
+            True
+            sage: F.from_integer(u.to_integer(rev), rev) == u
+            True
+            sage: n = randrange(F.cardinality())
+            sage: F.from_integer(n, rev).to_integer(rev) == n
+            True
+        """
+        if not reverse:
+            try:
+                return self._integer_representation()
+            except AttributeError:
+                pass
+        p = self.parent().characteristic()
+        f = self.polynomial().change_ring(ZZ)
+        if reverse:
+            f = f.reverse(self.parent().degree() - 1)
+        return f(p)
+
+    integer_representation = deprecated_function_alias(33941, to_integer)
 
 cdef class Cache_base(SageObject):
     cpdef FinitePolyExtElement fetch_int(self, number):

src/sage/rings/finite_rings/element_givaro.pyx

@@ -643,7 +643,7 @@ cdef class Cache_givaro(Cache_base):
             sage: k._cache._element_int_repr(a^20)
             '74'
         """
-        return str(e.integer_representation())
+        return str(e._integer_representation())
 
     def _element_poly_repr(self, FiniteField_givaroElement e, varname=None):
         """
@@ -1350,7 +1350,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement):
             raise TypeError("Cannot coerce element to an integer.")
         return self_int
 
-    def integer_representation(FiniteField_givaroElement self):
+    def _integer_representation(FiniteField_givaroElement self):
         r"""
         Return the integer representation of ``self``.  When ``self`` is in the
         prime subfield, the integer returned is equal to ``self``.
@@ -1362,15 +1362,19 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement):
 
         OUTPUT: A Python ``int``.
 
+        .. SEEALSO::
+
+            :meth:`sage.rings.finite_rings.element_base.FinitePolyExtElement.to_integer`
+
         EXAMPLES::
 
             sage: k.<b> = GF(5^2); k
             Finite Field in b of size 5^2
-            sage: k(4).integer_representation()
+            sage: k(4)._integer_representation()
             4
-            sage: b.integer_representation()
+            sage: b._integer_representation()
             5
-            sage: type(b.integer_representation())
+            sage: type(b._integer_representation())
             <... 'int'>
         """
         return self._cache.log_to_int(self.element)
@@ -1669,7 +1673,7 @@ cdef class FiniteField_givaroElement(FinitePolyExtElement):
             sage: hash(a)
             5
         """
-        return hash(self.integer_representation())
+        return hash(self._integer_representation())
 
     def _vector_(FiniteField_givaroElement self, reverse=False):
         """