passagemath-combinat 10.6.42__cp314-cp314t-win_amd64.whl

sage/combinat/shuffle.py

@@ -0,0 +1,830 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+Shuffle product of iterables
+
+The shuffle product of two sequences of lengths `m` and `n` is a
+sum over the `\binom{m+n}{n}` ways of interleaving the two sequences.
+
+That could be defined inductively by:
+
+.. MATH::
+
+    (a_n)_{n \geqslant 0} \Cup (b_m)_{m \geqslant 0} =
+    a_0 \cdot \left((a_n)_{n \geqslant 1} \Cup (b_m)_{m \geqslant 0}\right)
+    + b_0 \cdot \left((a_n)_{n \geqslant 0} \Cup (b_m)_{m \geqslant 1}\right)
+
+with `(a_n)` and `(b_m)` two non-empty sequences and if one of them is empty
+then the product is equals to the other.
+
+The shuffle product has been introduced by S. Eilenberg and S. Mac Lane in
+1953 [EilLan53]_.
+
+EXAMPLES::
+
+    sage: from sage.combinat.shuffle import ShuffleProduct
+    sage: list(ShuffleProduct([1,2], ["a", "b", "c"]))
+    [[1, 2, 'a', 'b', 'c'],
+     ['a', 1, 2, 'b', 'c'],
+     [1, 'a', 2, 'b', 'c'],
+     ['a', 'b', 1, 2, 'c'],
+     ['a', 1, 'b', 2, 'c'],
+     [1, 'a', 'b', 2, 'c'],
+     ['a', 'b', 'c', 1, 2],
+     ['a', 'b', 1, 'c', 2],
+     ['a', 1, 'b', 'c', 2],
+     [1, 'a', 'b', 'c', 2]]
+
+References:
+
+.. [EilLan53] On the groups `H(\pi, n)`, I,
+    Samuel Eilenberg and
+    Saunders Mac Lane,
+    1953.
+
+Author:
+
+- Jean-Baptiste Priez
+"""
+# ****************************************************************************
+#       Copyright (C) 2014 Jean-Baptiste Priez <jbp@kerios.fr>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from collections.abc import Iterable
+import itertools
+import operator
+
+from sage.categories.finite_enumerated_sets import FiniteEnumeratedSets
+from sage.combinat.integer_vector import IntegerVectors
+from sage.combinat.words.abstract_word import Word_class
+from sage.rings.integer import Integer
+from sage.structure.parent import Parent
+
+
+# TODO: Think about Parent/Element for this and the category
+# sage.categories.finite_enumerated_sets.FiniteEnumeratedSets
+
+class ShuffleProduct_abstract(Parent):
+    """
+    Abstract base class for shuffle products.
+    """
+
+    def __init__(self, l1, l2, element_constructor=None):
+        """
+        Initialize ``self``.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: SP = ShuffleProduct([1,2],[4,5,7,8,9])
+            sage: TestSuite(SP).run(skip='_test_an_element')
+        """
+        self._l1 = l1
+        self._l2 = l2
+        if element_constructor is None:
+            self._element_constructor_ = self._constructor_
+        else:
+            self._element_constructor_ = element_constructor
+        Parent.__init__(self, category=FiniteEnumeratedSets())
+
+    def _constructor_(self, x):
+        """
+        This is used by default to produce elements when iterating.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: S = ShuffleProduct([1,2,3],[4,5])
+            sage: S._constructor_((1,2,3))
+            [1, 2, 3]
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: S = ShuffleProduct_overlapping(w,u)
+            sage: S._constructor_((1,2,3))
+            [1, 2, 3]
+
+            sage: from sage.combinat.shuffle import SetShuffleProduct
+            sage: S = SetShuffleProduct([[1,2],[3,4]], [[1,4]])
+            sage: S._constructor_((1,2,3))
+            [1, 2, 3]
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: S = ShuffleProduct_overlapping_r(w,u,1)
+            sage: S._constructor_((1,2,3))
+            [1, 2, 3]
+        """
+        return list(x)
+
+    def __eq__(self, other):
+        """
+        Test for equality.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: SP = ShuffleProduct([1,2],[4,5,7,8,9])
+            sage: loads(dumps(SP)) == SP
+            True
+            sage: SP == ShuffleProduct([1,2],[4,5,7])
+            False
+        """
+        if not isinstance(other, type(self)):
+            return False
+        return self._l1 == other._l1 and self._l2 == other._l2
+
+    def __ne__(self, other):
+        """
+        Test for unequality.
+
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: A = ShuffleProduct_overlapping_r(w,u,1)
+            sage: B = ShuffleProduct_overlapping_r(u,w,2)
+            sage: A != A
+            False
+            sage: A != B
+            True
+        """
+        return not (self == other)
+
+    def __contains__(self, x):
+        """
+        Check containment.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: SP = ShuffleProduct([1,2],[4,5,7])
+            sage: [1,4,5,2,7] in SP
+            True
+            sage: (1,4,5,2,7) in SP
+            False
+            sage: [2,1,4,5,7] in SP
+            False
+        """
+        return x in self.list()
+
+
+class SetShuffleProduct(ShuffleProduct_abstract):
+    """
+    The union of all possible shuffle products of two sets of iterables.
+
+    EXAMPLES::
+
+        sage: from sage.combinat.shuffle import SetShuffleProduct
+        sage: sorted(SetShuffleProduct({(1,), (2,3)}, {(4,5), (6,)}))
+        [[1, 4, 5],
+         [1, 6],
+         [2, 3, 4, 5],
+         [2, 3, 6],
+         [2, 4, 3, 5],
+         [2, 4, 5, 3],
+         [2, 6, 3],
+         [4, 1, 5],
+         [4, 2, 3, 5],
+         [4, 2, 5, 3],
+         [4, 5, 1],
+         [4, 5, 2, 3],
+         [6, 1],
+         [6, 2, 3]]
+    """
+
+    def __init__(self, l1, l2, element_constructor=None):
+        """
+        Construct the set of all possible shuffle products of two sets of iterables.
+
+        INPUT:
+
+        - ``l1``, ``l2`` -- iterable: the sets to shuffle
+
+        - ``element_constructor`` -- constructor for the returned elements
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import SetShuffleProduct
+            sage: X = SetShuffleProduct({(1,2,3), (2,3,4)}, {(5,)})
+            sage: X   # random
+            Shuffle set product of: [(2, 3, 4), (1, 2, 3)] and [(5,)]
+            sage: TestSuite(X).run(skip='_test_an_element')
+
+            sage: list(SetShuffleProduct({(1,2,3), (2,3,4)}, {(5,)}))   # random
+            [[2, 3, 4, 5], [2, 5, 3, 4], [5, 2, 3, 4], [2, 3, 5, 4],
+             [1, 2, 3, 5], [1, 5, 2, 3], [5, 1, 2, 3], [1, 2, 5, 3]]
+        """
+        assert isinstance(l1, Iterable) and isinstance(l2, Iterable)
+        assert all(isinstance(elem, Iterable) for elem in l1)
+        assert all(isinstance(elem, Iterable) for elem in l2)
+
+        if element_constructor is None:
+            try:
+                e = next(iter(l1))
+                try:
+                    element_constructor = e.parent()._element_constructor_
+                except AttributeError:
+                    pass
+            except StopIteration:
+                pass
+        ShuffleProduct_abstract.__init__(self, list(l1), list(l2), element_constructor)
+
+    def _repr_(self):
+        """
+        TESTS::
+
+            sage: from sage.combinat.shuffle import SetShuffleProduct
+            sage: SetShuffleProduct([[1,2],[3,4]], [[1,4]])
+            Shuffle set product of: [[1, 2], [3, 4]] and [[1, 4]]
+            sage: SetShuffleProduct([()], [[1,4]])
+            Shuffle set product of: [()] and [[1, 4]]
+        """
+        return "Shuffle set product of: %s and %s" % (self._element_constructor_(self._l1),
+                                                      self._element_constructor_(self._l2))
+
+    def _ascii_art_(self):
+        r"""
+        TESTS::
+
+            sage: from sage.combinat.shuffle import SetShuffleProduct
+            sage: ascii_art(SetShuffleProduct([[BinaryTree()], [BinaryTree([]), BinaryTree([[],[]])]],                  # needs sage.graphs
+            ....: [[1,4]]))
+            Set shuffle product of:
+            [       [ o,   o   ] ]
+            [       [     / \  ] ]
+            [ [  ], [    o   o ] ] and [ [ 1, 4 ] ]
+        """
+        from sage.typeset.ascii_art import ascii_art
+        return (ascii_art("Set shuffle product of:") *
+                (ascii_art(self._l1) + ascii_art(" and ") +
+                 ascii_art(self._l2)))
+
+    def __iter__(self):
+        """
+        TESTS::
+
+            sage: from sage.combinat.shuffle import SetShuffleProduct
+            sage: list(SetShuffleProduct([[],[]], [[]]))
+            [[], []]
+            sage: list(SetShuffleProduct([[1,2],[3]], [[4]]))
+            [[1, 2, 4], [4, 1, 2], [1, 4, 2], [3, 4], [4, 3]]
+            sage: list(SetShuffleProduct([[1,2],[3,4]], [[1,4]], element_constructor=set))
+            [{1, 2, 4},
+             {1, 2, 4},
+             {1, 2, 4},
+             {1, 2, 4},
+             {1, 2, 4},
+             {1, 2, 4},
+             {1, 3, 4},
+             {1, 3, 4},
+             {1, 3, 4},
+             {1, 3, 4},
+             {1, 3, 4},
+             {1, 3, 4}]
+        """
+        return itertools.chain.from_iterable(
+            ShuffleProduct(*pair,
+                           element_constructor=self._element_constructor_)
+            for pair in itertools.product(self._l1, self._l2))
+
+    def cardinality(self):
+        """
+        The cardinality is defined by the sum of the cardinality of all shuffles.
+        That means by a sum of binomials.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import SetShuffleProduct
+            sage: SetShuffleProduct([[1,2],[3,4]], [[1,4]], element_constructor=set).cardinality()
+            12
+        """
+        def comp_binom(el1, el2):
+            ll1 = Integer(len(el1))
+            ll2 = Integer(len(el2))
+            return (ll1 + ll2).binomial(ll2)
+
+        return sum(comp_binom(el1, el2)
+                   for (el1, el2) in itertools.product(self._l1, self._l2))
+
+
+class ShuffleProduct(ShuffleProduct_abstract):
+    """
+    Shuffle product of two iterables.
+
+    EXAMPLES::
+
+        sage: from sage.combinat.shuffle import ShuffleProduct
+        sage: list(ShuffleProduct("abc", "de", element_constructor="".join))
+        ['abcde',
+         'adbce',
+         'dabce',
+         'abdce',
+         'adebc',
+         'daebc',
+         'deabc',
+         'adbec',
+         'dabec',
+         'abdec']
+        sage: list(ShuffleProduct("", "de", element_constructor="".join))
+        ['de']
+    """
+
+    def __init__(self, l1, l2, element_constructor=None):
+        """
+        Construct the shuffle product of two iterable.
+
+        INPUT:
+
+        - ``l1``, ``l2`` -- iterable: iterables to shuffle
+
+        - ``element_constructor`` -- constructor for the returned elements
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: SP = ShuffleProduct([1,2,3],[4,5])
+            sage: SP
+            Shuffle product of: [1, 2, 3] and [4, 5]
+            sage: TestSuite(SP).run(skip='_test_an_element')
+
+            sage: list(ShuffleProduct(Word("aa"), Word("bbb"), Word))
+            [word: aabbb, word: baabb, word: ababb, word: bbaab, word: babab, word: abbab,
+             word: bbbaa, word: bbaba, word: babba, word: abbba]
+        """
+        assert isinstance(l1, Iterable) and isinstance(l2, Iterable)
+
+        if element_constructor is None:
+            try:
+                element_constructor = l1.parent()._element_constructor_
+            except AttributeError:
+                pass
+        ShuffleProduct_abstract.__init__(self, list(l1), list(l2), element_constructor)
+
+    def _repr_(self):
+        """
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: ShuffleProduct([1,2,3],[4,5])
+            Shuffle product of: [1, 2, 3] and [4, 5]
+            sage: B = BinaryTree                                                        # needs sage.graphs
+            sage: ShuffleProduct([B(), B([[],[]])], [])                                 # needs sage.graphs
+            Shuffle product of: [., [[., .], [., .]]] and []
+        """
+        return "Shuffle product of: %s and %s" % (self._l1, self._l2)
+
+    def _ascii_art_(self):
+        r"""
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: ascii_art(ShuffleProduct([1,2,3],[4,5]))
+            Shuffle product of:
+            [ 1, 2, 3 ] and [ 4, 5 ]
+            sage: B = BinaryTree                                                        # needs sage.graphs
+            sage: ascii_art(ShuffleProduct([B([]), B([[],[]])],                         # needs sage.graphs
+            ....:   [B([[[],[]],[[],None]])]))
+            Shuffle product of:
+                             [     __o__   ]
+                             [    /     \  ]
+            [ o,   o   ]     [   o       o ]
+            [     / \  ]     [  / \     /  ]
+            [    o   o ] and [ o   o   o   ]
+        """
+        from sage.typeset.ascii_art import ascii_art
+        return ascii_art("Shuffle product of:") * \
+            (ascii_art(self._l1) + ascii_art(" and ") +
+             ascii_art(self._l2))
+
+    def __iter__(self):
+        r"""
+        Efficient iteration from a gray code on binary words in `B(n,k)`.
+
+        (with `B(n,k)` the number of binary words of size `n` with `k` one.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: list(ShuffleProduct([1,2,3],[4,5]))
+            [[1, 2, 3, 4, 5], [1, 4, 2, 3, 5], [4, 1, 2, 3, 5], [1, 2, 4, 3, 5], [1, 4, 5, 2, 3],
+             [4, 1, 5, 2, 3], [4, 5, 1, 2, 3], [1, 4, 2, 5, 3], [4, 1, 2, 5, 3], [1, 2, 4, 5, 3]]
+            sage: B = BinaryTree                                                        # needs sage.graphs
+            sage: ascii_art(list(ShuffleProduct([B([]), B([[],[]])],                    # needs sage.graphs
+            ....:   [B([[[],[]],[[],None]])])))
+            [ [ o,   o  ,     __o__   ]  [     __o__  , o,   o   ]
+            [ [     / \      /     \  ]  [    /     \       / \  ]
+            [ [    o   o    o       o ]  [   o       o     o   o ]
+            [ [            / \     /  ]  [  / \     /            ]
+            [ [           o   o   o   ], [ o   o   o             ],
+            <BLANKLINE>
+             [ o,     __o__  ,   o   ] ]
+             [       /     \    / \  ] ]
+             [      o       o  o   o ] ]
+             [     / \     /         ] ]
+             [    o   o   o          ] ]
+        """
+
+        # -------------- Gray code --------------
+        def swap(i, j):
+            l[i - 1], l[j - 1] = l[j - 1], l[i - 1]
+
+        def gen(n, k):
+            if 0 < k < n:
+                for _ in gen(n - 1, k):
+                    yield
+
+                if k == 1:
+                    swap(n, n - 1)
+                else:
+                    swap(n, k - 1)
+                yield
+
+                for _ in neg(n - 1, k - 1):
+                    yield
+
+        def neg(n, k):
+            if 0 < k < n:
+                for _ in gen(n - 1, k - 1):
+                    yield
+
+                if k == 1:
+                    swap(n, n - 1)
+                else:
+                    swap(n, k - 1)
+                yield
+
+                for _ in neg(n - 1, k):
+                    yield
+
+        ####################################
+
+        m = len(self._l1)
+        n = len(self._l2)
+        mn = m + n
+        l = [0] * m + [1] * n  # [0, 0 ... m times, 1, 1, 1 ... n times]
+
+        EC = self._element_constructor_
+        yield EC(self._l1 + self._l2)
+
+        for _ in gen(mn, m):
+            l1 = iter(self._l1)
+            l2 = iter(self._l2)
+            yield EC([next(l2) if l[k] else next(l1) for k in range(mn)])
+
+    def __contains__(self, iterable):
+        """
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: sh = ShuffleProduct([1,2,3],[4,5])
+            sage: list(range(1,6)) in sh
+            True
+            sage: list(range(1,7)) in sh
+            False
+            sage: [3,4,5,1,2] in sh
+            False
+            sage: [1,4,2,5,3] in sh
+            True
+            sage: [1,4,2,2,5,3] in sh
+            False
+        """
+        if not isinstance(iterable, type(self._element_constructor_([]))):
+            return False
+
+        l1 = self._l1
+        l2 = self._l2
+        len_l1 = len(l1)
+        len_l2 = len(l2)
+        i_l1 = i_l2 = 0
+        iterable = list(iterable)
+
+        for i, el in enumerate(iterable):
+            if l1[i_l1] == el:
+                i_l1 += 1
+            elif l2[i_l2] == el:
+                i_l2 += 1
+            else:
+                return False
+            if i_l1 == len_l1:
+                return iterable[i + 1:] == l2[i_l2:]
+            if i_l2 == len_l2:
+                return iterable[i + 1:] == l1[i_l1:]
+        return i_l1 + 1 == len_l1 and i_l2 + 1 == len_l2
+
+    def cardinality(self):
+        r"""
+        Return the number of shuffles of `l_1` and `l_2`, respectively of
+        lengths `m` and `n`, which is `\binom{m+n}{n}`.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct
+            sage: ShuffleProduct([3,1,2], [4,2,1,3]).cardinality()
+            35
+            sage: ShuffleProduct([3,1,2,5,6,4], [4,2,1,3]).cardinality() == binomial(10,4)
+            True
+        """
+        ll1 = Integer(len(self._l1))
+        ll2 = Integer(len(self._l2))
+        return (ll1 + ll2).binomial(ll1)
+
+
+class ShuffleProduct_overlapping_r(ShuffleProduct_abstract):
+    """
+    The overlapping shuffle product of the two words ``w1`` and ``w2``
+    with precisely ``r`` overlaps.
+
+    See :class:`ShuffleProduct_overlapping` for a definition.
+
+    EXAMPLES::
+
+        sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+        sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+        sage: S = ShuffleProduct_overlapping_r(w,u,1)
+        sage: list(S)
+        [word: 11,9,1,
+         word: 2,18,1,
+         word: 11,1,9,
+         word: 2,9,10,
+         word: 939,
+         word: 9,2,10]
+    """
+
+    def __init__(self, w1, w2, r, element_constructor=None, add=operator.add):
+        """
+        Initialize ``self``.
+
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: S = ShuffleProduct_overlapping_r(w,u,1)
+            sage: TestSuite(S).run(skip='_test_an_element')
+        """
+        self.r = r
+        self.add = add
+
+        if element_constructor is None:
+            # Special case for words since their parent has a __call__ but
+            #   not an _element_constructor_
+            if isinstance(w1, Word_class):
+                element_constructor = w1.parent()
+            else:
+                try:
+                    element_constructor = w1.parent()._element_constructor_
+                except AttributeError:
+                    pass
+        ShuffleProduct_abstract.__init__(self, w1, w2, element_constructor)
+
+    def _repr_(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: ShuffleProduct_overlapping_r(w,u,1).__repr__()
+            'Overlapping shuffle product of word: 29 and word: 91 with 1 overlaps'
+        """
+        return "Overlapping shuffle product of %s and %s with %s overlaps" % (repr(self._l1), repr(self._l2), self.r)
+
+    def __eq__(self, other):
+        """
+        Check equality.
+
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: A = ShuffleProduct_overlapping_r(w,u,1)
+            sage: B = ShuffleProduct_overlapping_r(u,w,2)
+            sage: A == A
+            True
+            sage: A == B
+            False
+        """
+        return ShuffleProduct_abstract.__eq__(self, other) and self.r == other.r
+
+    def __iter__(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping_r
+            sage: w, u = Word([1,2]), Word([3,4])
+            sage: ShuffleProduct_overlapping_r(w,u,1).list()
+            [word: 424, word: 154, word: 442, word: 136, word: 352, word: 316]
+            sage: w, u = map(Words(range(1,7)), [[1,2], [3,4]])
+            sage: W = Words(range(1,7))
+            sage: w, u = W([1,2]), W([3,4])
+            sage: ShuffleProduct_overlapping_r(w, u, 1).list() #indirect doctest
+            [word: 424, word: 154, word: 442, word: 136, word: 352, word: 316]
+
+            sage: I, J = Composition([2, 2]), Composition([1, 1])
+            sage: S = ShuffleProduct_overlapping_r(I, J, 1)
+            sage: S.list()
+            [[3, 2, 1], [2, 3, 1], [3, 1, 2], [2, 1, 3], [1, 3, 2], [1, 2, 3]]
+
+        TESTS:
+
+        We need to be explicitly more generic about the resulting parent
+        when shuffling two compositions `I` and `J` (:issue:`15131`)::
+
+            sage: I, J = Compositions(4)([2, 2]), Composition([1, 1])
+            sage: S = ShuffleProduct_overlapping_r(I, J, 1, Compositions())
+            sage: S.list()
+            [[3, 2, 1], [2, 3, 1], [3, 1, 2], [2, 1, 3], [1, 3, 2], [1, 2, 3]]
+        """
+        EC = self._element_constructor_
+
+        m = len(self._l1)
+        n = len(self._l2)
+        r = self.r
+        add = self.add
+
+        wc1, wc2 = self._l1, self._l2
+
+        blank = [None] * (m + n - r)
+        for iv in IntegerVectors(m, m + n - r, max_part=1):
+            w = blank[:]
+            filled_places = []
+            unfilled_places = []
+            # Fill in w1 into the iv slots
+            i = 0
+            for j in range(len(iv)):
+                if iv[j] == 1:
+                    w[j] = wc1[i]
+                    i += 1
+                    filled_places.append(j)
+                else:
+                    unfilled_places.append(j)
+
+            # Choose r of these filled places
+            for subset in itertools.combinations(filled_places, r):
+                places_to_fill = sorted(unfilled_places + list(subset))
+
+                # Fill in w2 into the places
+                i = 0
+                res = w[:]
+                for j in places_to_fill:
+                    if res[j] is not None:
+                        res[j] = add(res[j], wc2[i])
+                    else:
+                        res[j] = wc2[i]
+                    i += 1
+
+                yield EC(res)
+
+
+class ShuffleProduct_overlapping(ShuffleProduct_abstract):
+    r"""
+    The overlapping shuffle product of the two words ``w1`` and
+    ``w2``.
+
+    If `u` and `v` are two words whose letters belong to an
+    additive monoid or to another kind of alphabet on which addition
+    is well-defined, then the *overlapping shuffle product* of
+    `u` and `v` is a certain multiset of words defined as follows:
+    Let `a` and `b` be the lengths of `u` and `v`, respectively.
+    Let `A` be the set `\{(0, 1), (0, 2), \cdots, (0, a)\}`, and
+    let `B` be the set `\{(1, 1), (1, 2), \cdots, (1, b)\}`.
+    Notice that the sets `A` and `B` are disjoint. We can make
+    `A` and `B` into posets by setting `(k, i) \leq (k, j)` for
+    all `k \in \{0, 1\}` and `i \leq j`. Then, `A \cup B` becomes
+    a poset by disjoint union (we don't set `(0, i) \leq (1, i)`).
+    Let `p` be the map from `A \cup B` to the set of all letters
+    which sends every `(0, i)` to the `i`-th letter of `u`, and
+    every `(1, j)` to the `j`-th letter of `v`. For every
+    nonnegative integer `c` and every surjective map
+    `f : A \cup B \to \{ 1, 2, \cdots, c \}` for which both
+    restrictions `f \mid_A` and `f \mid_B` are strictly increasing,
+    let `w(f)` be the length-`c` word such that for every
+    `1 \leq k \leq c`, the `k`-th letter of `w(f)` equals
+    `\sum_{j \in f^{-1}(k)} p(j)` (this sum always has either
+    one or two addends). The overlapping shuffle product of `u`
+    and `v` is then the multiset of all `w(f)` with `c` ranging
+    over all nonnegative integers and `f` ranging
+    over the surjective maps
+    `f : A \cup B \to \{ 1, 2, \cdots, c \}` for which both
+    restrictions `f \mid_A` and `f \mid_B` are strictly increasing.
+
+    If one restricts `c` to a particular fixed nonnegative
+    integer, then the multiset is instead called the *overlapping
+    shuffle product with precisely `a + b - c` overlaps*. This is
+    nonempty only if `\max \{a, b\} \leq c \leq a + b`.
+
+    If `c = a + b`, then the overlapping shuffle product with
+    precisely `a + b - c` overlaps is plainly the shuffle product
+    (:class:`ShuffleProduct_w1w2`).
+
+    INPUT:
+
+    - ``w1``, ``w2`` -- iterables
+    - ``element_constructor`` -- (default: the parent of ``w1``)
+      the function used to construct the output
+    - ``add`` -- (default: ``+``) the addition function
+
+    EXAMPLES::
+
+        sage: from sage.combinat.shuffle import ShuffleProduct_overlapping
+        sage: w, u = [[2, 9], [9, 1]]
+        sage: S = ShuffleProduct_overlapping(w, u)
+        sage: sorted(S)
+        [[2, 9, 1, 9],
+         [2, 9, 9, 1],
+         [2, 9, 9, 1],
+         [2, 9, 10],
+         [2, 18, 1],
+         [9, 1, 2, 9],
+         [9, 2, 1, 9],
+         [9, 2, 9, 1],
+         [9, 2, 10],
+         [9, 3, 9],
+         [11, 1, 9],
+         [11, 9, 1],
+         [11, 10]]
+        sage: A = [{1,2}, {3,4}]
+        sage: B = [{2,3}, {4,5,6}]
+        sage: S = ShuffleProduct_overlapping(A, B, add=lambda X,Y: X.union(Y))
+        sage: list(S)
+        [[{1, 2}, {3, 4}, {2, 3}, {4, 5, 6}],
+         [{1, 2}, {2, 3}, {3, 4}, {4, 5, 6}],
+         [{1, 2}, {2, 3}, {4, 5, 6}, {3, 4}],
+         [{2, 3}, {1, 2}, {3, 4}, {4, 5, 6}],
+         [{2, 3}, {1, 2}, {4, 5, 6}, {3, 4}],
+         [{2, 3}, {4, 5, 6}, {1, 2}, {3, 4}],
+         [{1, 2, 3}, {3, 4}, {4, 5, 6}],
+         [{1, 2}, {2, 3, 4}, {4, 5, 6}],
+         [{1, 2, 3}, {4, 5, 6}, {3, 4}],
+         [{1, 2}, {2, 3}, {3, 4, 5, 6}],
+         [{2, 3}, {1, 2, 4, 5, 6}, {3, 4}],
+         [{2, 3}, {1, 2}, {3, 4, 5, 6}],
+         [{1, 2, 3}, {3, 4, 5, 6}]]
+    """
+
+    def __init__(self, w1, w2, element_constructor=None, add=operator.add):
+        """
+        Initialize ``self``.
+
+        TESTS::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: S = ShuffleProduct_overlapping(w,u)
+            sage: TestSuite(S).run(skip='_test_an_element')
+        """
+        self._add = add
+
+        if element_constructor is None:
+            # Special case for words since their parent has a __call__ but
+            #   not an _element_constructor_
+            if isinstance(w1, Word_class):
+                element_constructor = w1.parent()
+            else:
+                try:
+                    element_constructor = self._l1.parent()._element_constructor_
+                except AttributeError:
+                    pass
+        ShuffleProduct_abstract.__init__(self, w1, w2, element_constructor)
+
+    def _repr_(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping
+            sage: w, u = map(Words(range(20)), [[2, 9], [9, 1]])
+            sage: ShuffleProduct_overlapping(w,u).__repr__()
+            'Overlapping shuffle product of word: 29 and word: 91'
+        """
+        return "Overlapping shuffle product of %s and %s" % (repr(self._l1),
+                                                             repr(self._l2))
+
+    def __iter__(self):
+        """
+        EXAMPLES::
+
+            sage: from sage.combinat.shuffle import ShuffleProduct_overlapping
+            sage: w, u = map(Words(range(10)), [[0,1],[2,3]])
+            sage: S = ShuffleProduct_overlapping(w,u)
+            sage: S.list()
+            [word: 0123, word: 0213, word: 0231, word: 2013, word: 2031,
+             word: 2301, word: 213, word: 033, word: 231, word: 024,
+             word: 231, word: 204, word: 24]
+
+            sage: w, u = map(Words(range(1,10)), [[1,2],[3,4]])
+            sage: S = ShuffleProduct_overlapping(w,u)
+            sage: S.list()
+            [word: 1234, word: 1324, word: 1342, word: 3124, word: 3142,
+             word: 3412, word: 424, word: 154, word: 442, word: 136,
+             word: 352, word: 316, word: 46]
+        """
+        m = len(self._l1)
+        n = len(self._l2)
+        for r in range(min(m, n) + 1):
+            yield from ShuffleProduct_overlapping_r(self._l1, self._l2, r,
+                                                    self._element_constructor_,
+                                                    add=self._add)