implement the inclusion NCSym -> WQSym

src/sage/combinat/ncsym/bases.py

@@ -603,6 +603,62 @@ def to_symmetric_function(self):
             m = self.parent().realization_of().monomial()
             return m(self).to_symmetric_function()
 
+        def to_wqsym(self):
+            r"""
+            Return the image of ``self`` under the canonical
+            inclusion map `NCSym \to WQSym`.
+
+            The canonical inclusion map `NCSym \to WQSym` is
+            an injective homomorphism of algebras. It sends a
+            basis element `\mathbf{m}_A` of `NCSym` to the sum of
+            basis elements `\mathbf{M}_P` of `WQSym`, where `P`
+            ranges over all ordered set partitions that become
+            `A` when the ordering is forgotten.
+            This map is denoted by `\theta` in [BZ05]_ (17).
+
+            .. SEEALSO::
+
+                :class:`WordQuasisymmetricFunctions` for a
+                definition of `WQSym`.
+
+            EXAMPLES::
+
+                sage: NCSym = SymmetricFunctionsNonCommutingVariables(QQ)
+                sage: e = NCSym.e()
+                sage: h = NCSym.h()
+                sage: p = NCSym.p()
+                sage: cp = NCSym.cp()
+                sage: x = NCSym.x()
+                sage: m = NCSym.m()
+                sage: m[[1,3],[2]].to_wqsym()
+                M[{2}, {1, 3}] + M[{1, 3}, {2}]
+                sage: x[[1,3],[2]].to_wqsym()
+                -M[{1}, {3}, {2}] - M[{2}, {1}, {3}] - M[{1, 2}, {3}]
+                 - M[{2, 3}, {1}] - M[{1}, {2}, {3}] - M[{3}, {2}, {1}]
+                 - M[{3}, {1}, {2}] - M[{3}, {1, 2}] - M[{2}, {3}, {1}]
+                 - M[{1}, {2, 3}]
+                sage: (4*p[[1,3],[2]]-p[[1]]).to_wqsym()
+                4*M[{1, 2, 3}] + 4*M[{2}, {1, 3}] + 4*M[{1, 3}, {2}] - M[{1}]
+            """
+            parent = self.parent()
+            NCSym = parent.realization_of()
+            R = parent.base_ring()
+            one = R.one()
+            m = NCSym.monomial()
+            from sage.combinat.chas.wqsym import WordQuasisymmetricFunctions
+            from sage.combinat.set_partition_ordered import OrderedSetPartition
+            M = WordQuasisymmetricFunctions(R).M()
+            from itertools import permutations
+            def to_wqsym_on_m_basis(A):
+                # Return the image of `\mathbf{m}_A` under the inclusion
+                # map `NCSym \to WQSym`.
+                l = len(A)
+                return M.sum_of_terms([(OrderedSetPartition([A[u[i]] for i in range(l)]), 1)
+                                         for u in permutations(range(l))],
+                                      distinct=True)
+            return M.sum(coeff * to_wqsym_on_m_basis(A)
+                         for A, coeff in m(self))
+
         def internal_coproduct(self):
             """
             Return the internal coproduct of ``self``.

src/sage/combinat/ncsym/ncsym.py

@@ -162,20 +162,23 @@ class SymmetricFunctionsNonCommutingVariables(UniqueRepresentation, Parent):
     indexed by set partitions.
 
     Let `A = \{A_1, A_2, \ldots, A_r\}` be a set partition of the integers
-    `\{ 1, 2, \ldots, k \}`.  A monomial basis element indexed by `A`
-    represents the sum of monomials `x_{i_1} x_{i_2} \cdots x_{i_k}` where
-    `i_c = i_d` if and only if `c` and `d` are in the same part `A_i` for some `i`.
+    `[k] := \{ 1, 2, \ldots, k \}`.  This partition `A` determines an
+    equivalence relation `~_A` on `[k]`, which has `c ~_A d` if and
+    only if `c` and `d` are in the same part `A_j` of `A`.
+    The monomial basis element `\mathbf{m}_A` indexed by `A` is the sum of
+    monomials `x_{i_1} x_{i_2} \cdots x_{i_k}` such that `i_c = i_d` if
+    and only if `c ~_A d`.
 
     The `k`-th graded component of the ring of symmetric functions in
     non-commutative variables has its dimension equal to the number of
-    set partitions of `k`. (If we work, instead, with finitely many --
+    set partitions of `[k]`. (If we work, instead, with finitely many --
     say, `n` -- variables, then its dimension is equal to the number of
-    set partitions of `k` where the number of parts is at most `n`.)
+    set partitions of `[k]` where the number of parts is at most `n`.)
 
     .. NOTE::
 
-        All set partitions are considered standard, a set partition of `[n]`
-        for some `n`, unless otherwise stated.
+        All set partitions are considered standard (i.e., set partitions
+        of `[n]` for some `n`) unless otherwise stated.
 
     REFERENCES:
 
@@ -537,7 +540,7 @@ def product_on_basis(self, A, B):
             and `A | B` is the
             :meth:`SetPartition.pipe` operation.
             Equivalently we can describe all `C` as matchings between the
-            partitions of `A` and `B` where if `a \in A` is matched
+            parts of `A` and `B` where if `a \in A` is matched
             with `b \in B`, we take `a \cup b` instead of `a` and `b` in `C`.
 
             INPUT: