Merge branch 't/21204/sequences/k-regular-guess' into t/21343/k-regular-warning

* t/21204/sequences/k-regular-guess:
  Trac #21204: fix punctuation
  Trac #21319: fix punctuation
  Trac #21318: rmul/lmul preserve identity for multiplying by 1
  Trac #21325: fixup test .subsequence being identity
  Trac #21318: rmul/lmul preserve identity for multiplying by 1
  Trac #21325: use (new) decorator minimize_result
  Trac #21325: remove empty lines, fix punctuation
  Trac #21325: remove iteritems
  Trac #21318: fix rmul/lmul issues
  Trac #21318: use "correct" 1
  Trac #21318: use tensor_product in method hadamard_product
  Trac #21318: use is_trivial_zero in doctest of _neg_
  Trac #21318: use (new) .linear_representation in doctests
  Trac #21318: fix empty lines and punctuation
  Trac #21318: decorator minimize_result
  Trac #21203 review issue 10: use "raise ... from None" where approriate

Author: dkrenn

src/sage/combinat/k_regular_sequence.py

@@ -101,6 +101,7 @@
 
 from .recognizable_series import RecognizableSeries
 from .recognizable_series import RecognizableSeriesSpace
+from .recognizable_series import minimize_result
 from sage.misc.cachefunc import cached_function, cached_method
 
 
@@ -111,15 +112,15 @@ def pad_right(T, length, zero=0):
 
     INPUT:
 
-    - ``T`` -- A tuple, list or other iterable.
+    - ``T`` -- A tuple, list or other iterable
 
-    - ``length`` -- a nonnegative integer.
+    - ``length`` -- a nonnegative integer
 
-    - ``zero`` -- (default: ``0``) the elements to pad with.
+    - ``zero`` -- (default: ``0``) the elements to pad with
 
     OUTPUT:
 
-    An object of the same type as ``T``.
+    An object of the same type as ``T``
 
     EXAMPLES::
 
@@ -147,14 +148,14 @@ def value(D, k):
 
     INPUT:
 
-    - ``D`` -- a tuple or other iterable.
+    - ``D`` -- a tuple or other iterable
 
-    - ``k`` -- the base.
+    - ``k`` -- the base
 
     OUTPUT:
 
     An element in the common parent of the base `k` and of the entries
-    of `D`.
+    of `D`
 
     EXAMPLES::
 
@@ -172,16 +173,16 @@ def split_interlace(n, k, p):
 
     INPUT:
 
-    - ``n`` -- an integer.
+    - ``n`` -- an integer
 
-    - ``k`` -- an integer specifying the base.
+    - ``k`` -- an integer specifying the base
 
     - ``p`` -- a positive integer specifying in how many parts
       the input ``n`` is split. This has to be a divisor of ``k``.
 
     OUTPUT:
 
-    A tuple of integers.
+    A tuple of integers
 
     EXAMPLES::
 
@@ -384,7 +385,6 @@ def __iter__(self):
         from itertools import count
         return iter(self[n] for n in count())
 
-
     @cached_method
     def is_degenerated(self):
         r"""
@@ -610,27 +610,30 @@ def _minimized_right_(self):
         """
         return self.transposed(allow_degenerated_sequence=True)._minimized_left_().transposed(allow_degenerated_sequence=True)
 
-    def subsequence(self, a, b, minimize=True):
+    @minimize_result
+    def subsequence(self, a, b):
         r"""
         Return the subsequence with indices `an+b` of this
         `k`-regular sequence.
 
         INPUT:
 
-        - ``a`` -- a nonnegative integer.
+        - ``a`` -- a nonnegative integer
 
-        - ``b`` -- an integer.
+        - ``b`` -- an integer
 
           Alternatively, this is allowed to be a dictionary
           `b_j \mapsto c_j`. If so, the result will be the sum
           of all `c_j(an+b_j)`.
 
-        - ``minimize`` -- (default: ``True``) a boolean. If set, then
-          :meth:`minimized` is called after the operation.
+        - ``minimize`` -- (default: ``None``) a boolean or ``None``.
+          If ``True``, then :meth:`minimized` is called after the operation,
+          if ``False``, then not. If this argument is ``None``, then
+          the default specified by the parent's ``minimize_results`` is used.
 
         OUTPUT:
 
-        A :class:`kRegularSequence`.
+        A :class:`kRegularSequence`
 
         .. NOTE::
 
@@ -682,7 +685,10 @@ def subsequence(self, a, b, minimize=True):
 
             sage: C.subsequence(0, 4)
             2-regular sequence 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, ...
-            sage: C.subsequence(1, 0) is C
+
+        ::
+
+            sage: C.subsequence(1, 0, minimize=False) is C
             True
 
         The following test that the range for `c` in the code
@@ -815,11 +821,7 @@ def mu_line(r, i, c):
                         if c >= 0 else dim*(zero,)
                         for c in kernel), tuple())))
 
-        if minimize:
-            return result.minimized()
-        else:
-            return result
-
+        return result
 
     def backward_differences(self, **kwds):
         r"""
@@ -828,12 +830,14 @@ def backward_differences(self, **kwds):
 
         INPUT:
 
-        - ``minimize`` -- (default: ``True``) a boolean. If set, then
-          :meth:`minimized` is called after the operation.
+        - ``minimize`` -- (default: ``None``) a boolean or ``None``.
+          If ``True``, then :meth:`minimized` is called after the operation,
+          if ``False``, then not. If this argument is ``None``, then
+          the default specified by the parent's ``minimize_results`` is used.
 
         OUTPUT:
 
-        A :class:`kRegularSequence`.
+        A :class:`kRegularSequence`
 
         .. NOTE::
 
@@ -860,20 +864,21 @@ def backward_differences(self, **kwds):
         """
         return self.subsequence(1, {0: 1, -1: -1}, **kwds)
 
-
     def forward_differences(self, **kwds):
         r"""
         Return the sequence of forward differences of this
         `k`-regular sequence.
 
         INPUT:
 
-        - ``minimize`` -- (default: ``True``) a boolean. If set, then
-          :meth:`minimized` is called after the operation.
+        - ``minimize`` -- (default: ``None``) a boolean or ``None``.
+          If ``True``, then :meth:`minimized` is called after the operation,
+          if ``False``, then not. If this argument is ``None``, then
+          the default specified by the parent's ``minimize_results`` is used.
 
         OUTPUT:
 
-        A :class:`kRegularSequence`.
+        A :class:`kRegularSequence`
 
         EXAMPLES::
 
@@ -896,8 +901,8 @@ def forward_differences(self, **kwds):
         """
         return self.subsequence(1, {1: 1, 0: -1}, **kwds)
 
-
-    def partial_sums(self, include_n=False, minimize=True):
+    @minimize_result
+    def partial_sums(self, include_n=False):
         r"""
         Return the sequence of partial sums of this
         `k`-regular sequence. That is, the `n`th entry of the result
@@ -909,12 +914,14 @@ def partial_sums(self, include_n=False, minimize=True):
           the `n`th entry of the result is the sum of the entries up
           to index `n` (included).
 
-        - ``minimize`` -- (default: ``True``) a boolean. If set, then
-          :meth:`minimized` is called after the operation.
+        - ``minimize`` -- (default: ``None``) a boolean or ``None``.
+          If ``True``, then :meth:`minimized` is called after the operation,
+          if ``False``, then not. If this argument is ``None``, then
+          the default specified by the parent's ``minimize_results`` is used.
 
         OUTPUT:
 
-        A :class:`kRegularSequence`.
+        A :class:`kRegularSequence`
 
         EXAMPLES::
 
@@ -1025,10 +1032,7 @@ def partial_sums(self, include_n=False, minimize=True):
                    (dim*(0,) if include_n else tuple(-self.left))),
             vector(2*tuple(self.right)))
 
-        if minimize:
-            return result.minimized()
-        else:
-            return result
+        return result
 
 
 def _pickle_kRegularSequenceSpace(k, coefficients, category):
@@ -1277,21 +1281,21 @@ def guess(self, f, n_max=100, max_dimension=10, sequence=None):
         INPUT:
 
         - ``f`` -- a function (callable) which determines the sequence.
-          It takes nonnegative integers as an input.
+          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.
+          terms
 
         - ``max_dimension`` -- (default: ``10``) a positive integer specifying
-          the maxium dimension which is tried when guessing the sequence.
+          the maxium dimension which is tried when guessing the sequence
 
         - ``sequence`` -- (default: ``None``) a `k`-regular sequence used
-          for bootstrapping this guessing.
+          for bootstrapping this guessing
 
         OUTPUT:
 
-        A :class:`kRegularSequence`.
+        A :class:`kRegularSequence`
 
         EXAMPLES: