add optional order= argument to .log() method for PARI finite-field elements

Author: yyyyx4

src/sage/rings/finite_rings/element_pari_ffelt.pyx

@@ -1100,14 +1100,17 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement):
             else:
                 raise ValueError("element is not a square")
 
-    def log(self, base):
+    def log(self, base, order=None, *, check=False):
         """
         Return a discrete logarithm of ``self`` with respect to the
         given base.
 
         INPUT:
 
         - ``base`` -- non-zero field element
+        - ``order`` -- integer (optional), the order of the base
+        - ``check`` -- boolean (optional, default ``False``): If set,
+          test whether the given ``order`` is correct.
 
         OUTPUT:
 
@@ -1133,6 +1136,23 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement):
             sage: F(1).log(a)
             0
 
+        ::
+
+            sage: p = 2^127-1
+            sage: F.<t> = GF((p, 3))
+            sage: elt = F.random_element()^(p^2+p+1)
+            sage: (elt^2).log(elt, p-1)
+            2
+
+        Passing the ``order`` argument can lead to huge speedups when
+        factoring the order of the entire unit group is expensive but
+        the order of the base element is much smaller::
+
+            sage: %timeit (elt^2).log(elt)       # not tested
+            6.18 s ± 85 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
+            sage: %timeit (elt^2).log(elt, p-1)  # not tested
+            147 ms ± 1.39 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
+
         Some cases where the logarithm is not defined or does not exist::
 
             sage: F.<a> = GF(3^10, impl='pari_ffelt')
@@ -1148,27 +1168,44 @@ cdef class FiniteFieldElement_pari_ffelt(FinitePolyExtElement):
             Traceback (most recent call last):
             ...
             ArithmeticError: discrete logarithm of 0 is not defined
+
+        TESTS:
+
+        An example for ``check=True``::
+
+            sage: a = GF(101^5).primitive_element()
+            sage: a.log(a, 10510100500, check=True)
+            1
+            sage: a.log(a, 5255050250, check=True)
+            Traceback (most recent call last):
+            ...
+            ValueError: element does not have the provided order
         """
         base = self._parent(base)
         if self.is_zero():
             raise ArithmeticError("discrete logarithm of 0 is not defined")
         if base.is_zero():
             raise ArithmeticError("discrete logarithm with base 0 is not defined")
 
-        # Compute the orders of self and base to check whether self
-        # actually lies in the cyclic group generated by base. PARI
-        # requires that this is the case.
-        # We also have to specify the order of the base anyway
-        # because PARI assumes by default that this element generates
-        # the multiplicative group.
-        cdef GEN x, base_order, self_order
+        # Compute the order of the base to check whether the element actually
+        # lies in the group generated by the base. PARI may otherwise enter an
+        # infinite loop.
+        # We also have to specify the order of the base anyway as PARI assumes
+        # by default that the base generates the entire multiplicative group.
+        cdef GEN x, base_order
         sig_on()
-        base_order = FF_order((<FiniteFieldElement_pari_ffelt>base).val, NULL)
-        self_order = FF_order(self.val, NULL)
-        if not dvdii(base_order, self_order):
-            # self_order does not divide base_order
+        if order is None:
+            base_order = FF_order((<FiniteFieldElement_pari_ffelt>base).val, NULL)
+        else:
+            if check:
+                from sage.groups.generic import has_order
+                if not has_order(base, order, '*'):
+                    clear_stack()
+                    raise ValueError('element does not have the provided order')
+            base_order = _new_GEN_from_mpz_t((<Integer>order).value)
+        if not gequal1(powgi(self.val, base_order)):
             clear_stack()
-            raise ArithmeticError("element %s does not lie in group generated by %s"%(self, base))
+            raise ArithmeticError(f'element {self} does not lie in group generated by {base}')
         x = FF_log(self.val, (<FiniteFieldElement_pari_ffelt>base).val, base_order)
         return Integer(new_gen(x))