Trac #23724: Allow random sampling for unit testing

#16244 removed random sampling, but there are times when it would be
nice to have.  This ticket adds it back in, but optionally.

URL: https://trac.sagemath.org/23724
Reported by: roed
Ticket author(s): David Roe
Reviewer(s): Julian Rüth

Author: Release Manager

src/sage/misc/misc.py

@@ -1174,11 +1174,30 @@ def random_sublist(X, s):
     return [a for a in X if random.random() <= s]
 
 
-def some_tuples(elements, repeat, bound):
+def some_tuples(elements, repeat, bound, max_samples=None):
     r"""
     Return an iterator over at most ``bound`` number of ``repeat``-tuples of
     ``elements``.
 
+    INPUT:
+
+    - ``elements`` -- an iterable
+    - ``repeat`` -- integer (default ``None``), the length of the tuples to be returned.
+      If ``None``, just returns entries from ``elements``.
+    - ``bound`` -- the maximum number of tuples returned (ignored if ``max_samples`` given)
+    - ``max_samples`` -- non-negative integer (default ``None``).  If given,
+      then a sample of the possible tuples will be returned,
+      instead of the first few in the standard order.
+
+    OUTPUT:
+
+    If ``max_samples`` is not provided, an iterator over the first
+    ``bound`` tuples of length ``repeat``, in the standard nested-for-loop order.
+
+    If ``max_samples`` is provided, a list of at most ``max_samples`` tuples,
+    sampled uniformly from the possibilities.  In this case, ``elements``
+    must be finite.
+
     TESTS::
 
         sage: from sage.misc.misc import some_tuples
@@ -1192,15 +1211,44 @@ def some_tuples(elements, repeat, bound):
         sage: len(list(l))
         10
 
-    .. TODO::
+        sage: l = some_tuples(range(3), 2, None, max_samples=10)
+        sage: len(list(l))
+        9
+    """
+    if max_samples is None:
+        from itertools import islice, product
+        P = elements if repeat is None else product(elements, repeat=repeat)
+        return islice(P, bound)
+    else:
+        if not (hasattr(elements, '__len__') and hasattr(elements, '__getitem__')):
+            elements = list(elements)
+        n = len(elements)
+        N = n if repeat is None else n**repeat
+        if N <= max_samples:
+            from itertools import product
+            return elements if repeat is None else product(elements, repeat=repeat)
+        return _some_tuples_sampling(elements, repeat, max_samples, n)
 
-        Currently, this only return an iterator over the first element of the
-        Cartesian product. It would be smarter to return something more
-        "random like" as it is used in tests. However, this should remain
-        deterministic.
+def _some_tuples_sampling(elements, repeat, max_samples, n):
     """
-    from itertools import islice, product
-    return islice(product(elements, repeat=repeat), bound)
+    Internal function for :func:`some_tuples`.
+
+    TESTS::
+
+        sage: from sage.misc.misc import _some_tuples_sampling
+        sage: list(_some_tuples_sampling(range(3), 3, 2, 3))
+        [(0, 1, 0), (1, 1, 1)]
+        sage: list(_some_tuples_sampling(range(20), None, 4, 20))
+        [0, 6, 9, 3]
+    """
+    from sage.rings.integer import Integer
+    N = n if repeat is None else n**repeat
+    # We sample on range(N) and create tuples manually since we don't want to create the list of all possible tuples in memory
+    for a in random.sample(range(N), max_samples):
+        if repeat is None:
+            yield elements[a]
+        else:
+            yield tuple(elements[j] for j in Integer(a).digits(n, padto=repeat))
 
 def powerset(X):
     r"""

src/sage/misc/sage_unittest.py

@@ -15,6 +15,7 @@
 import unittest
 import sys
 import traceback
+import random
 
 class TestSuite(object):
     """
@@ -76,7 +77,7 @@ class TestSuite(object):
 
     Debugging tip: in case of failure of some test, use ``%pdb on`` to
     turn on automatic debugging on error. Run the failing test
-    independtly: the debugger will stop right where the first
+    independently: the debugger will stop right where the first
     assertion fails. Then, introspection can be used to analyse what
     exactly the problem is. See also the ``catch = False`` option to
     :meth:`.run`.
@@ -269,16 +270,16 @@ def _test_b(self, tester): tester.fail()
               ...
             AssertionError: None
 
-        In conjunction with ``%pdb on``, this allows for the debbuger
+        In conjunction with ``%pdb on``, this allows for the debugger
         to jump directly to the first failure location.
         """
         if isinstance(skip, str):
             skip = [skip]
         else:
             skip = tuple(skip)
 
-        # The class of exceptions that will be catched and reported;
-        # other exceptions will get trough. None catches nothing.
+        # The class of exceptions that will be caught and reported;
+        # other exceptions will get through. None catches nothing.
         catch_exception = Exception if catch else None
 
         tester = instance_tester(self._instance, **options)
@@ -373,7 +374,7 @@ class InstanceTester(unittest.TestCase):
         Testing utilities for Rational Field
     """
 
-    def __init__(self, instance, elements = None, verbose = False, prefix = "", max_runs = 4096, **options):
+    def __init__(self, instance, elements = None, verbose = False, prefix = "", max_runs = 4096, max_samples = None, **options):
         """
         A gadget attached to an instance providing it with testing utilities.
 
@@ -383,7 +384,7 @@ def __init__(self, instance, elements = None, verbose = False, prefix = "", max_
             sage: InstanceTester(instance = ZZ, verbose = True, elements = [1,2,3])
             Testing utilities for Integer Ring
 
-        This is used by ``SageObject._tester``, which see::
+        This is used by ``SageObject._tester``, for example::
 
             sage: QQ._tester()
             Testing utilities for Rational Field
@@ -394,6 +395,7 @@ def __init__(self, instance, elements = None, verbose = False, prefix = "", max_
         self._elements = elements
         self._prefix = prefix
         self._max_runs = max_runs
+        self._max_samples = max_samples
 
     def runTest(self):
         """
@@ -448,9 +450,9 @@ def __repr__(self):
         return "Testing utilities for %s"%self._instance
 
 
-    def some_elements(self, S=None):
+    def some_elements(self, S=None, repeat=None):
         """
-        Returns a list (or iterable) of elements of ``self`` on which
+        Returns a list (or iterable) of elements of the instance on which
         the tests should be run. This is only meaningful for container
         objects like parents.
 
@@ -461,9 +463,13 @@ def some_elements(self, S=None):
           time, or the result of :meth:`.some_elements` if no elements
           were specified.
 
+        - ``repeat`` -- integer (default: None).  If given, instead returns
+          a list of tuples of length ``repeat`` from ``S``.
+
         OUTPUT:
 
-        A list of at most ``self._max_runs`` elements of ``S``.
+        A list of at most ``self._max_runs`` elements of ``S^r``,
+        or a sample of at most ``self._max_samples`` if that is not ``None``.
 
         EXAMPLES:
 
@@ -520,6 +526,18 @@ def some_elements(self, S=None):
             sage: list(tester.some_elements())
             [0, 1, 2]
 
+        The ``repeat`` keyword can give pairs or triples from ``S``::
+
+            sage: list(tester.some_elements(repeat=2))
+            [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1)]
+
+        You can use ``max_samples`` to sample at random, instead of in order::
+
+            sage: tester = InstanceTester(ZZ, elements = srange(8), max_samples = 4)
+            sage: list(tester.some_elements())
+            [0, 3, 7, 1]
+            sage: list(tester.some_elements(repeat=2))
+            [(1, 4), (3, 1), (4, 5), (5, 0)]
 
         Test for :trac:`15919`, :trac:`16244`::
 
@@ -539,14 +557,9 @@ def some_elements(self, S=None):
             sage: list(tester.some_elements())
             [(0, 0, 0, 0), (0, 0, 0, 1), (0, 0, 0, 2), (0, 0, 0, 3)]
         """
-        if S is None:
-            if self._elements is None:
-                S = self._instance.some_elements()
-            else:
-                S = self._elements
-        import itertools
-        return list(itertools.islice(S,0,self._max_runs))
-
+        S = S or self._elements or self._instance.some_elements()
+        from sage.misc.misc import some_tuples
+        return list(some_tuples(S, repeat, self._max_runs, self._max_samples))
 
 class PythonObjectWithTests(object):
     """