gh-37329: add optional order= argument to .log() method for PARI finite-field elements
    
When the order of the base element of a finite-field logarithm is
already known, factoring the unit-group order can be skipped. PARI's
`fflog()` accepts the order of the base element as an optional input,
but that argument is currently not exposed in Sage. This patch takes
care of it. An example of the speedup is given in the new doctests.
    
URL: #37329
Reported by: Lorenz Panny
Reviewer(s): Giacomo Pope

Author: Release Manager

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))