gh-36806: add generic has_order() function
    
Currently there is `order_from_multiple()` for generic groups, but
sometimes we really only want to know if the order equals a particular
value (e.g., when sampling random elements to find a generating set of a
group with known structure). This means the computation can be aborted
earlier than when finding the exact order is required.

In this patch we add such an optimized `has_order()` function as well as
a convenience wrapper for elliptic-curve points.  An example of the
speedup can be found in one of the new doctests.
    
URL: #36806
Reported by: Lorenz Panny
Reviewer(s): Lorenz Panny, Travis Scrimshaw

Author: Release Manager

src/sage/groups/generic.py

@@ -1181,6 +1181,8 @@ def linear_relation(P, Q, operation='+', identity=None, inverse=None, op=None):
 # 2. order_from_bounds: finds the order given an interval containing a
 # multiple of the order
 #
+# 3. has_order: check if the order is exactly equal to a given integer
+#
 ################################################################
 
 
@@ -1408,6 +1410,100 @@ def order_from_bounds(P, bounds, d=None, operation='+',
 
     return order_from_multiple(P, m, operation=operation, check=False)
 
+def has_order(P, n, operation='+'):
+    r"""
+    Generic function to test if a group element `P` has order
+    exactly equal to a given positive integer `n`.
+
+    INPUT:
+
+    - ``P`` -- group element with respect to the specified ``operation``
+    - ``n`` -- positive integer, or its :class:`~sage.structure.factorization.Factorization`
+    - ``operation`` -- string, either ``'+'`` (default) or ``'*'``
+
+    EXAMPLES::
+
+        sage: from sage.groups.generic import has_order
+        sage: E.<P> = EllipticCurve(GF(71), [5,5])
+        sage: P.order()
+        57
+        sage: has_order(P, 57)
+        True
+        sage: has_order(P, factor(57))
+        True
+        sage: has_order(P, 19)
+        False
+        sage: has_order(3*P, 19)
+        True
+        sage: has_order(3*P, 57)
+        False
+
+    ::
+
+        sage: R = Zmod(14981)
+        sage: g = R(321)
+        sage: g.multiplicative_order()
+        42
+        sage: has_order(g, 42, operation='*')
+        True
+        sage: has_order(g, factor(42), operation='*')
+        True
+        sage: has_order(g, 70, operation='*')
+        False
+
+    TESTS::
+
+        sage: ns = [randrange(1,10**5) for _ in range(randrange(1,5))]
+        sage: A = AdditiveAbelianGroup(ns)
+        sage: from sage.groups.generic import has_order
+        sage: el = A.random_element()
+        sage: o = el.order()
+        sage: has_order(el, o)
+        True
+        sage: has_order(el, o.factor())
+        True
+        sage: has_order(el, ZZ(randrange(100)*o + randrange(o)))
+        False
+
+    .. NOTE::
+
+        In some cases, order *testing* can be much faster than
+        *computing* the order using :func:`order_from_multiple`.
+    """
+    if isinstance(n, sage.rings.integer.Integer):
+        n = n.factor()
+
+    G = P.parent()
+    if operation in addition_names:
+        isid = lambda el: not el
+        mult = lambda el, n: multiple(el, n, operation='+')
+    elif operation in multiplication_names:
+        isid = lambda el: el.is_one()
+        mult = multiple
+    else:
+        raise ValueError('unknown group operation')
+
+    def _rec(Q, fn):
+        if not fn:
+            return isid(Q)
+
+        if len(fn) == 1:
+            p, k = fn[0]
+            for _ in range(k):
+                if isid(Q):
+                    return False
+                Q = mult(Q, p)
+            return isid(Q)
+
+        fl = fn[::2]
+        fr = fn[1::2]
+        l = prod(p**k for p,k in fl)
+        r = prod(p**k for p,k in fr)
+        L, R = mult(Q, r), mult(Q, l)
+        return _rec(L, fl) and _rec(R, fr)
+
+    return _rec(P, n)
+
 
 def merge_points(P1, P2, operation='+',
                  identity=None, inverse=None, op=None, check=True):

src/sage/schemes/elliptic_curves/ell_point.py

@@ -539,6 +539,104 @@ def __bool__(self):
         """
         return bool(self[2])
 
+    def has_order(self, n):
+        r"""
+        Test if this point has order exactly `n`.
+
+        INPUT:
+
+        - ``n`` -- integer, or its :class:`~sage.structure.factorization.Factorization`
+
+        ALGORITHM:
+
+        Compare a cached order if available, otherwise use :func:`sage.groups.generic.has_order`.
+
+        EXAMPLES::
+
+            sage: E = EllipticCurve('26b1')
+            sage: P = E(1, 0)
+            sage: P.has_order(7)
+            True
+            sage: P._order
+            7
+            sage: P.has_order(7)
+            True
+
+        It also works with a :class:`~sage.structure.factorization.Factorization` object::
+
+            sage: E = EllipticCurve(GF(419), [1,0])
+            sage: P = E(-33, 8)
+            sage: P.has_order(factor(21))
+            True
+            sage: P._order
+            21
+            sage: P.has_order(factor(21))
+            True
+
+        This method can be much faster than computing the order and comparing::
+
+            sage: # not tested -- timings are different each time
+            sage: p = 4 * prod(primes(3,377)) * 587 - 1
+            sage: E = EllipticCurve(GF(p), [1,0])
+            sage: %timeit P = E.random_point(); P.set_order(multiple=p+1)
+            72.4 ms ± 773 µs per loop (mean ± std. dev. of 7 runs, 1 loop each)
+            sage: %timeit P = E.random_point(); P.has_order(p+1)
+            32.8 ms ± 3.12 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
+            sage: fac = factor(p+1)
+            sage: %timeit P = E.random_point(); P.has_order(fac)
+            30.6 ms ± 3.48 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)
+
+        The order is cached once it has been confirmed once, and the cache is
+        shared with :meth:`order`::
+
+            sage: # not tested -- timings are different each time
+            sage: P, = E.gens()
+            sage: delattr(P, '_order')
+            sage: %time P.has_order(p+1)
+            CPU times: user 83.6 ms, sys: 30 µs, total: 83.6 ms
+            Wall time: 83.8 ms
+            True
+            sage: %time P.has_order(p+1)
+            CPU times: user 31 µs, sys: 2 µs, total: 33 µs
+            Wall time: 37.9 µs
+            True
+            sage: %time P.order()
+            CPU times: user 11 µs, sys: 0 ns, total: 11 µs
+            Wall time: 16 µs
+            5326738796327623094747867617954605554069371494832722337612446642054009560026576537626892113026381253624626941643949444792662881241621373288942880288065660
+            sage: delattr(P, '_order')
+            sage: %time P.has_order(fac)
+            CPU times: user 68.6 ms, sys: 17 µs, total: 68.7 ms
+            Wall time: 68.7 ms
+            True
+            sage: %time P.has_order(fac)
+            CPU times: user 92 µs, sys: 0 ns, total: 92 µs
+            Wall time: 97.5 µs
+            True
+            sage: %time P.order()
+            CPU times: user 10 µs, sys: 1e+03 ns, total: 11 µs
+            Wall time: 14.5 µs
+            5326738796327623094747867617954605554069371494832722337612446642054009560026576537626892113026381253624626941643949444792662881241621373288942880288065660
+
+        TESTS::
+
+            sage: E = EllipticCurve([1,2,3,4,5])
+            sage: E(0).has_order(1)
+            True
+            sage: E(0).has_order(Factorization([]))
+            True
+        """
+        if hasattr(self, '_order'):                 # already known
+            if not isinstance(n, Integer):
+                n = n.value()
+            return self._order == n
+        ret = generic.has_order(self, n, operation='+')
+        if ret and not hasattr(self, '_order'):     # known now; cache
+            if not isinstance(n, Integer):
+                n = n.value()
+            self._order = n
+        return ret
+
     def has_finite_order(self):
         """
         Return ``True`` if this point has finite additive order as an