gh-35935: add multiple= option to EllipticCurvePoint_field.set_order()
    
Calling `order_from_multiple()` followed by `.set_order()` on elliptic-
curve points is a common pattern in algorithms for elliptic curves over
finite fields (for instance, this is part of a simple algorithm for
sampling points of specified order). This patch adds a shorthand for the
combination, allowing us to write `P.set_order(multiple=m)` instead.
    
URL: #35935
Reported by: Lorenz Panny
Reviewer(s): John Cremona

Author: Release Manager

src/sage/schemes/elliptic_curves/ell_point.py

@@ -1188,16 +1188,24 @@ def _divide_out(self, p):
             pts = Q.division_points(p)
         return (Q, k)
 
-    def set_order(self, value, *, check=True):
+    def set_order(self, value=None, *, multiple=None, check=True):
         r"""
-        Set the value of ``self._order`` to ``value``.
+        Set the cached order of this point (i.e., the value of
+        ``self._order``) to the given ``value``.
 
-        Use this when you know a priori the order of this point to avoid a
-        potentially expensive order calculation.
+        Alternatively, when ``multiple`` is given, this method will
+        first run :func:`~sage.groups.generic.order_from_multiple`
+        to determine the exact order from the given multiple of the
+        point order, then cache the result.
+
+        Use this when you know a priori the order of this point, or
+        a multiple of the order, to avoid a potentially expensive
+        order calculation.
 
         INPUT:
 
         - ``value`` -- positive integer
+        - ``multiple`` -- positive integer; mutually exclusive with ``value``
 
         OUTPUT: ``None``
 
@@ -1212,6 +1220,10 @@ def set_order(self, value, *, check=True):
             sage: G.set_order(2)                                                        # optional - sage.rings.finite_rings
             sage: 2*G                                                                   # optional - sage.rings.finite_rings
             (0 : 1 : 0)
+            sage: G = E(0, 6)                                                           # optional - sage.rings.finite_rings
+            sage: G.set_order(multiple=12)                                              # optional - sage.rings.finite_rings
+            sage: G._order                                                              # optional - sage.rings.finite_rings
+            3
 
         We now give a more interesting case, the NIST-P521 curve. Its
         order is too big to calculate with Sage, and takes a long time
@@ -1233,7 +1245,31 @@ def set_order(self, value, *, check=True):
             (0 : 1 : 0)
             sage: proof.arithmetic(prev_proof_state) # restore state
 
-        It is an error to pass a `value` equal to `0`::
+        Using ``.set_order()`` with a ``multiple=`` argument can
+        be used to compute a point's order *significantly* faster
+        than calling :meth:`order` if the point is already known
+        to be `m`-torsion::
+
+            sage: F.<a> = GF((10007, 23))
+            sage: E = EllipticCurve(F, [9,9])
+            sage: n = E.order()
+            sage: m = 5 * 47 * 139 * 1427 * 2027 * 4831 * 275449 * 29523031
+            sage: assert m.divides(n)
+            sage: P = n/m * E.lift_x(6747+a)
+            sage: assert m * P == 0
+            sage: P.set_order(multiple=m)   # compute exact order
+            sage: factor(m // P.order())    # order is now cached
+            47 * 139
+
+        The algorithm used internally for this functionality is
+        :meth:`~sage.groups.generic.order_from_multiple`.
+        Indeed, simply calling :meth:`order` on ``P`` would take
+        much longer since factoring ``n`` is fairly expensive::
+
+            sage: n == m * 6670822796985115651 * 441770032618665681677 * 9289973478285634606114927
+            True
+
+        It is an error to pass a ``value`` equal to `0`::
 
             sage: E = EllipticCurve(GF(7), [0, 1])  # This curve has order 12           # optional - sage.rings.finite_rings
             sage: G = E.random_point()                                                  # optional - sage.rings.finite_rings
@@ -1257,20 +1293,53 @@ def set_order(self, value, *, check=True):
             ...
             ValueError: Value 11 illegal: 11 * (5 : 0 : 1) is not the identity
 
-        However, ``set_order`` can be fooled, though it's not likely in "real cases
-        of interest". For instance, the order can be set to a multiple the
-        actual order::
+        However, ``set_order`` can be fooled. For instance, the order
+        can be set to a multiple the actual order::
 
             sage: E = EllipticCurve(GF(7), [0, 1])  # This curve has order 12           # optional - sage.rings.finite_rings
             sage: G = E(5, 0)   # G has order 2                                         # optional - sage.rings.finite_rings
             sage: G.set_order(8)                                                        # optional - sage.rings.finite_rings
             sage: G.order()                                                             # optional - sage.rings.finite_rings
             8
 
+        TESTS:
+
+        Check that some invalid inputs are caught::
+
+            sage: E = EllipticCurve(GF(101), [5,5])
+            sage: P = E.lift_x(11)
+            sage: P.set_order(17, multiple=119)
+            Traceback (most recent call last):
+            ...
+            ValueError: cannot pass both value and multiple
+            sage: P.set_order(17)
+            sage: P.set_order(multiple=119+1)
+            Traceback (most recent call last):
+            ...
+            ValueError: previously cached order 17 does not divide given multiple 120
+            sage: P.set_order(119)
+            Traceback (most recent call last):
+            ...
+            ValueError: value 119 contradicts previously cached order 17
+
         AUTHORS:
 
         - Mariah Lenox (2011-02-16)
+        - Lorenz Panny (2022): add ``multiple=`` option
         """
+        if multiple is not None:
+            if value is not None:
+                raise ValueError('cannot pass both value and multiple')
+
+            if hasattr(self, '_order'):  # already known
+                if check and not self._order.divides(multiple):
+                    raise ValueError(f'previously cached order {self._order} does not divide given multiple {multiple}')
+                return
+
+            from sage.groups.generic import order_from_multiple
+            value = order_from_multiple(self, multiple, check=check)
+            check = False
+
         value = Integer(value)
 
         if check:
@@ -1283,6 +1352,9 @@ def set_order(self, value, *, check=True):
                 raise ValueError('Value %s illegal: outside max Hasse bound' % value)
             if value * self != E(0):
                 raise ValueError('Value %s illegal: %s * %s is not the identity' % (value, value, self))
+            if hasattr(self, '_order') and self._order != value:  # already known
+                raise ValueError(f'value {value} contradicts previously cached order {self._order}')
+
         self._order = value
 
     # #############################  end  ################################