guessing k-regular sequences

src/sage/combinat/k_regular_sequence.py

@@ -125,6 +125,8 @@ def pad_right(T, length, zero=0):
         (1, 2, 3, 0, 0, 0, 0, 0, 0, 0)
         sage: pad_right((1, 2, 3), 2)
         (1, 2, 3)
+        sage: pad_right([(1, 2), (3, 4)], 4, (0, 0))
+        [(1, 2), (3, 4), (0, 0), (0, 0)]
 
     TESTS::
 
@@ -979,7 +981,7 @@ def _n_to_index_(self, n):
         except OverflowError:
             raise ValueError('value {} of index is negative'.format(n)) from None
 
-    def guess(self, f, n_max=100, max_exponent=10, sequence=None):
+    def guess(self, f, n_verify=100, max_exponent=10, sequence=None):
         r"""
         Guess a `k`-regular sequence whose first terms coincide with `(f(n))_{n\geq0}`.
 
@@ -988,12 +990,14 @@ def guess(self, f, n_max=100, max_exponent=10, sequence=None):
         - ``f`` -- a function (callable) which determines the sequence.
           It takes nonnegative integers as an input
 
-        - ``n_max`` -- (default: ``100``) a positive integer. The resulting
-          `k`-regular sequence coincides with `f` on the first ``n_max``
-          terms
+        - ``n_verify`` -- (default: ``100``) a positive integer. The resulting
+          `k`-regular sequence coincides with `f` on the first ``n_verify``
+          terms.
 
         - ``max_exponent`` -- (default: ``10``) a positive integer specifying
-          the maximum exponent of `k` which is tried when guessing the sequence
+          the maximum exponent of `k` which is tried when guessing the sequence,
+          i.e., relations between `f(k^t n+r)` are used for
+          `0\le t\le \mathtt{max\_exponent}` and `0\le r < k^j`
 
         - ``sequence`` -- (default: ``None``) a `k`-regular sequence used
           for bootstrapping the guessing by adding information of the
@@ -1006,20 +1010,20 @@ def guess(self, f, n_max=100, max_exponent=10, sequence=None):
         ALGORITHM:
 
         For the purposes of this description, the left vector valued sequence
-        associated with a regular sequence is consists of the left vector
+        associated with a regular sequence consists of the left vector
         multiplied by the corresponding matrix product, but without the right
         vector of the regular sequence.
 
         The algorithm maintains a left vector valued sequence consisting
         of the left vector valued sequence of the argument ``sequence``
-        (replaced by an empty tuple if ``sequence`` is `None`) plus several
+        (replaced by an empty tuple if ``sequence`` is ``None``) plus several
         components of the shape `m \mapsto f(k^t\cdot m +r)` for suitable
         ``t`` and ``r``.
 
-        Implicitly, the algorithm also maintains a `d \times n_max` matrix ``A``
+        Implicitly, the algorithm also maintains a `d \times n_\mathrm{verify}` matrix ``A``
         (where ``d`` is the dimension of the left vector valued sequence)
         whose columns are the current left vector valued sequence evaluated at
-        the non-negative integers less than `n_max` and ensures that this
+        the non-negative integers less than `n_\mathrm{verify}` and ensures that this
         matrix has full row rank.
 
         EXAMPLES:
@@ -1053,6 +1057,8 @@ def guess(self, f, n_max=100, max_exponent=10, sequence=None):
                                [-1  2]},
              (0, 1))
 
+        The ``INFO`` messages mean that the right vector valued sequence is the sequence `(s(n), s(2n+1))^\top`.
+
         We guess again, but this time, we use a constant sequence
         for bootstrapping the guessing process::
 
@@ -1121,11 +1127,11 @@ def guess(self, f, n_max=100, max_exponent=10, sequence=None):
             sage: logging.basicConfig(level=logging.DEBUG)
             sage: Seq2.guess(s)
             INFO:...:including f_{1*m+0}
-            DEBUG:...:M_0: f_{2*m+0} = (1) * X_m
+            DEBUG:...:M_0: f_{2*m+0} = (1) * F_m
             INFO:...:including f_{2*m+1}
-            DEBUG:...:M_1: f_{2*m+1} = (0, 1) * X_m
-            DEBUG:...:M_0: f_{4*m+1} = (0, 1) * X_m
-            DEBUG:...:M_1: f_{4*m+3} = (-1, 2) * X_m
+            DEBUG:...:M_1: f_{2*m+1} = (0, 1) * F_m
+            DEBUG:...:M_0: f_{4*m+1} = (0, 1) * F_m
+            DEBUG:...:M_1: f_{4*m+3} = (-1, 2) * F_m
             2-regular sequence 0, 1, 1, 2, 1, 2, 2, 3, 1, 2, ...
             sage: from importlib import reload
             sage: logging.shutdown(); _ = reload(logging)
@@ -1196,6 +1202,51 @@ def guess(self, f, n_max=100, max_exponent=10, sequence=None):
             Traceback (most recent call last):
             ...
             RuntimeError: aborting as exponents would be larger than max_exponent=1
+
+        ::
+
+            sage: R = kRegularSequenceSpace(2, QQ)
+            sage: one = R.one_hadamard()
+            sage: S = R.guess(lambda n: sum(n.bits()), sequence=one) + one
+            sage: T = R.guess(lambda n: n*n, sequence=S, n_verify=4); T
+            2-regular sequence 0, 1, 4, 9, 16, 25, 36, 163/3, 64, 89, ...
+            sage: T.linear_representation()
+            ((0, 0, 1),
+             Finite family {0: [1 0 0]
+                               [0 1 0]
+                               [0 0 4],
+                            1: [   0    1    0]
+                               [  -1    2    0]
+                               [13/3 -5/3 16/3]},
+             (1, 2, 0))
+
+        ::
+
+            sage: two = Seq2.one_hadamard() * 2
+            sage: two.linear_representation()
+            ((1), Finite family {0: [1], 1: [1]}, (2))
+            sage: two_again = Seq2.guess(lambda n: 2, sequence=two)
+            sage: two_again.linear_representation()
+            ((1), Finite family {0: [1], 1: [1]}, (2))
+
+        ::
+
+            sage: def s(k):
+            ....:     return k
+            sage: S1 = Seq2.guess(s)
+            sage: S2 = Seq2.guess(s, sequence=S1)
+            sage: S1
+            2-regular sequence 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
+            sage: S2
+            2-regular sequence 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
+
+        ::
+
+            sage: A = Seq2((Matrix([[1, 1], [1, 1]]), Matrix([[1, 1], [1, 1]])), left=(1, 1), right=(1, 1))
+            sage: Seq2.guess(lambda n: n, sequence=A, n_verify=5)
+            Traceback (most recent call last):
+            ...
+            RuntimeError: no invertible submatrix found
         """
         import logging
         logger = logging.getLogger(__name__)
@@ -1212,18 +1263,17 @@ def guess(self, f, n_max=100, max_exponent=10, sequence=None):
             seq = lambda m: vector([])
         else:
             mu = [M.rows() for M in sequence.mu]
-            seq = lambda m: sequence.left * sequence._mu_of_word_(
-                self._n_to_index_(m))
+            seq = lambda m: (sequence._mu_of_word_(self._n_to_index_(m))
+                             * sequence.right)
             logger.info('including %s', sequence)
 
         zero = domain(0)
         one = domain(1)
 
-        # A `line` will be a triple `(t, r, s)` corresponding to an entry
-        # `k**t * m + r` belonging to `M_s`
-        # TODO: what is `M_s`?
+        # A `line` will be a pair `(t, r)` corresponding to an entry
+        # `k**t * m + r`
 
-        # The elements of `lines` will be correspond to the current components
+        # The elements of `lines` will correspond to the current components
         # of the left vector valued sequence described in the algorithm section
         # of the docstring.
 
@@ -1234,10 +1284,12 @@ def values(m, lines):
             """
             return tuple(seq(m)) + tuple(f(k**t_R * m + r_R) for t_R, r_R in lines)
 
-        @cached_function(key=lambda lines: len(lines))  # we assume that existing lines are not changed (we allow appending of new lines)
+        @cached_function(key=lambda lines: len(lines))
+        # we assume that existing lines are not changed
+        # (we allow appending of new lines)
         def some_inverse_U_matrix(lines):
             r"""
-                Find an invertible `d \times d` times submatrix of the matrix
+                Find an invertible `d \times d` submatrix of the matrix
                 ``A`` described in the algorithm section of the docstring.
 
                 The output is the inverse of the invertible submatrix and
@@ -1246,17 +1298,19 @@ def some_inverse_U_matrix(lines):
             """
             d = len(seq(0)) + len(lines)
 
-            for m_indices in cantor_product(xsrange(n_max), repeat=d, min_slope=1):
+            # The following search for an inverse works but is inefficient;
+            # see :trac:`35748` for details.
+            for m_indices in cantor_product(xsrange(n_verify), repeat=d, min_slope=1):
                 # Iterate over all increasing lists of length d consisting
-                # of non-negative integers less than `n_max`.
+                # of non-negative integers less than `n_verify`.
 
                 U = Matrix(domain, d, d, [values(m, lines) for m in m_indices]).transpose()
                 try:
                     return U.inverse(), m_indices
                 except ZeroDivisionError:
                     pass
             else:
-                raise RuntimeError('no inverse submatrix found')
+                raise RuntimeError('no invertible submatrix found')
 
         def linear_combination_candidate(t_L, r_L, lines):
             r"""
@@ -1276,12 +1330,20 @@ def verify_linear_combination(t_L, r_L, linear_combination, lines):
                 ``r_L``, i.e., `m \mapsto f(k**t_L * m + r_L)`, is the linear
                 combination ``linear_combination`` of the current vector valued
                 sequence.
+
+                Note that we only evaluate the subsequence of ``f`` where arguments
+                of ``f`` are at most ``n_verify``. This might lead to detection of
+                linear dependence which would not be true for higher values, but this
+                coincides with the documentation of ``n_verify``.
+                However, this is not a guarantee that the given function will never
+                be evaluated beyond ``n_verify``, determining an invertible submatrix
+                in ``some_inverse_U_matrix`` might require us to do so.
             """
             return all(f(k**t_L * m + r_L) ==
                        linear_combination * vector(values(m, lines))
-                       for m in xsrange(0, (n_max - r_L) // k**t_L + 1))
+                       for m in xsrange(0, (n_verify - r_L) // k**t_L + 1))
 
-        class NoLinearCombination(ValueError):
+        class NoLinearCombination(RuntimeError):
             pass
 
         def find_linear_combination(t_L, r_L, lines):
@@ -1301,37 +1363,33 @@ def find_linear_combination(t_L, r_L, lines):
         to_branch = []
         lines = []
 
-        def include(line):
-            to_branch.append(line)
-            lines.append(line)
-            t, r = line
+        def include(t, r):
+            to_branch.append((t, r))
+            lines.append((t, r))
             logger.info('including f_{%s*m+%s}', k**t, r)
 
         if left is None:
-            line_L = (0, 0)  # entries (t, r) --> k**t * m + r
-            include(line_L)
-            left = vector((len(seq(0)) + len(lines)-1)*(zero,) + (one,))
+            include(0, 0)  # entries (t, r) --> k**t * m + r
+            assert len(lines) == 1
+            left = vector(len(seq(0))*(zero,) + (one,))
 
         while to_branch:
-            line_R = to_branch.pop(0)
-            t_R, r_R = line_R
+            t_R, r_R = to_branch.pop(0)
             if t_R >= max_exponent:
                 raise RuntimeError(f'aborting as exponents would be larger '
                                    f'than max_exponent={max_exponent}')
 
             t_L = t_R + 1
             for s_L in srange(k):
                 r_L = k**t_R * s_L + r_R
-                line_L = t_L, r_L
-
                 try:
-                    solution = find_linear_combination(t_L, r_L, lines)
+                    linear_combination = find_linear_combination(t_L, r_L, lines)
                 except NoLinearCombination:
-                    include(line_L)
-                    solution = (len(lines)-1)*(zero,) + (one,)
-                logger.debug('M_%s: f_{%s*m+%s} = %s * X_m',
-                             s_L, k**t_L, r_L, solution)
-                mu[s_L].append(solution)
+                    include(t_L, r_L)  # entries (t, r) --> k**t * m + r
+                    linear_combination = (len(lines)-1)*(zero,) + (one,)
+                logger.debug('M_%s: f_{%s*m+%s} = %s * F_m',
+                             s_L, k**t_L, r_L, linear_combination)
+                mu[s_L].append(linear_combination)
 
         d = len(seq(0)) + len(lines)
         mu = tuple(Matrix(domain, [pad_right(tuple(row), d, zero=zero) for row in M])