Noncommutative symmetric functions - Combinatorics

Skip to content
Back to top
View this page
Edit this page

# Noncommutative symmetric functions

class sage.combinat.ncsf_qsym.ncsf.NonCommutativeSymmetricFunctions(R)

  Bases: `UniqueRepresentation`, `Parent`

  The abstract algebra of non-commutative symmetric functions.

  We construct the abstract algebra of non-commutative symmetric functions over the rational numbers:

  Sage

      sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
      sage: NCSF
      Non-Commutative Symmetric Functions over the Rational Field
      sage: S = NCSF.complete()
      sage: R = NCSF.ribbon()
      sage: S[2,1]*R[1,2]
      S[2, 1, 1, 2] - S[2, 1, 3]

  Python

      >>> from sage.all import *
      >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
      >>> NCSF
      Non-Commutative Symmetric Functions over the Rational Field
      >>> S = NCSF.complete()
      >>> R = NCSF.ribbon()
      >>> S[Integer(2),Integer(1)]*R[Integer(1),Integer(2)]
      S[2, 1, 1, 2] - S[2, 1, 3]

  NCSF is the unique free (non-commutative!) graded connected algebra with one generator in each degree:

  Sage

      sage: NCSF.category()
      Join of Category of Hopf algebras over Rational Field
          and Category of graded algebras over Rational Field
          and Category of monoids with realizations
          and Category of graded coalgebras over Rational Field
          and Category of coalgebras over Rational Field with realizations
          and Category of cocommutative coalgebras over Rational Field

      sage: [S[i].degree() for i in range(10)]
      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

  [Python]

      >>> from sage.all import *
      >>> NCSF.category()
      Join of Category of Hopf algebras over Rational Field
          and Category of graded algebras over Rational Field
          and Category of monoids with realizations
          and Category of graded coalgebras over Rational Field
          and Category of coalgebras over Rational Field with realizations
          and Category of cocommutative coalgebras over Rational Field

      >>> [S[i].degree() for i in range(Integer(10))]
      [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

  We use the Sage standard renaming idiom to get shorter outputs:

  Sage

      sage: NCSF.rename('NCSF')
      sage: NCSF
      NCSF

  Python

      >>> from sage.all import *
      >>> NCSF.rename('NCSF')
      >>> NCSF
      NCSF

  NCSF has many representations as a concrete algebra. Each of them has a distinguished basis, and its elements are expanded in this basis. Here is the \(\Psi\) (`Psi`) representation:

  Sage

      sage: Psi = NCSF.Psi()
      sage: Psi
      NCSF in the Psi basis

  [Python]

      >>> from sage.all import *
      >>> Psi = NCSF.Psi()
      >>> Psi
      NCSF in the Psi basis

  Elements of `Psi` are linear combinations of basis elements indexed by compositions:

  Sage

      sage: Psi.an_element()
      2*Psi[] + 2*Psi[1] + 3*Psi[1, 1]

  Python

      >>> from sage.all import *
      >>> Psi.an_element()
      2*Psi[] + 2*Psi[1] + 3*Psi[1, 1]

  The basis itself is accessible through:

  Sage

      sage: Psi.basis()
      Lazy family (Term map from Compositions of nonnegative integers...
      sage: Psi.basis().keys()
      Compositions of nonnegative integers

  [Python]

      >>> from sage.all import *
      >>> Psi.basis()
      Lazy family (Term map from Compositions of nonnegative integers...
      >>> Psi.basis().keys()
      Compositions of nonnegative integers

  To construct an element one can therefore do:

  Sage

      sage: Psi.basis()[Composition([2,1,3])]
      Psi[2, 1, 3]

  Python

      >>> from sage.all import *
      >>> Psi.basis()[Composition([Integer(2),Integer(1),Integer(3)])]
      Psi[2, 1, 3]

  As this is rather cumbersome, the following abuses of notation are allowed:

  Sage

      sage: Psi[Composition([2, 1, 3])]
      Psi[2, 1, 3]
      sage: Psi[[2, 1, 3]]
      Psi[2, 1, 3]
      sage: Psi[2, 1, 3]
      Psi[2, 1, 3]

  [Python]

      >>> from sage.all import *
      >>> Psi[Composition([Integer(2), Integer(1), Integer(3)])]
      Psi[2, 1, 3]
      >>> Psi[[Integer(2), Integer(1), Integer(3)]]
      Psi[2, 1, 3]
      >>> Psi[Integer(2), Integer(1), Integer(3)]
      Psi[2, 1, 3]

  or even:

  Sage

      sage: Psi[(i for i in [2, 1, 3])]
      Psi[2, 1, 3]

  Python

      >>> from sage.all import *
      >>> Psi[(i for i in [Integer(2), Integer(1), Integer(3)])]
      Psi[2, 1, 3]

  Unfortunately, due to a limitation in Python syntax, one cannot use:

  Sage

      sage: Psi[]       # not implemented

  [Python]

      >>> from sage.all import *
      >>> Psi[]       # not implemented

  Instead, you can use:

  Sage

      sage: Psi[[]]
      Psi[]

  Python

      >>> from sage.all import *
      >>> Psi[[]]
      Psi[]

  Now, we can construct linear combinations of basis elements:

  Sage

      sage: Psi[2,1,3] + 2 * (Psi[4] + Psi[2,1])
      2*Psi[2, 1] + Psi[2, 1, 3] + 2*Psi[4]

  [Python]

      >>> from sage.all import *
      >>> Psi[Integer(2),Integer(1),Integer(3)] + Integer(2) * (Psi[Integer(4)] + Psi[Integer(2),Integer(1)])
      2*Psi[2, 1] + Psi[2, 1, 3] + 2*Psi[4]

  Algebra structure

  To start with, `Psi` is a graded algebra, the grading being induced by the size of compositions. The one is the basis element indexed by the empty composition:

  Sage

      sage: Psi.one()
      Psi[]
      sage: S.one()
      S[]
      sage: R.one()
      R[]

  Python

      >>> from sage.all import *
      >>> Psi.one()
      Psi[]
      >>> S.one()
      S[]
      >>> R.one()
      R[]

  As we have seen above, the `Psi` basis is multiplicative; that is multiplication is induced by linearity from the concatenation of compositions:

  Sage

      sage: Psi[1,3] * Psi[2,1]
      Psi[1, 3, 2, 1]
      sage: (Psi.one() + 2 * Psi[1,3]) * Psi[2, 4]
      2*Psi[1, 3, 2, 4] + Psi[2, 4]

  [Python]

      >>> from sage.all import *
      >>> Psi[Integer(1),Integer(3)] * Psi[Integer(2),Integer(1)]
      Psi[1, 3, 2, 1]
      >>> (Psi.one() + Integer(2) * Psi[Integer(1),Integer(3)]) * Psi[Integer(2), Integer(4)]
      2*Psi[1, 3, 2, 4] + Psi[2, 4]

  Hopf algebra structure

  `Psi` is further endowed with a coalgebra structure. The coproduct is an algebra morphism, and therefore determined by its values on the generators; those are primitive:

  Sage

      sage: Psi[1].coproduct()
      Psi[] # Psi[1] + Psi[1] # Psi[]
      sage: Psi[2].coproduct()
      Psi[] # Psi[2] + Psi[2] # Psi[]

  Python

      >>> from sage.all import *
      >>> Psi[Integer(1)].coproduct()
      Psi[] # Psi[1] + Psi[1] # Psi[]
      >>> Psi[Integer(2)].coproduct()
      Psi[] # Psi[2] + Psi[2] # Psi[]

  The coproduct, being cocommutative on the generators, is cocommutative everywhere:

  Sage

      sage: Psi[1,2].coproduct()
      Psi[] # Psi[1, 2] + Psi[1] # Psi[2] + Psi[1, 2] # Psi[] + Psi[2] # Psi[1]

  [Python]

      >>> from sage.all import *
      >>> Psi[Integer(1),Integer(2)].coproduct()
      Psi[] # Psi[1, 2] + Psi[1] # Psi[2] + Psi[1, 2] # Psi[] + Psi[2] # Psi[1]

  The algebra and coalgebra structures on `Psi` combine to form a bialgebra structure, which cooperates with the grading to form a connected graded bialgebra. Thus, as any connected graded bialgebra, `Psi` is a Hopf algebra. Over `QQ` (or any other \(\QQ\)-algebra), this Hopf algebra `Psi` is isomorphic to the universal enveloping algebra of its space of primitive elements. Here, the primitives form a countably generated free Lie algebra, so `Psi` is isomorphic to the tensor algebra on a countably infinite dimensional vector space.

  The antipode is an anti-algebra morphism; in the `Psi` basis, it sends the generators to their opposites and changes their sign if they are of odd degree:

  Sage

      sage: Psi[3].antipode()
      -Psi[3]
      sage: Psi[1,3,2].antipode()
      -Psi[2, 3, 1]
      sage: Psi[1,3,2].coproduct().apply_multilinear_morphism(lambda be,ga: Psi(be)*Psi(ga).antipode())
      0

  Python

      >>> from sage.all import *
      >>> Psi[Integer(3)].antipode()
      -Psi[3]
      >>> Psi[Integer(1),Integer(3),Integer(2)].antipode()
      -Psi[2, 3, 1]
      >>> Psi[Integer(1),Integer(3),Integer(2)].coproduct().apply_multilinear_morphism(lambda be,ga: Psi(be)*Psi(ga).antipode())
      0

  The counit is defined by sending all elements of positive degree to zero:

  Sage

      sage: S[3].degree(), S[3,1,2].degree(), S.one().degree()
      (3, 6, 0)
      sage: S[3].counit()
      0
      sage: S[3,1,2].counit()
      0
      sage: S.one().counit()
      1
      sage: (S[3] - 2*S[3,1,2] + 7).counit()
      7
      sage: (R[3] - 2*R[3,1,2] + 7).counit()
      7

  [Python]

      >>> from sage.all import *
      >>> S[Integer(3)].degree(), S[Integer(3),Integer(1),Integer(2)].degree(), S.one().degree()
      (3, 6, 0)
      >>> S[Integer(3)].counit()
      0
      >>> S[Integer(3),Integer(1),Integer(2)].counit()
      0
      >>> S.one().counit()
      1
      >>> (S[Integer(3)] - Integer(2)*S[Integer(3),Integer(1),Integer(2)] + Integer(7)).counit()
      7
      >>> (R[Integer(3)] - Integer(2)*R[Integer(3),Integer(1),Integer(2)] + Integer(7)).counit()
      7

  It is possible to change the prefix used to display the basis elements using the method `print_options()`. Say that for instance one wanted to display the `Complete` basis as having a prefix `H` instead of the default `S`:

  Sage

      sage: H = NCSF.complete()
      sage: H.an_element()
      2*S[] + 2*S[1] + 3*S[1, 1]
      sage: H.print_options(prefix='H')
      sage: H.an_element()
      2*H[] + 2*H[1] + 3*H[1, 1]
      sage: H.print_options(prefix='S') #restore to 'S'

  Python

      >>> from sage.all import *
      >>> H = NCSF.complete()
      >>> H.an_element()
      2*S[] + 2*S[1] + 3*S[1, 1]
      >>> H.print_options(prefix='H')
      >>> H.an_element()
      2*H[] + 2*H[1] + 3*H[1, 1]
      >>> H.print_options(prefix='S') #restore to 'S'

  Concrete representations

  NCSF admits the concrete realizations defined in [NCSF1]:

  Sage

      sage: Phi        = NCSF.Phi()
      sage: Psi        = NCSF.Psi()
      sage: ribbon     = NCSF.ribbon()
      sage: complete   = NCSF.complete()
      sage: elementary = NCSF.elementary()

  [Python]

      >>> from sage.all import *
      >>> Phi        = NCSF.Phi()
      >>> Psi        = NCSF.Psi()
      >>> ribbon     = NCSF.ribbon()
      >>> complete   = NCSF.complete()
      >>> elementary = NCSF.elementary()

  To change from one basis to another, one simply does:

  Sage

      sage: Phi(Psi[1])
      Phi[1]
      sage: Phi(Psi[3])
      -1/4*Phi[1, 2] + 1/4*Phi[2, 1] + Phi[3]

  Python

      >>> from sage.all import *
      >>> Phi(Psi[Integer(1)])
      Phi[1]
      >>> Phi(Psi[Integer(3)])
      -1/4*Phi[1, 2] + 1/4*Phi[2, 1] + Phi[3]

  In general, one can mix up different bases in computations:

  Sage

      sage: Phi[1] * Psi[1]
      Phi[1, 1]

  [Python]

      >>> from sage.all import *
      >>> Phi[Integer(1)] * Psi[Integer(1)]
      Phi[1, 1]

  Some of the changes of basis are easy to guess:

  Sage

      sage: ribbon(complete[1,3,2])
      R[1, 3, 2] + R[1, 5] + R[4, 2] + R[6]

  Python

      >>> from sage.all import *
      >>> ribbon(complete[Integer(1),Integer(3),Integer(2)])
      R[1, 3, 2] + R[1, 5] + R[4, 2] + R[6]

  This is the sum of all fatter compositions. Using the usual Möbius function for the boolean lattice, the inverse change of basis is given by the alternating sum of all fatter compositions:

  Sage

      sage: complete(ribbon[1,3,2])
      S[1, 3, 2] - S[1, 5] - S[4, 2] + S[6]

  [Python]

      >>> from sage.all import *
      >>> complete(ribbon[Integer(1),Integer(3),Integer(2)])
      S[1, 3, 2] - S[1, 5] - S[4, 2] + S[6]

  The analogue of the elementary basis is the sum over all finer compositions than the ‘complement’ of the composition in the ribbon basis:

  Sage

      sage: Composition([1,3,2]).complement()
      [2, 1, 2, 1]
      sage: ribbon(elementary([1,3,2]))
      R[1, 1, 1, 1, 1, 1] + R[1, 1, 1, 2, 1] + R[2, 1, 1, 1, 1] + R[2, 1, 2, 1]

  Python

      >>> from sage.all import *
      >>> Composition([Integer(1),Integer(3),Integer(2)]).complement()
      [2, 1, 2, 1]
      >>> ribbon(elementary([Integer(1),Integer(3),Integer(2)]))
      R[1, 1, 1, 1, 1, 1] + R[1, 1, 1, 2, 1] + R[2, 1, 1, 1, 1] + R[2, 1, 2, 1]

  By Möbius inversion on the composition poset, the ribbon basis element corresponding to a composition \(I\) is then the alternating sum over all compositions fatter than the complement composition of \(I\) in the elementary basis:

  Sage

      sage: elementary(ribbon[2,1,2,1])
      L[1, 3, 2] - L[1, 5] - L[4, 2] + L[6]

  [Python]

      >>> from sage.all import *
      >>> elementary(ribbon[Integer(2),Integer(1),Integer(2),Integer(1)])
      L[1, 3, 2] - L[1, 5] - L[4, 2] + L[6]

  The \(\Phi\) (`Phi`) and \(\Psi\) bases are computed by changing to and from the `Complete` basis. The expansion of \(\Psi\) basis is given in Proposition 4.5 of [NCSF1] by the formulae

  \[S^I = \sum_{J \geq I} \frac{1}{\pi_u(J,I)} \Psi^J\]

  and

  \[\Psi^I = \sum_{J \geq I} (-1)^{\ell(J)-\ell(I)} lp(J,I) S^J\]

  where the coefficients \(\pi_u(J,I)\) and \(lp(J,I)\) are coefficients in the methods `coeff_pi()` and `coeff_lp()` respectively. For example:

  Sage

      sage: Psi(complete[3])
      1/6*Psi[1, 1, 1] + 1/3*Psi[1, 2] + 1/6*Psi[2, 1] + 1/3*Psi[3]
      sage: complete(Psi[3])
      S[1, 1, 1] - 2*S[1, 2] - S[2, 1] + 3*S[3]

  Python

      >>> from sage.all import *
      >>> Psi(complete[Integer(3)])
      1/6*Psi[1, 1, 1] + 1/3*Psi[1, 2] + 1/6*Psi[2, 1] + 1/3*Psi[3]
      >>> complete(Psi[Integer(3)])
      S[1, 1, 1] - 2*S[1, 2] - S[2, 1] + 3*S[3]

  The `Phi` basis is another analogue of the power sum basis from the algebra of symmetric functions and the expansion in the Complete basis is given in Proposition 4.9 of [NCSF1] by the formulae

  \[S^I = \sum_{J \geq I} \frac{1}{sp(J,I)} \Phi^J\]

  and

  \[\Phi^I = \sum_{J \geq I} (-1)^{\ell(J)-\ell(I)} \frac{\prod_i I_i}{\ell(J,I)} S^J\]

  where the coefficients \(sp(J,I)\) and \(\ell(J,I)\) are coefficients in the methods `coeff_sp()` and `coeff_ell()` respectively. For example:

  Sage

      sage: Phi(complete[3])
      1/6*Phi[1, 1, 1] + 1/4*Phi[1, 2] + 1/4*Phi[2, 1] + 1/3*Phi[3]
      sage: complete(Phi[3])
      S[1, 1, 1] - 3/2*S[1, 2] - 3/2*S[2, 1] + 3*S[3]

  [Python]

      >>> from sage.all import *
      >>> Phi(complete[Integer(3)])
      1/6*Phi[1, 1, 1] + 1/4*Phi[1, 2] + 1/4*Phi[2, 1] + 1/3*Phi[3]
      >>> complete(Phi[Integer(3)])
      S[1, 1, 1] - 3/2*S[1, 2] - 3/2*S[2, 1] + 3*S[3]

  Here is how to fetch the conversion morphisms:

  Sage

      sage: f = complete.coerce_map_from(elementary); f
      Generic morphism:
        From: NCSF in the Elementary basis
        To:   NCSF in the Complete basis
      sage: g = elementary.coerce_map_from(complete); g
      Generic morphism:
        From: NCSF in the Complete basis
        To:   NCSF in the Elementary basis
      sage: f.category()
      Category of homsets of unital magmas and right modules over Rational Field and
        left modules over Rational Field
      sage: f(elementary[1,2,2])
      S[1, 1, 1, 1, 1] - S[1, 1, 1, 2] - S[1, 2, 1, 1] + S[1, 2, 2]
      sage: g(complete[1,2,2])
      L[1, 1, 1, 1, 1] - L[1, 1, 1, 2] - L[1, 2, 1, 1] + L[1, 2, 2]
      sage: h = f*g; h
      Composite map:
        From: NCSF in the Complete basis
        To:   NCSF in the Complete basis
        Defn:   Generic morphism:
                From: NCSF in the Complete basis
                To:   NCSF in the Elementary basis
              then
                Generic morphism:
                From: NCSF in the Elementary basis
                To:   NCSF in the Complete basis
      sage: h(complete[1,3,2])
      S[1, 3, 2]

  Python

      >>> from sage.all import *
      >>> f = complete.coerce_map_from(elementary); f
      Generic morphism:
        From: NCSF in the Elementary basis
        To:   NCSF in the Complete basis
      >>> g = elementary.coerce_map_from(complete); g
      Generic morphism:
        From: NCSF in the Complete basis
        To:   NCSF in the Elementary basis
      >>> f.category()
      Category of homsets of unital magmas and right modules over Rational Field and
        left modules over Rational Field
      >>> f(elementary[Integer(1),Integer(2),Integer(2)])
      S[1, 1, 1, 1, 1] - S[1, 1, 1, 2] - S[1, 2, 1, 1] + S[1, 2, 2]
      >>> g(complete[Integer(1),Integer(2),Integer(2)])
      L[1, 1, 1, 1, 1] - L[1, 1, 1, 2] - L[1, 2, 1, 1] + L[1, 2, 2]
      >>> h = f*g; h
      Composite map:
        From: NCSF in the Complete basis
        To:   NCSF in the Complete basis
        Defn:   Generic morphism:
                From: NCSF in the Complete basis
                To:   NCSF in the Elementary basis
              then
                Generic morphism:
                From: NCSF in the Elementary basis
                To:   NCSF in the Complete basis
      >>> h(complete[Integer(1),Integer(3),Integer(2)])
      S[1, 3, 2]

  Additional concrete representations

  NCSF has some additional bases which appear in the literature:

  Sage

      sage: Monomial                 = NCSF.Monomial()
      sage: Immaculate               = NCSF.Immaculate()
      sage: dualQuasisymmetric_Schur = NCSF.dualQuasisymmetric_Schur()

  [Python]

      >>> from sage.all import *
      >>> Monomial                 = NCSF.Monomial()
      >>> Immaculate               = NCSF.Immaculate()
      >>> dualQuasisymmetric_Schur = NCSF.dualQuasisymmetric_Schur()

  The `Monomial` basis was introduced in [Tev2007] and the `Immaculate` basis was introduced in [BBSSZ2012]. The `Quasisymmetric_Schur` were defined in [QSCHUR] and the dual basis is implemented here as `dualQuasisymmetric_Schur`. Refer to the documentation for the use and definition of these bases.

  Todo

  - implement fundamental, forgotten, and simple (coming from the simple modules of HS_n) bases.

  We revert back to the original name from our custom short name NCSF:

  Sage

      sage: NCSF
      NCSF
      sage: NCSF.rename()
      sage: NCSF
      Non-Commutative Symmetric Functions over the Rational Field

  Python

      >>> from sage.all import *
      >>> NCSF
      NCSF
      >>> NCSF.rename()
      >>> NCSF
      Non-Commutative Symmetric Functions over the Rational Field

  class Bases(parent_with_realization)

    Bases: `Category_realization_of_parent`

    Category of bases of non-commutative symmetric functions.

    EXAMPLES:

    Sage

        sage: N = NonCommutativeSymmetricFunctions(QQ)
        sage: N.Bases()
        Category of bases of Non-Commutative Symmetric Functions over the Rational Field
        sage: R = N.Ribbon()
        sage: R in N.Bases()
        True

    Python

        >>> from sage.all import *
        >>> N = NonCommutativeSymmetricFunctions(QQ)
        >>> N.Bases()
        Category of bases of Non-Commutative Symmetric Functions over the Rational Field
        >>> R = N.Ribbon()
        >>> R in N.Bases()
        True

    class ElementMethods

      Bases: `object`

      bernstein_creation_operator(n)

        Return the image of `self` under the \(n\)-th Bernstein creation operator.

        Let \(n\) be an integer. The \(n\)-th Bernstein creation operator \(\mathbb{B}_n\) is defined as the endomorphism of the space \(NSym\) of noncommutative symmetric functions which sends every \(f\) to

        \[\sum_{i \geq 0} (-1)^i H_{n+i} F_{1^i}^\perp,\]

        where usual notations are in place (the letter \(H\) stands for the complete basis of \(NSym\), the letter \(F\) stands for the fundamental basis of the algebra \(QSym\) of quasisymmetric functions, and \(F_{1^i}^\perp\) means skewing (`skew_by()`) by \(F_{1^i}\)). Notice that \(F_{1^i}\) is nothing other than the elementary symmetric function \(e_i\).

        This has been introduced in [BBSSZ2012], section 3.1, in analogy to the Bernstein creation operators on the symmetric functions (`bernstein_creation_operator()`), and studied further in [BBSSZ2012], mainly in the context of immaculate functions (`Immaculate`). In fact, if \((\alpha_1, \alpha_2, \ldots, \alpha_m)\) is an \(m\)-tuple of integers, then

        \[\mathbb{B}_n I_{(\alpha_1, \alpha_2, \ldots, \alpha_m)} = I_{(n, \alpha_1, \alpha_2, \ldots, \alpha_m)},\]

        where \(I_{(\alpha_1, \alpha_2, \ldots, \alpha_m)}\) is the immaculate function associated to the \(m\)-tuple \((\alpha_1, \alpha_2, \ldots, \alpha_m)\) (see `immaculate_function()`).

        EXAMPLES:

        We get the immaculate functions by repeated application of Bernstein creation operators:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: I = NSym.I()
            sage: S = NSym.S()
            sage: def immaculate_by_bernstein(xs):
            ....:     # immaculate function corresponding to integer
            ....:     # tuple ``xs``, computed by iterated application
            ....:     # of Bernstein creation operators.
            ....:     res = S.one()
            ....:     for i in reversed(xs):
            ....:         res = res.bernstein_creation_operator(i)
            ....:     return res
            sage: import itertools
            sage: all( immaculate_by_bernstein(p) == I.immaculate_function(p)
            ....:      for p in itertools.product(range(-1, 3), repeat=3))
            True

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> I = NSym.I()
            >>> S = NSym.S()
            >>> def immaculate_by_bernstein(xs):
            ...     # immaculate function corresponding to integer
            ...     # tuple ``xs``, computed by iterated application
            ...     # of Bernstein creation operators.
            ...     res = S.one()
            ...     for i in reversed(xs):
            ...         res = res.bernstein_creation_operator(i)
            ...     return res
            >>> import itertools
            >>> all( immaculate_by_bernstein(p) == I.immaculate_function(p)
            ...      for p in itertools.product(range(-Integer(1), Integer(3)), repeat=Integer(3)))
            True

        Some examples:

        Sage

            sage: S[3,2].bernstein_creation_operator(-2)
            S[2, 1]
            sage: S[3,2].bernstein_creation_operator(-1)
            S[1, 2, 1] - S[2, 2] - S[3, 1]
            sage: S[3,2].bernstein_creation_operator(0)
            -S[1, 2, 2] - S[1, 3, 1] + S[2, 2, 1] + S[3, 2]
            sage: S[3,2].bernstein_creation_operator(1)
            S[1, 3, 2] - S[2, 2, 2] - S[2, 3, 1] + S[3, 2, 1]
            sage: S[3,2].bernstein_creation_operator(2)
            S[2, 3, 2] - S[3, 2, 2] - S[3, 3, 1] + S[4, 2, 1]

        [Python]

            >>> from sage.all import *
            >>> S[Integer(3),Integer(2)].bernstein_creation_operator(-Integer(2))
            S[2, 1]
            >>> S[Integer(3),Integer(2)].bernstein_creation_operator(-Integer(1))
            S[1, 2, 1] - S[2, 2] - S[3, 1]
            >>> S[Integer(3),Integer(2)].bernstein_creation_operator(Integer(0))
            -S[1, 2, 2] - S[1, 3, 1] + S[2, 2, 1] + S[3, 2]
            >>> S[Integer(3),Integer(2)].bernstein_creation_operator(Integer(1))
            S[1, 3, 2] - S[2, 2, 2] - S[2, 3, 1] + S[3, 2, 1]
            >>> S[Integer(3),Integer(2)].bernstein_creation_operator(Integer(2))
            S[2, 3, 2] - S[3, 2, 2] - S[3, 3, 1] + S[4, 2, 1]

      chi()

        alias of `to_symmetric_function()`.

      expand(n, alphabet='x')

        Expand the noncommutative symmetric function into an element of a free algebra in \(n\) indeterminates of an alphabet, which by default is `'x'`.

        INPUT:

        - `n` – nonnegative integer; the number of variables in the expansion

        - `alphabet` – (default: `'x'`) the alphabet in which `self` is to be expanded

        OUTPUT: an expansion of `self` into the \(n\) variables specified by `alphabet`

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: S = NSym.S()
            sage: S[3].expand(3)
            x0^3 + x0^2*x1 + x0^2*x2 + x0*x1^2 + x0*x1*x2
             + x0*x2^2 + x1^3 + x1^2*x2 + x1*x2^2 + x2^3
            sage: L = NSym.L()
            sage: L[3].expand(3)
            x2*x1*x0
            sage: L[2].expand(3)
            x1*x0 + x2*x0 + x2*x1
            sage: L[3].expand(4)
            x2*x1*x0 + x3*x1*x0 + x3*x2*x0 + x3*x2*x1
            sage: Psi = NSym.Psi()
            sage: Psi[2, 1].expand(3)
            x0^3 + x0^2*x1 + x0^2*x2 + x0*x1*x0 + x0*x1^2 + x0*x1*x2
             + x0*x2*x0 + x0*x2*x1 + x0*x2^2 - x1*x0^2 - x1*x0*x1
             - x1*x0*x2 + x1^2*x0 + x1^3 + x1^2*x2 + x1*x2*x0
             + x1*x2*x1 + x1*x2^2 - x2*x0^2 - x2*x0*x1 - x2*x0*x2
             - x2*x1*x0 - x2*x1^2 - x2*x1*x2 + x2^2*x0 + x2^2*x1 + x2^3

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> S = NSym.S()
            >>> S[Integer(3)].expand(Integer(3))
            x0^3 + x0^2*x1 + x0^2*x2 + x0*x1^2 + x0*x1*x2
             + x0*x2^2 + x1^3 + x1^2*x2 + x1*x2^2 + x2^3
            >>> L = NSym.L()
            >>> L[Integer(3)].expand(Integer(3))
            x2*x1*x0
            >>> L[Integer(2)].expand(Integer(3))
            x1*x0 + x2*x0 + x2*x1
            >>> L[Integer(3)].expand(Integer(4))
            x2*x1*x0 + x3*x1*x0 + x3*x2*x0 + x3*x2*x1
            >>> Psi = NSym.Psi()
            >>> Psi[Integer(2), Integer(1)].expand(Integer(3))
            x0^3 + x0^2*x1 + x0^2*x2 + x0*x1*x0 + x0*x1^2 + x0*x1*x2
             + x0*x2*x0 + x0*x2*x1 + x0*x2^2 - x1*x0^2 - x1*x0*x1
             - x1*x0*x2 + x1^2*x0 + x1^3 + x1^2*x2 + x1*x2*x0
             + x1*x2*x1 + x1*x2^2 - x2*x0^2 - x2*x0*x1 - x2*x0*x2
             - x2*x1*x0 - x2*x1^2 - x2*x1*x2 + x2^2*x0 + x2^2*x1 + x2^3

        One can use a different set of variables by adding an optional argument `alphabet=...`:

        Sage

            sage: L[3].expand(4, alphabet='y')
            y2*y1*y0 + y3*y1*y0 + y3*y2*y0 + y3*y2*y1

        [Python]

            >>> from sage.all import *
            >>> L[Integer(3)].expand(Integer(4), alphabet='y')
            y2*y1*y0 + y3*y1*y0 + y3*y2*y0 + y3*y2*y1

        Todo

        So far this is only implemented on the elementary basis, and everything else goes through coercion. Maybe it is worth shortcutting some of the other bases?

      left_padded_kronecker_product(x)

        Return the left-padded Kronecker product of `self` and `x` in the basis of `self`.

        The left-padded Kronecker product is a bilinear map mapping two non-commutative symmetric functions to another, not necessarily preserving degree. It can be defined as follows: Let \(*\) denote the internal product (`internal_product()`) on the space of non-commutative symmetric functions. For any composition \(I\), let \(S^I\) denote the complete homogeneous symmetric function indexed by \(I\). For any compositions \(\alpha\), \(\beta\), \(\gamma\), let \(g^{\gamma}_{\alpha, \beta}\) denote the coefficient of \(S^{\gamma}\) in the internal product \(S^{\alpha} * S^{\beta}\). For every composition \(I = (i_1, i_2, \ldots, i_k)\) and every integer \(n > \left\lvert I \right\rvert\), define the `n`-completion of `I` to be the composition \((n - \left\lvert I \right\rvert, i_1, i_2, \ldots, i_k)\); this \(n\)-completion is denoted by \(I[n]\). Then, for any compositions \(\alpha\) and \(\beta\) and every integer \(n > \left\lvert \alpha \right\rvert + \left\lvert\beta\right\rvert\), we can write the internal product \(S^{\alpha[n]} * S^{\beta[n]}\) in the form

        \[S^{\alpha[n]} * S^{\beta[n]} = \sum_{\gamma} g^{\gamma[n]}_{\alpha[n], \beta[n]} S^{\gamma[n]}\]

        with \(\gamma\) ranging over all compositions. The coefficients \(g^{\gamma[n]}_{\alpha[n], \beta[n]}\) are independent on \(n\). These coefficients \(g^{\gamma[n]}_{\alpha[n], \beta[n]}\) are denoted by \(\widetilde{g}^{\gamma}_{\alpha, \beta}\), and the non-commutative symmetric function

        \[\sum_{\gamma} \widetilde{g}^{\gamma}_{\alpha, \beta} S^{\gamma}\]

        is said to be the left-padded Kronecker product of \(S^{\alpha}\) and \(S^{\beta}\). By bilinearity, this extends to a definition of a left-padded Kronecker product of any two non-commutative symmetric functions.

        The left-padded Kronecker product on the non-commutative symmetric functions lifts the left-padded Kronecker product on the symmetric functions. More precisely: Let \(\pi\) denote the canonical projection (`to_symmetric_function()`) from the non-commutative symmetric functions to the symmetric functions. Then, any two non-commutative symmetric functions \(f\) and \(g\) satisfy

        \[\pi(f \overline{*} g) = \pi(f) \overline{*} \pi(g),\]

        where the \(\overline{*}\) on the left-hand side denotes the left-padded Kronecker product on the non-commutative symmetric functions, and the \(\overline{*}\) on the right-hand side denotes the left-padded Kronecker product on the symmetric functions.

        INPUT:

        - `x` – element of the ring of non-commutative symmetric functions over the same base ring as `self`

        OUTPUT:

        - the left-padded Kronecker product of `self` with `x` (an element of the ring of non-commutative symmetric functions in the same basis as `self`)

        AUTHORS:

        - Darij Grinberg (15 Mar 2014)

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: S = NSym.S()
            sage: S[2,1].left_padded_kronecker_product(S[3])
            S[1, 1, 1, 1] + S[1, 2, 1] + S[2, 1] + S[2, 1, 1, 1] + S[2, 2, 1] + S[3, 2, 1]
            sage: S[2,1].left_padded_kronecker_product(S[1])
            S[1, 1, 1] + S[1, 2, 1] + S[2, 1]
            sage: S[1].left_padded_kronecker_product(S[2,1])
            S[1, 1, 1] + S[2, 1] + S[2, 1, 1]
            sage: S[1,1].left_padded_kronecker_product(S[2])
            S[1, 1] + 2*S[1, 1, 1] + S[2, 1, 1]
            sage: S[1].left_padded_kronecker_product(S[1,2,1])
            S[1, 1, 1, 1] + S[1, 2, 1] + S[1, 2, 1, 1] + S[2, 1, 1]
            sage: S[2].left_padded_kronecker_product(S[3])
            S[1, 2] + S[2, 1, 1] + S[3, 2]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> S = NSym.S()
            >>> S[Integer(2),Integer(1)].left_padded_kronecker_product(S[Integer(3)])
            S[1, 1, 1, 1] + S[1, 2, 1] + S[2, 1] + S[2, 1, 1, 1] + S[2, 2, 1] + S[3, 2, 1]
            >>> S[Integer(2),Integer(1)].left_padded_kronecker_product(S[Integer(1)])
            S[1, 1, 1] + S[1, 2, 1] + S[2, 1]
            >>> S[Integer(1)].left_padded_kronecker_product(S[Integer(2),Integer(1)])
            S[1, 1, 1] + S[2, 1] + S[2, 1, 1]
            >>> S[Integer(1),Integer(1)].left_padded_kronecker_product(S[Integer(2)])
            S[1, 1] + 2*S[1, 1, 1] + S[2, 1, 1]
            >>> S[Integer(1)].left_padded_kronecker_product(S[Integer(1),Integer(2),Integer(1)])
            S[1, 1, 1, 1] + S[1, 2, 1] + S[1, 2, 1, 1] + S[2, 1, 1]
            >>> S[Integer(2)].left_padded_kronecker_product(S[Integer(3)])
            S[1, 2] + S[2, 1, 1] + S[3, 2]

        Taking the left-padded Kronecker product with \(1 = S^{\empty}\) is the identity map on the ring of non-commutative symmetric functions:

        Sage

            sage: all( S[Composition([])].left_padded_kronecker_product(S[lam])
            ....:      == S[lam].left_padded_kronecker_product(S[Composition([])])
            ....:      == S[lam] for i in range(4)
            ....:      for lam in Compositions(i) )
            True

        [Python]

            >>> from sage.all import *
            >>> all( S[Composition([])].left_padded_kronecker_product(S[lam])
            ...      == S[lam].left_padded_kronecker_product(S[Composition([])])
            ...      == S[lam] for i in range(Integer(4))
            ...      for lam in Compositions(i) )
            True

        Here is a rule for the left-padded Kronecker product of \(S_1\) (this is the same as \(S^{(1)}\)) with any complete homogeneous function: Let \(I\) be a composition. Then, the left-padded Kronecker product of \(S_1\) and \(S^I\) is \(\sum_K a_K S^K\), where the sum runs over all compositions \(K\), and the coefficient \(a_K\) is defined as the number of ways to obtain \(K\) from \(I\) by one of the following two operations:

        - Insert a \(1\) at the end of \(I\).

        - Subtract \(1\) from one of the entries of \(I\) (and remove the entry if it thus becomes \(0\)), and insert a \(1\) at the end of \(I\).

        We check this for compositions of size \(\leq 4\):

        Sage

            sage: def mults1(I):
            ....:     # Left left-padded Kronecker multiplication by S[1].
            ....:     res = S[I[:] + [1]]
            ....:     for k in range(len(I)):
            ....:         I2 = I[:]
            ....:         if I2[k] == 1:
            ....:             I2 = I2[:k] + I2[k+1:]
            ....:         else:
            ....:             I2[k] -= 1
            ....:         res += S[I2 + [1]]
            ....:     return res
            sage: all( mults1(I) == S[1].left_padded_kronecker_product(S[I])
            ....:      for i in range(5) for I in Compositions(i) )
            True

        Python

            >>> from sage.all import *
            >>> def mults1(I):
            ...     # Left left-padded Kronecker multiplication by S[1].
            ...     res = S[I[:] + [Integer(1)]]
            ...     for k in range(len(I)):
            ...         I2 = I[:]
            ...         if I2[k] == Integer(1):
            ...             I2 = I2[:k] + I2[k+Integer(1):]
            ...         else:
            ...             I2[k] -= Integer(1)
            ...         res += S[I2 + [Integer(1)]]
            ...     return res
            >>> all( mults1(I) == S[Integer(1)].left_padded_kronecker_product(S[I])
            ...      for i in range(Integer(5)) for I in Compositions(i) )
            True

        A similar rule can be made for the left-padded Kronecker product of any complete homogeneous function with \(S_1\): Let \(I\) be a composition. Then, the left-padded Kronecker product of \(S^I\) and \(S_1\) is \(\sum_K b_K S^K\), where the sum runs over all compositions \(K\), and the coefficient \(b_K\) is defined as the number of ways to obtain \(K\) from \(I\) by one of the following two operations:

        - Insert a \(1\) at the front of \(I\).

        - Subtract \(1\) from one of the entries of \(I\) (and remove the entry if it thus becomes \(0\)), and insert a \(1\) right after this entry.

        We check this for compositions of size \(\leq 4\):

        Sage

            sage: def mults2(I):
            ....:     # Left left-padded Kronecker multiplication by S[1].
            ....:     res = S[[1] + I[:]]
            ....:     for k in range(len(I)):
            ....:         I2 = I[:]
            ....:         i2k = I2[k]
            ....:         if i2k != 1:
            ....:             I2 = I2[:k] + [i2k-1, 1] + I2[k+1:]
            ....:         res += S[I2]
            ....:     return res
            sage: all( mults2(I) == S[I].left_padded_kronecker_product(S[1])
            ....:      for i in range(5) for I in Compositions(i) )
            True

        [Python]

            >>> from sage.all import *
            >>> def mults2(I):
            ...     # Left left-padded Kronecker multiplication by S[1].
            ...     res = S[[Integer(1)] + I[:]]
            ...     for k in range(len(I)):
            ...         I2 = I[:]
            ...         i2k = I2[k]
            ...         if i2k != Integer(1):
            ...             I2 = I2[:k] + [i2k-Integer(1), Integer(1)] + I2[k+Integer(1):]
            ...         res += S[I2]
            ...     return res
            >>> all( mults2(I) == S[I].left_padded_kronecker_product(S[Integer(1)])
            ...      for i in range(Integer(5)) for I in Compositions(i) )
            True

        Checking the \(\pi(f \overline{*} g) = \pi(f) \overline{*} \pi(g)\) equality:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: R = NSym.R()
            sage: def testpi(n):
            ....:     for I in Compositions(n):
            ....:         for J in Compositions(n):
            ....:             a = R[I].to_symmetric_function()
            ....:             b = R[J].to_symmetric_function()
            ....:             x = a.left_padded_kronecker_product(b)
            ....:             y = R[I].left_padded_kronecker_product(R[J])
            ....:             y = y.to_symmetric_function()
            ....:             if x != y:
            ....:                 return False
            ....:     return True
            sage: testpi(3)
            True

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> R = NSym.R()
            >>> def testpi(n):
            ...     for I in Compositions(n):
            ...         for J in Compositions(n):
            ...             a = R[I].to_symmetric_function()
            ...             b = R[J].to_symmetric_function()
            ...             x = a.left_padded_kronecker_product(b)
            ...             y = R[I].left_padded_kronecker_product(R[J])
            ...             y = y.to_symmetric_function()
            ...             if x != y:
            ...                 return False
            ...     return True
            >>> testpi(Integer(3))
            True

      omega_involution()

        Return the image of the noncommutative symmetric function `self` under the omega involution.

        The omega involution is defined as the algebra antihomomorphism \(NCSF \to NCSF\) which, for every positive integer \(n\), sends the \(n\)-th complete non-commutative symmetric function \(S_n\) to the \(n\)-th elementary non-commutative symmetric function \(\Lambda_n\). This omega involution is denoted by \(\omega\). It can be shown that every composition \(I\) satisfies

        \[\omega(S^I) = \Lambda^{I^r}, \quad \omega(\Lambda^I) = S^{I^r}, \quad \omega(R_I) = R_{I^t}, \quad \omega(\Phi^I) = (-1)^{|I|-\ell(I)} \Phi^{I^r}, \omega(\Psi^I) = (-1)^{|I|-\ell(I)} \Psi^{I^r},\]

        where \(I^r\) denotes the reversed composition of \(I\), and \(I^t\) denotes the conjugate composition of \(I\), and \(\ell(I)\) denotes the length of the composition \(I\), and standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(R\) for the ribbon basis, \(\Phi\) for that of the power-sums of the second kind, and \(\Psi\) for that of the power-sums of the first kind). More generally, if \(f\) is a homogeneous element of \(NCSF\) of degree \(n\), then

        \[\omega(f) = (-1)^n S(f),\]

        where \(S\) denotes the antipode of \(NCSF\).

        The omega involution \(\omega\) is an involution and a coalgebra automorphism of \(NCSF\). It is an automorphism of the graded vector space \(NCSF\). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(\omega(f)) = \omega(\pi(f))\) for every \(f \in NCSF\), where the \(\omega\) on the right hand side denotes the omega automorphism of \(Sym\).

        The omega involution on \(NCSF\) is adjoint to the omega involution on \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The omega involution has been denoted by \(\omega\) in [LMvW13], section 3.6. See [NCSF1], section 3.1 for the properties of this map.

        See also

        `omega involution of QSym`, `psi involution of NCSF`, `star involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: S = NSym.S()
            sage: L = NSym.L()
            sage: L(S[3,2].omega_involution())
            L[2, 3]
            sage: L(S[6,3].omega_involution())
            L[3, 6]
            sage: L(S[1,3].omega_involution())
            L[3, 1]
            sage: L((S[9,1] - S[8,2] + 2*S[6,4] - 3*S[3] + 4*S[[]]).omega_involution()) # long time
            4*L[] + L[1, 9] - L[2, 8] - 3*L[3] + 2*L[4, 6]
            sage: L((S[3,3] - 2*S[2]).omega_involution())
            -2*L[2] + L[3, 3]
            sage: L(S([4,2]).omega_involution())
            L[2, 4]
            sage: R = NSym.R()
            sage: R([4,2]).omega_involution()
            R[1, 2, 1, 1, 1]
            sage: R.zero().omega_involution()
            0
            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: Phi = NSym.Phi()
            sage: Phi([2,1]).omega_involution()
            -Phi[1, 2]
            sage: Psi = NSym.Psi()
            sage: Psi([2,1]).omega_involution()
            -Psi[1, 2]
            sage: Psi([3,1]).omega_involution()
            Psi[1, 3]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> S = NSym.S()
            >>> L = NSym.L()
            >>> L(S[Integer(3),Integer(2)].omega_involution())
            L[2, 3]
            >>> L(S[Integer(6),Integer(3)].omega_involution())
            L[3, 6]
            >>> L(S[Integer(1),Integer(3)].omega_involution())
            L[3, 1]
            >>> L((S[Integer(9),Integer(1)] - S[Integer(8),Integer(2)] + Integer(2)*S[Integer(6),Integer(4)] - Integer(3)*S[Integer(3)] + Integer(4)*S[[]]).omega_involution()) # long time
            4*L[] + L[1, 9] - L[2, 8] - 3*L[3] + 2*L[4, 6]
            >>> L((S[Integer(3),Integer(3)] - Integer(2)*S[Integer(2)]).omega_involution())
            -2*L[2] + L[3, 3]
            >>> L(S([Integer(4),Integer(2)]).omega_involution())
            L[2, 4]
            >>> R = NSym.R()
            >>> R([Integer(4),Integer(2)]).omega_involution()
            R[1, 2, 1, 1, 1]
            >>> R.zero().omega_involution()
            0
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> Phi = NSym.Phi()
            >>> Phi([Integer(2),Integer(1)]).omega_involution()
            -Phi[1, 2]
            >>> Psi = NSym.Psi()
            >>> Psi([Integer(2),Integer(1)]).omega_involution()
            -Psi[1, 2]
            >>> Psi([Integer(3),Integer(1)]).omega_involution()
            Psi[1, 3]

        Testing the \(\pi(\omega(f)) = \omega(\pi(f))\) relation noticed above:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: R = NSym.R()
            sage: all( R(I).omega_involution().to_symmetric_function()
            ....:      == R(I).to_symmetric_function().omega_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> R = NSym.R()
            >>> all( R(I).omega_involution().to_symmetric_function()
            ...      == R(I).to_symmetric_function().omega_involution()
            ...      for I in Compositions(Integer(4)) )
            True

        The omega involution on \(QSym\) is adjoint to the omega involution on \(NSym\) with respect to the duality pairing:

        Sage

            sage: QSym = QuasiSymmetricFunctions(QQ)
            sage: M = QSym.M()
            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: S = NSym.S()
            sage: all( all( M(I).omega_involution().duality_pairing(S(J))
            ....:           == M(I).duality_pairing(S(J).omega_involution())
            ....:           for I in Compositions(2) )
            ....:      for J in Compositions(3) )
            True

        Python

            >>> from sage.all import *
            >>> QSym = QuasiSymmetricFunctions(QQ)
            >>> M = QSym.M()
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> S = NSym.S()
            >>> all( all( M(I).omega_involution().duality_pairing(S(J))
            ...           == M(I).duality_pairing(S(J).omega_involution())
            ...           for I in Compositions(Integer(2)) )
            ...      for J in Compositions(Integer(3)) )
            True

      psi_involution()

        Return the image of the noncommutative symmetric function `self` under the involution \(\psi\).

        The involution \(\psi\) is defined as the linear map \(NCSF \to NCSF\) which, for every composition \(I\), sends the complete noncommutative symmetric function \(S^I\) to the elementary noncommutative symmetric function \(\Lambda^I\). It can be shown that every composition \(I\) satisfies

        \[\psi(R_I) = R_{I^c}, \quad \psi(S^I) = \Lambda^I, \quad \psi(\Lambda^I) = S^I, \quad \psi(\Phi^I) = (-1)^{|I| - \ell(I)} \Phi^I\]

        where \(I^c\) denotes the complement of the composition \(I\), and \(\ell(I)\) denotes the length of \(I\), and where standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(\Phi\) for the basis of the power sums of the second kind, and \(R\) for the ribbon basis). The map \(\psi\) is an involution and a graded Hopf algebra automorphism of \(NCSF\). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(\psi(f)) = \omega(\pi(f))\) for every \(f \in NCSF\), where the \(\omega\) on the right hand side denotes the omega automorphism of \(Sym\).

        The involution \(\psi\) of \(NCSF\) is adjoint to the involution \(\psi\) of \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The involution \(\psi\) has been denoted by \(\psi\) in [LMvW13], section 3.6.

        See also

        `psi involution of QSym`, `star involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: R = NSym.R()
            sage: R[3,2].psi_involution()
            R[1, 1, 2, 1]
            sage: R[6,3].psi_involution()
            R[1, 1, 1, 1, 1, 2, 1, 1]
            sage: (R[9,1] - R[8,2] + 2*R[2,4] - 3*R[3] + 4*R[[]]).psi_involution()
            4*R[] - 3*R[1, 1, 1] + R[1, 1, 1, 1, 1, 1, 1, 1, 2] - R[1, 1, 1, 1, 1, 1, 1, 2, 1] + 2*R[1, 2, 1, 1, 1]
            sage: (R[3,3] - 2*R[2]).psi_involution()
            -2*R[1, 1] + R[1, 1, 2, 1, 1]
            sage: R([2,1,1]).psi_involution()
            R[1, 3]
            sage: S = NSym.S()
            sage: S([2,1]).psi_involution()
            S[1, 1, 1] - S[2, 1]
            sage: S.zero().psi_involution()
            0
            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: Phi = NSym.Phi()
            sage: Phi([2,1]).psi_involution()
            -Phi[2, 1]
            sage: Phi([3,1]).psi_involution()
            Phi[3, 1]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> R = NSym.R()
            >>> R[Integer(3),Integer(2)].psi_involution()
            R[1, 1, 2, 1]
            >>> R[Integer(6),Integer(3)].psi_involution()
            R[1, 1, 1, 1, 1, 2, 1, 1]
            >>> (R[Integer(9),Integer(1)] - R[Integer(8),Integer(2)] + Integer(2)*R[Integer(2),Integer(4)] - Integer(3)*R[Integer(3)] + Integer(4)*R[[]]).psi_involution()
            4*R[] - 3*R[1, 1, 1] + R[1, 1, 1, 1, 1, 1, 1, 1, 2] - R[1, 1, 1, 1, 1, 1, 1, 2, 1] + 2*R[1, 2, 1, 1, 1]
            >>> (R[Integer(3),Integer(3)] - Integer(2)*R[Integer(2)]).psi_involution()
            -2*R[1, 1] + R[1, 1, 2, 1, 1]
            >>> R([Integer(2),Integer(1),Integer(1)]).psi_involution()
            R[1, 3]
            >>> S = NSym.S()
            >>> S([Integer(2),Integer(1)]).psi_involution()
            S[1, 1, 1] - S[2, 1]
            >>> S.zero().psi_involution()
            0
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> Phi = NSym.Phi()
            >>> Phi([Integer(2),Integer(1)]).psi_involution()
            -Phi[2, 1]
            >>> Phi([Integer(3),Integer(1)]).psi_involution()
            Phi[3, 1]

        The Psi basis doesn’t behave as nicely:

        Sage

            sage: Psi = NSym.Psi()
            sage: Psi([2,1]).psi_involution()
            -Psi[2, 1]
            sage: Psi([3,1]).psi_involution()
            1/2*Psi[1, 2, 1] - 1/2*Psi[2, 1, 1] + Psi[3, 1]

        [Python]

            >>> from sage.all import *
            >>> Psi = NSym.Psi()
            >>> Psi([Integer(2),Integer(1)]).psi_involution()
            -Psi[2, 1]
            >>> Psi([Integer(3),Integer(1)]).psi_involution()
            1/2*Psi[1, 2, 1] - 1/2*Psi[2, 1, 1] + Psi[3, 1]

        The involution \(\psi\) commutes with the antipode:

        Sage

            sage: all( R(I).psi_involution().antipode()
            ....:      == R(I).antipode().psi_involution()
            ....:      for I in Compositions(4) )
            True

        Python

            >>> from sage.all import *
            >>> all( R(I).psi_involution().antipode()
            ...      == R(I).antipode().psi_involution()
            ...      for I in Compositions(Integer(4)) )
            True

        Testing the \(\pi(\psi(f)) = \omega(\pi(f))\) relation noticed above:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: R = NSym.R()
            sage: all( R(I).psi_involution().to_symmetric_function()
            ....:      == R(I).to_symmetric_function().omega()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> R = NSym.R()
            >>> all( R(I).psi_involution().to_symmetric_function()
            ...      == R(I).to_symmetric_function().omega()
            ...      for I in Compositions(Integer(4)) )
            True

        The involution \(\psi\) of \(QSym\) is adjoint to the involution \(\psi\) of \(NSym\) with respect to the duality pairing:

        Sage

            sage: QSym = QuasiSymmetricFunctions(QQ)
            sage: M = QSym.M()
            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: S = NSym.S()
            sage: all( all( M(I).psi_involution().duality_pairing(S(J))
            ....:           == M(I).duality_pairing(S(J).psi_involution())
            ....:           for I in Compositions(2) )
            ....:      for J in Compositions(3) )
            True

        Python

            >>> from sage.all import *
            >>> QSym = QuasiSymmetricFunctions(QQ)
            >>> M = QSym.M()
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> S = NSym.S()
            >>> all( all( M(I).psi_involution().duality_pairing(S(J))
            ...           == M(I).duality_pairing(S(J).psi_involution())
            ...           for I in Compositions(Integer(2)) )
            ...      for J in Compositions(Integer(3)) )
            True

      star_involution()

        Return the image of the noncommutative symmetric function `self` under the star involution.

        The star involution is defined as the algebra antihomomorphism \(NCSF \to NCSF\) which, for every positive integer \(n\), sends the \(n\)-th complete non-commutative symmetric function \(S_n\) to \(S_n\). Denoting by \(f^{\ast}\) the image of an element \(f \in NCSF\) under this star involution, it can be shown that every composition \(I\) satisfies

        \[(S^I)^{\ast} = S^{I^r}, \quad (\Lambda^I)^{\ast} = \Lambda^{I^r}, \quad R_I^{\ast} = R_{I^r}, \quad (\Phi^I)^{\ast} = \Phi^{I^r},\]

        where \(I^r\) denotes the reversed composition of \(I\), and standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(R\) for the ribbon basis, and \(\Phi\) for that of the power-sums of the second kind). The star involution is an involution and a coalgebra automorphism of \(NCSF\). It is an automorphism of the graded vector space \(NCSF\). Under the canonical isomorphism between the \(n\)-th graded component of \(NCSF\) and the descent algebra of the symmetric group \(S_n\) (see `to_descent_algebra()`), the star involution (restricted to the \(n\)-th graded component) corresponds to the automorphism of the descent algebra given by \(x \mapsto \omega_n x \omega_n\), where \(\omega_n\) is the permutation \((n, n-1, \ldots, 1) \in S_n\) (written here in one-line notation). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(f^{\ast}) = \pi(f)\) for every \(f \in NCSF\).

        The star involution on \(NCSF\) is adjoint to the star involution on \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The star involution has been denoted by \(\rho\) in [LMvW13], section 3.6. See [NCSF2], section 2.3 for the properties of this map.

        See also

        `star involution of QSym`, `psi involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: S = NSym.S()
            sage: S[3,2].star_involution()
            S[2, 3]
            sage: S[6,3].star_involution()
            S[3, 6]
            sage: (S[9,1] - S[8,2] + 2*S[6,4] - 3*S[3] + 4*S[[]]).star_involution()
            4*S[] + S[1, 9] - S[2, 8] - 3*S[3] + 2*S[4, 6]
            sage: (S[3,3] - 2*S[2]).star_involution()
            -2*S[2] + S[3, 3]
            sage: S([4,2]).star_involution()
            S[2, 4]
            sage: R = NSym.R()
            sage: R([4,2]).star_involution()
            R[2, 4]
            sage: R.zero().star_involution()
            0
            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: Phi = NSym.Phi()
            sage: Phi([2,1]).star_involution()
            Phi[1, 2]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> S = NSym.S()
            >>> S[Integer(3),Integer(2)].star_involution()
            S[2, 3]
            >>> S[Integer(6),Integer(3)].star_involution()
            S[3, 6]
            >>> (S[Integer(9),Integer(1)] - S[Integer(8),Integer(2)] + Integer(2)*S[Integer(6),Integer(4)] - Integer(3)*S[Integer(3)] + Integer(4)*S[[]]).star_involution()
            4*S[] + S[1, 9] - S[2, 8] - 3*S[3] + 2*S[4, 6]
            >>> (S[Integer(3),Integer(3)] - Integer(2)*S[Integer(2)]).star_involution()
            -2*S[2] + S[3, 3]
            >>> S([Integer(4),Integer(2)]).star_involution()
            S[2, 4]
            >>> R = NSym.R()
            >>> R([Integer(4),Integer(2)]).star_involution()
            R[2, 4]
            >>> R.zero().star_involution()
            0
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> Phi = NSym.Phi()
            >>> Phi([Integer(2),Integer(1)]).star_involution()
            Phi[1, 2]

        The Psi basis doesn’t behave as nicely:

        Sage

            sage: Psi = NSym.Psi()
            sage: Psi([2,1]).star_involution()
            Psi[1, 2]
            sage: Psi([3,1]).star_involution()
            1/2*Psi[1, 1, 2] - 1/2*Psi[1, 2, 1] + Psi[1, 3]

        [Python]

            >>> from sage.all import *
            >>> Psi = NSym.Psi()
            >>> Psi([Integer(2),Integer(1)]).star_involution()
            Psi[1, 2]
            >>> Psi([Integer(3),Integer(1)]).star_involution()
            1/2*Psi[1, 1, 2] - 1/2*Psi[1, 2, 1] + Psi[1, 3]

        The star involution commutes with the antipode:

        Sage

            sage: all( R(I).star_involution().antipode()
            ....:      == R(I).antipode().star_involution()
            ....:      for I in Compositions(4) )
            True

        Python

            >>> from sage.all import *
            >>> all( R(I).star_involution().antipode()
            ...      == R(I).antipode().star_involution()
            ...      for I in Compositions(Integer(4)) )
            True

        Checking the relation with the descent algebra described above:

        Sage

            sage: def descent_test(n):
            ....:     DA = DescentAlgebra(QQ, n)
            ....:     NSym = NonCommutativeSymmetricFunctions(QQ)
            ....:     S = NSym.S()
            ....:     DAD = DA.D()
            ....:     w_n = DAD(set(range(1, n)))
            ....:     for I in Compositions(n):
            ....:         if not (S[I].star_involution()
            ....:                 == w_n * S[I].to_descent_algebra(n) * w_n):
            ....:             return False
            ....:         return True
            sage: all( descent_test(i) for i in range(4) )
            True
            sage: all( descent_test(i) for i in range(6) ) # long time
            True

        [Python]

            >>> from sage.all import *
            >>> def descent_test(n):
            ...     DA = DescentAlgebra(QQ, n)
            ...     NSym = NonCommutativeSymmetricFunctions(QQ)
            ...     S = NSym.S()
            ...     DAD = DA.D()
            ...     w_n = DAD(set(range(Integer(1), n)))
            ...     for I in Compositions(n):
            ...         if not (S[I].star_involution()
            ...                 == w_n * S[I].to_descent_algebra(n) * w_n):
            ...             return False
            ...         return True
            >>> all( descent_test(i) for i in range(Integer(4)) )
            True
            >>> all( descent_test(i) for i in range(Integer(6)) ) # long time
            True

        Testing the \(\pi(f^{\ast}) = \pi(f)\) relation noticed above:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: R = NSym.R()
            sage: all( R(I).star_involution().to_symmetric_function()
            ....:      == R(I).to_symmetric_function()
            ....:      for I in Compositions(4) )
            True

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> R = NSym.R()
            >>> all( R(I).star_involution().to_symmetric_function()
            ...      == R(I).to_symmetric_function()
            ...      for I in Compositions(Integer(4)) )
            True

        The star involution on \(QSym\) is adjoint to the star involution on \(NSym\) with respect to the duality pairing:

        Sage

            sage: QSym = QuasiSymmetricFunctions(QQ)
            sage: M = QSym.M()
            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: S = NSym.S()
            sage: all( all( M(I).star_involution().duality_pairing(S(J))
            ....:           == M(I).duality_pairing(S(J).star_involution())
            ....:           for I in Compositions(2) )
            ....:      for J in Compositions(3) )
            True

        [Python]

            >>> from sage.all import *
            >>> QSym = QuasiSymmetricFunctions(QQ)
            >>> M = QSym.M()
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> S = NSym.S()
            >>> all( all( M(I).star_involution().duality_pairing(S(J))
            ...           == M(I).duality_pairing(S(J).star_involution())
            ...           for I in Compositions(Integer(2)) )
            ...      for J in Compositions(Integer(3)) )
            True

      to_descent_algebra(n=None)

        Return the image of the `n`-th degree homogeneous component of `self` in the descent algebra of \(S_n\) over the same base ring as `self`.

        This is based upon the canonical isomorphism from the \(n\)-th degree homogeneous component of the algebra of noncommutative symmetric functions to the descent algebra of \(S_n\). This isomorphism maps the inner product of noncommutative symmetric functions either to the product in the descent algebra of \(S_n\) or to its opposite (depending on how the latter is defined).

        If `n` is not specified, it will be taken to be the highest homogeneous component of `self`.

        OUTPUT:

        - The image of the `n`-th homogeneous component of `self` under the isomorphism into the descent algebra of \(S_n\) over the same base ring as `self`.

        EXAMPLES:

        Sage

            sage: S = NonCommutativeSymmetricFunctions(ZZ).S()
            sage: S[2,1].to_descent_algebra(3)
            B[2, 1]
            sage: (S[1,2,1] - 3 * S[1,1,2]).to_descent_algebra(4)
            -3*B[1, 1, 2] + B[1, 2, 1]
            sage: S[2,1].to_descent_algebra(2)
            0
            sage: S[2,1].to_descent_algebra()
            B[2, 1]
            sage: S.zero().to_descent_algebra().parent()
            Descent algebra of 0 over Integer Ring in the subset basis
            sage: (S[1,2,1] - 3 * S[1,1,2]).to_descent_algebra(1)
            0

        Python

            >>> from sage.all import *
            >>> S = NonCommutativeSymmetricFunctions(ZZ).S()
            >>> S[Integer(2),Integer(1)].to_descent_algebra(Integer(3))
            B[2, 1]
            >>> (S[Integer(1),Integer(2),Integer(1)] - Integer(3) * S[Integer(1),Integer(1),Integer(2)]).to_descent_algebra(Integer(4))
            -3*B[1, 1, 2] + B[1, 2, 1]
            >>> S[Integer(2),Integer(1)].to_descent_algebra(Integer(2))
            0
            >>> S[Integer(2),Integer(1)].to_descent_algebra()
            B[2, 1]
            >>> S.zero().to_descent_algebra().parent()
            Descent algebra of 0 over Integer Ring in the subset basis
            >>> (S[Integer(1),Integer(2),Integer(1)] - Integer(3) * S[Integer(1),Integer(1),Integer(2)]).to_descent_algebra(Integer(1))
            0

      to_fqsym()

        Return the image of the non-commutative symmetric function `self` under the morphism \(\iota : NSym \to FQSym\).

        This morphism is the injective algebra homomorphism \(NSym \to FQSym\) that sends each Complete generator \(S_n\) to \(F_{[1, 2, \ldots, n]}\). It is the inclusion map, if we regard both \(NSym\) and \(FQSym\) as rings of noncommutative power series.

        See also

        `FreeQuasisymmetricFunctions` for a definition of \(FQSym\).

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: R = N.ribbon()
            sage: x = 2*R[[]] + 2*R[1] + 3*R[2]
            sage: x.to_fqsym()
            2*F[] + 2*F[1] + 3*F[1, 2]
            sage: R[2,1].to_fqsym()
            F[1, 3, 2] + F[3, 1, 2]
            sage: x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            sage: x.to_fqsym()
            2*F[] + 2*F[1] + 3*F[2, 1]

            sage: y = N.Phi()[1,2]
            sage: y.to_fqsym()
            F[1, 2, 3] - F[1, 3, 2] + F[2, 1, 3] + F[2, 3, 1]
             - F[3, 1, 2] - F[3, 2, 1]

            sage: S = NonCommutativeSymmetricFunctions(QQ).S()
            sage: S[2].to_fqsym()
            F[1, 2]
            sage: S[1,2].to_fqsym()
            F[1, 2, 3] + F[2, 1, 3] + F[2, 3, 1]
            sage: S[2,1].to_fqsym()
            F[1, 2, 3] + F[1, 3, 2] + F[3, 1, 2]
            sage: S[1,2,1].to_fqsym()
            F[1, 2, 3, 4] + F[1, 2, 4, 3] + F[1, 4, 2, 3]
             + F[2, 1, 3, 4] + F[2, 1, 4, 3] + F[2, 3, 1, 4]
             + F[2, 3, 4, 1] + F[2, 4, 1, 3] + F[2, 4, 3, 1]
             + F[4, 1, 2, 3] + F[4, 2, 1, 3] + F[4, 2, 3, 1]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> R = N.ribbon()
            >>> x = Integer(2)*R[[]] + Integer(2)*R[Integer(1)] + Integer(3)*R[Integer(2)]
            >>> x.to_fqsym()
            2*F[] + 2*F[1] + 3*F[1, 2]
            >>> R[Integer(2),Integer(1)].to_fqsym()
            F[1, 3, 2] + F[3, 1, 2]
            >>> x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            >>> x.to_fqsym()
            2*F[] + 2*F[1] + 3*F[2, 1]

            >>> y = N.Phi()[Integer(1),Integer(2)]
            >>> y.to_fqsym()
            F[1, 2, 3] - F[1, 3, 2] + F[2, 1, 3] + F[2, 3, 1]
             - F[3, 1, 2] - F[3, 2, 1]

            >>> S = NonCommutativeSymmetricFunctions(QQ).S()
            >>> S[Integer(2)].to_fqsym()
            F[1, 2]
            >>> S[Integer(1),Integer(2)].to_fqsym()
            F[1, 2, 3] + F[2, 1, 3] + F[2, 3, 1]
            >>> S[Integer(2),Integer(1)].to_fqsym()
            F[1, 2, 3] + F[1, 3, 2] + F[3, 1, 2]
            >>> S[Integer(1),Integer(2),Integer(1)].to_fqsym()
            F[1, 2, 3, 4] + F[1, 2, 4, 3] + F[1, 4, 2, 3]
             + F[2, 1, 3, 4] + F[2, 1, 4, 3] + F[2, 3, 1, 4]
             + F[2, 3, 4, 1] + F[2, 4, 1, 3] + F[2, 4, 3, 1]
             + F[4, 1, 2, 3] + F[4, 2, 1, 3] + F[4, 2, 3, 1]

      to_fsym()

        Return the image of `self` under the natural map to \(FSym\).

        There is an injective Hopf algebra morphism from \(NSym\) to \(FSym\) (see `FreeSymmetricFunctions`), which maps the ribbon \(R_\alpha\) indexed by a composition \(\alpha\) to the sum of all tableaux whose descent composition is \(\alpha\). If we regard \(NSym\) as a Hopf subalgebra of \(FQSym\) via the morphism \(\iota : NSym \to FQSym\) (implemented as `to_fqsym()`), then this injective morphism is just the inclusion map.

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: R = N.ribbon()
            sage: x = 2*R[[]] + 2*R[1] + 3*R[2]
            sage: x.to_fsym()
            2*G[] + 2*G[1] + 3*G[12]
            sage: R[2,1].to_fsym()
            G[12|3]
            sage: R[1,2].to_fsym()
            G[13|2]
            sage: R[2,1,2].to_fsym()
            G[12|35|4] + G[125|3|4]
            sage: x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            sage: x.to_fsym()
            2*G[] + 2*G[1] + 3*G[1|2]

            sage: y = N.Phi()[1,2]
            sage: y.to_fsym()
            -G[1|2|3] - G[12|3] + G[123] + G[13|2]

            sage: S = NonCommutativeSymmetricFunctions(QQ).S()
            sage: S[2].to_fsym()
            G[12]
            sage: S[2,1].to_fsym()
            G[12|3] + G[123]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> R = N.ribbon()
            >>> x = Integer(2)*R[[]] + Integer(2)*R[Integer(1)] + Integer(3)*R[Integer(2)]
            >>> x.to_fsym()
            2*G[] + 2*G[1] + 3*G[12]
            >>> R[Integer(2),Integer(1)].to_fsym()
            G[12|3]
            >>> R[Integer(1),Integer(2)].to_fsym()
            G[13|2]
            >>> R[Integer(2),Integer(1),Integer(2)].to_fsym()
            G[12|35|4] + G[125|3|4]
            >>> x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            >>> x.to_fsym()
            2*G[] + 2*G[1] + 3*G[1|2]

            >>> y = N.Phi()[Integer(1),Integer(2)]
            >>> y.to_fsym()
            -G[1|2|3] - G[12|3] + G[123] + G[13|2]

            >>> S = NonCommutativeSymmetricFunctions(QQ).S()
            >>> S[Integer(2)].to_fsym()
            G[12]
            >>> S[Integer(2),Integer(1)].to_fsym()
            G[12|3] + G[123]

      to_ncsym()

        Return the image of `self` under the injective algebra homomorphism \(\kappa : NSym \to NCSym\) that fixes the symmetric functions.

        As usual, \(NCSym\) denotes the ring of symmetric functions in non-commuting variables. Let \(S_n\) denote a generator of the complete basis. The algebra homomorphism \(\kappa : NSym \to NCSym\) is defined by

        \[S_n \mapsto \sum_{A \vdash [n]} \frac{\lambda(A)! \lambda(A)^!}{n!} \mathbf{m}_A .\]

        It has the property that the canonical maps \(\chi : NCSym \to Sym\) and \(\rho : NSym \to Sym\) satisfy \(\chi \circ \kappa = \rho\).

        Note

        A remark in [BRRZ08] makes it clear that the embedding of \(NSym\) into \(NCSym\) that preserves the projection into the symmetric functions is not unique. While this seems to be a natural embedding, any free set of algebraic generators of \(NSym\) can be sent to a set of free elements in \(NCSym\) to form another embedding.

        See also

        `NonCommutativeSymmetricFunctions` for a definition of \(NCSym\).

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: S = N.complete()
            sage: S[2].to_ncsym()
            1/2*m{{1}, {2}} + m{{1, 2}}
            sage: S[1,2,1].to_ncsym()
            1/2*m{{1}, {2}, {3}, {4}} + 1/2*m{{1}, {2}, {3, 4}} + m{{1}, {2, 3}, {4}}
             + m{{1}, {2, 3, 4}} + 1/2*m{{1}, {2, 4}, {3}} + 1/2*m{{1, 2}, {3}, {4}}
             + 1/2*m{{1, 2}, {3, 4}} + m{{1, 2, 3}, {4}} + m{{1, 2, 3, 4}}
             + 1/2*m{{1, 2, 4}, {3}} + 1/2*m{{1, 3}, {2}, {4}} + 1/2*m{{1, 3}, {2, 4}}
             + 1/2*m{{1, 3, 4}, {2}} + 1/2*m{{1, 4}, {2}, {3}} + m{{1, 4}, {2, 3}}
            sage: S[1,2].to_ncsym()
            1/2*m{{1}, {2}, {3}} + m{{1}, {2, 3}} + 1/2*m{{1, 2}, {3}}
             + m{{1, 2, 3}} + 1/2*m{{1, 3}, {2}}
            sage: S[[]].to_ncsym()
            m{}

            sage: R = N.ribbon()
            sage: x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            sage: x.to_ncsym()
            2*m{} + 2*m{{1}} + 3/2*m{{1}, {2}}
            sage: R[2,1].to_ncsym()
            1/3*m{{1}, {2}, {3}} + 1/6*m{{1}, {2, 3}}
             + 2/3*m{{1, 2}, {3}} + 1/6*m{{1, 3}, {2}}

            sage: Phi = N.Phi()
            sage: Phi[1,2].to_ncsym()
            m{{1}, {2, 3}} + m{{1, 2, 3}}
            sage: Phi[1,3].to_ncsym()
            -1/4*m{{1}, {2}, {3, 4}} - 1/4*m{{1}, {2, 3}, {4}} + m{{1}, {2, 3, 4}}
             + 1/2*m{{1}, {2, 4}, {3}} - 1/4*m{{1, 2}, {3, 4}} - 1/4*m{{1, 2, 3}, {4}}
             + m{{1, 2, 3, 4}} + 1/2*m{{1, 2, 4}, {3}} + 1/2*m{{1, 3}, {2, 4}}
             - 1/4*m{{1, 3, 4}, {2}} - 1/4*m{{1, 4}, {2, 3}}

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> S = N.complete()
            >>> S[Integer(2)].to_ncsym()
            1/2*m{{1}, {2}} + m{{1, 2}}
            >>> S[Integer(1),Integer(2),Integer(1)].to_ncsym()
            1/2*m{{1}, {2}, {3}, {4}} + 1/2*m{{1}, {2}, {3, 4}} + m{{1}, {2, 3}, {4}}
             + m{{1}, {2, 3, 4}} + 1/2*m{{1}, {2, 4}, {3}} + 1/2*m{{1, 2}, {3}, {4}}
             + 1/2*m{{1, 2}, {3, 4}} + m{{1, 2, 3}, {4}} + m{{1, 2, 3, 4}}
             + 1/2*m{{1, 2, 4}, {3}} + 1/2*m{{1, 3}, {2}, {4}} + 1/2*m{{1, 3}, {2, 4}}
             + 1/2*m{{1, 3, 4}, {2}} + 1/2*m{{1, 4}, {2}, {3}} + m{{1, 4}, {2, 3}}
            >>> S[Integer(1),Integer(2)].to_ncsym()
            1/2*m{{1}, {2}, {3}} + m{{1}, {2, 3}} + 1/2*m{{1, 2}, {3}}
             + m{{1, 2, 3}} + 1/2*m{{1, 3}, {2}}
            >>> S[[]].to_ncsym()
            m{}

            >>> R = N.ribbon()
            >>> x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            >>> x.to_ncsym()
            2*m{} + 2*m{{1}} + 3/2*m{{1}, {2}}
            >>> R[Integer(2),Integer(1)].to_ncsym()
            1/3*m{{1}, {2}, {3}} + 1/6*m{{1}, {2, 3}}
             + 2/3*m{{1, 2}, {3}} + 1/6*m{{1, 3}, {2}}

            >>> Phi = N.Phi()
            >>> Phi[Integer(1),Integer(2)].to_ncsym()
            m{{1}, {2, 3}} + m{{1, 2, 3}}
            >>> Phi[Integer(1),Integer(3)].to_ncsym()
            -1/4*m{{1}, {2}, {3, 4}} - 1/4*m{{1}, {2, 3}, {4}} + m{{1}, {2, 3, 4}}
             + 1/2*m{{1}, {2, 4}, {3}} - 1/4*m{{1, 2}, {3, 4}} - 1/4*m{{1, 2, 3}, {4}}
             + m{{1, 2, 3, 4}} + 1/2*m{{1, 2, 4}, {3}} + 1/2*m{{1, 3}, {2, 4}}
             - 1/4*m{{1, 3, 4}, {2}} - 1/4*m{{1, 4}, {2, 3}}

      to_symmetric_function()

        Return the commutative image of a non-commutative symmetric function.

        OUTPUT: the commutative image of `self`; this will be a symmetric function

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: R = N.ribbon()
            sage: x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            sage: x.to_symmetric_function()
            2*s[] + 2*s[1] + 3*s[1, 1]
            sage: y = N.Phi()[1,3]
            sage: y.to_symmetric_function()
            h[1, 1, 1, 1] - 3*h[2, 1, 1] + 3*h[3, 1]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> R = N.ribbon()
            >>> x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            >>> x.to_symmetric_function()
            2*s[] + 2*s[1] + 3*s[1, 1]
            >>> y = N.Phi()[Integer(1),Integer(3)]
            >>> y.to_symmetric_function()
            h[1, 1, 1, 1] - 3*h[2, 1, 1] + 3*h[3, 1]

      to_symmetric_group_algebra()

        Return the image of a non-commutative symmetric function into the symmetric group algebra where the ribbon basis element indexed by a composition is associated with the sum of all permutations which have descent set equal to said composition. In compliance with the anti- isomorphism between the descent algebra and the non-commutative symmetric functions, we index descent positions by the reversed composition.

        OUTPUT:

        - The image of `self` under the embedding of the \(n\)-th degree homogeneous component of the non-commutative symmetric functions in the symmetric group algebra of \(S_n\). This can behave unexpectedly when `self` is not homogeneous.

        EXAMPLES:

        Sage

            sage: R = NonCommutativeSymmetricFunctions(QQ).R()
            sage: R[2,1].to_symmetric_group_algebra()
            [1, 3, 2] + [2, 3, 1]
            sage: R([]).to_symmetric_group_algebra()
            []

        Python

            >>> from sage.all import *
            >>> R = NonCommutativeSymmetricFunctions(QQ).R()
            >>> R[Integer(2),Integer(1)].to_symmetric_group_algebra()
            [1, 3, 2] + [2, 3, 1]
            >>> R([]).to_symmetric_group_algebra()
            []

      verschiebung(n)

        Return the image of the noncommutative symmetric function `self` under the \(n\)-th Verschiebung operator.

        The \(n\)-th Verschiebung operator \(\mathbf{V}_n\) is defined to be the map from the \(\mathbf{k}\)-algebra of noncommutative symmetric functions to itself that sends the complete function \(S^I\) indexed by a composition \(I = (i_1, i_2, \ldots , i_k)\) to \(S^{(i_1/n, i_2/n, \ldots , i_k/n)}\) if all of the numbers \(i_1, i_2, \ldots, i_k\) are divisible by \(n\), and to \(0\) otherwise. This operator \(\mathbf{V}_n\) is a Hopf algebra endomorphism. For every positive integer \(r\) with \(n \mid r\), it satisfies

        \[\mathbf{V}_n(S_r) = S_{r/n}, \quad \mathbf{V}_n(\Lambda_r) = (-1)^{r - r/n} \Lambda_{r/n}, \quad \mathbf{V}_n(\Psi_r) = n \Psi_{r/n}, \quad \mathbf{V}_n(\Phi_r) = n \Phi_{r/n}\]

        (where \(S_r\) denotes the \(r\)-th complete non-commutative symmetric function, \(\Lambda_r\) denotes the \(r\)-th elementary non-commutative symmetric function, \(\Psi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the first kind, and \(\Phi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the second kind). For every positive integer \(r\) with \(n \nmid r\), it satisfes

        \[\mathbf{V}_n(S_r) = \mathbf{V}_n(\Lambda_r) = \mathbf{V}_n(\Psi_r) = \mathbf{V}_n(\Phi_r) = 0.\]

        The \(n\)-th Verschiebung operator is also called the \(n\)-th Verschiebung endomorphism.

        It is a lift of the \(n\)-th Verschiebung operator on the ring of symmetric functions (`verschiebung()`) to the ring of noncommutative symmetric functions.

        The action of the \(n\)-th Verschiebung operator can also be described on the ribbon Schur functions. Namely, every composition \(I\) of size \(n \ell\) satisfies

        \[\mathbf{V}_n ( R_I ) = (-1)^{\ell(I) - \ell(J)} \cdot R_{J / n},\]

        where \(J\) denotes the meet of the compositions \(I\) and \((\underbrace{n, n, \ldots, n}_{|I|/n \mbox{ times}})\), where \(\ell(I)\) is the length of \(I\), and where \(J / n\) denotes the composition obtained by dividing every entry of \(J\) by \(n\). For a composition \(I\) of size not divisible by \(n\), we have \(\mathbf{V}_n( R_I ) = 0\).

        See also

        `adams_operator method of QSym`, `verschiebung method of Sym`

        INPUT:

        - `n` – positive integer

        OUTPUT:

        The result of applying the \(n\)-th Verschiebung operator (on the ring of noncommutative symmetric functions) to `self`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: S = NSym.S()
            sage: S[3,2].verschiebung(2)
            0
            sage: S[6,4].verschiebung(2)
            S[3, 2]
            sage: (S[9,1] - S[8,2] + 2*S[6,4] - 3*S[3] + 4*S[[]]).verschiebung(2)
            4*S[] + 2*S[3, 2] - S[4, 1]
            sage: (S[3,3] - 2*S[2]).verschiebung(3)
            S[1, 1]
            sage: S([4,2]).verschiebung(1)
            S[4, 2]
            sage: R = NSym.R()
            sage: R([4,2]).verschiebung(2)
            R[2, 1]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> S = NSym.S()
            >>> S[Integer(3),Integer(2)].verschiebung(Integer(2))
            0
            >>> S[Integer(6),Integer(4)].verschiebung(Integer(2))
            S[3, 2]
            >>> (S[Integer(9),Integer(1)] - S[Integer(8),Integer(2)] + Integer(2)*S[Integer(6),Integer(4)] - Integer(3)*S[Integer(3)] + Integer(4)*S[[]]).verschiebung(Integer(2))
            4*S[] + 2*S[3, 2] - S[4, 1]
            >>> (S[Integer(3),Integer(3)] - Integer(2)*S[Integer(2)]).verschiebung(Integer(3))
            S[1, 1]
            >>> S([Integer(4),Integer(2)]).verschiebung(Integer(1))
            S[4, 2]
            >>> R = NSym.R()
            >>> R([Integer(4),Integer(2)]).verschiebung(Integer(2))
            R[2, 1]

        Being Hopf algebra endomorphisms, the Verschiebung operators commute with the antipode:

        Sage

            sage: all( R(I).verschiebung(2).antipode()
            ....:      == R(I).antipode().verschiebung(2)
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> all( R(I).verschiebung(Integer(2)).antipode()
            ...      == R(I).antipode().verschiebung(Integer(2))
            ...      for I in Compositions(Integer(4)) )
            True

        They lift the Verschiebung operators of the ring of symmetric functions:

        Sage

            sage: all( S(I).verschiebung(2).to_symmetric_function()
            ....:      == S(I).to_symmetric_function().verschiebung(2)
            ....:      for I in Compositions(4) )
            True

        Python

            >>> from sage.all import *
            >>> all( S(I).verschiebung(Integer(2)).to_symmetric_function()
            ...      == S(I).to_symmetric_function().verschiebung(Integer(2))
            ...      for I in Compositions(Integer(4)) )
            True

        The Frobenius operators on \(QSym\) are adjoint to the Verschiebung operators on \(NSym\) with respect to the duality pairing:

        Sage

            sage: QSym = QuasiSymmetricFunctions(ZZ)
            sage: M = QSym.M()
            sage: all( all( M(I).adams_operator(3).duality_pairing(S(J))
            ....:           == M(I).duality_pairing(S(J).verschiebung(3))
            ....:           for I in Compositions(2) )
            ....:      for J in Compositions(3) )
            True

        [Python]

            >>> from sage.all import *
            >>> QSym = QuasiSymmetricFunctions(ZZ)
            >>> M = QSym.M()
            >>> all( all( M(I).adams_operator(Integer(3)).duality_pairing(S(J))
            ...           == M(I).duality_pairing(S(J).verschiebung(Integer(3)))
            ...           for I in Compositions(Integer(2)) )
            ...      for J in Compositions(Integer(3)) )
            True

    class ParentMethods

      Bases: `object`

      immaculate_function(xs)

        Return the immaculate function corresponding to the integer vector `xs`, written in the basis `self`.

        If \(\alpha\) is any integer vector – i.e., an element of \(\ZZ^m\) for some \(m \in \NN\) –, the immaculate function corresponding to \(\alpha\) is a non-commutative symmetric function denoted by \(\mathfrak{S}_{\alpha}\). One way to define this function is by setting

        \[\mathfrak{S}_{\alpha} = \sum_{\sigma \in S_m} (-1)^{\sigma} S_{\alpha_1 + \sigma(1) - 1} S_{\alpha_2 + \sigma(2) - 2} \cdots S_{\alpha_m + \sigma(m) - m},\]

        where \(\alpha\) is written in the form \((\alpha_1, \alpha_2, \ldots, \alpha_m)\), and where \(S\) stands for the complete basis (`Complete`).

        The immaculate function \(\mathfrak{S}_{\alpha}\) first appeared in [BBSSZ2012] (where it was defined differently, but the definition we gave above appeared as Theorem 3.27).

        The immaculate functions \(\mathfrak{S}_{\alpha}\) for \(\alpha\) running over all compositions (i.e., finite sequences of positive integers) form a basis of \(NCSF\). This is the immaculate basis (`Immaculate`).

        INPUT:

        - `xs` – list (or tuple or any iterable – possibly a composition) of integers

        OUTPUT:

        The immaculate function \(\mathfrak{S}_{xs}\) written in the basis `self`.

        EXAMPLES:

        Let us first check that, for `xs` a composition, we get the same as the result of `self.realization_of().I()[xs]`:

        Sage

            sage: def test_comp(xs):
            ....:     NSym = NonCommutativeSymmetricFunctions(QQ)
            ....:     I = NSym.I()
            ....:     return I[xs] == I.immaculate_function(xs)
            sage: def test_allcomp(n):
            ....:     return all( test_comp(c) for c in Compositions(n) )
            sage: test_allcomp(1)
            True
            sage: test_allcomp(2)
            True
            sage: test_allcomp(3)
            True

        Python

            >>> from sage.all import *
            >>> def test_comp(xs):
            ...     NSym = NonCommutativeSymmetricFunctions(QQ)
            ...     I = NSym.I()
            ...     return I[xs] == I.immaculate_function(xs)
            >>> def test_allcomp(n):
            ...     return all( test_comp(c) for c in Compositions(n) )
            >>> test_allcomp(Integer(1))
            True
            >>> test_allcomp(Integer(2))
            True
            >>> test_allcomp(Integer(3))
            True

        Now some examples of non-composition immaculate functions:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: I = NSym.I()
            sage: I.immaculate_function([0, 1])
            0
            sage: I.immaculate_function([0, 2])
            -I[1, 1]
            sage: I.immaculate_function([-1, 1])
            -I[]
            sage: I.immaculate_function([2, -1])
            0
            sage: I.immaculate_function([2, 0])
            I[2]
            sage: I.immaculate_function([2, 0, 1])
            0
            sage: I.immaculate_function([1, 0, 2])
            -I[1, 1, 1]
            sage: I.immaculate_function([2, 0, 2])
            -I[2, 1, 1]
            sage: I.immaculate_function([0, 2, 0, 2])
            I[1, 1, 1, 1] + I[1, 2, 1]
            sage: I.immaculate_function([2, 0, 2, 0, 2])
            I[2, 1, 1, 1, 1] + I[2, 1, 2, 1]

        [Python]

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> I = NSym.I()
            >>> I.immaculate_function([Integer(0), Integer(1)])
            0
            >>> I.immaculate_function([Integer(0), Integer(2)])
            -I[1, 1]
            >>> I.immaculate_function([-Integer(1), Integer(1)])
            -I[]
            >>> I.immaculate_function([Integer(2), -Integer(1)])
            0
            >>> I.immaculate_function([Integer(2), Integer(0)])
            I[2]
            >>> I.immaculate_function([Integer(2), Integer(0), Integer(1)])
            0
            >>> I.immaculate_function([Integer(1), Integer(0), Integer(2)])
            -I[1, 1, 1]
            >>> I.immaculate_function([Integer(2), Integer(0), Integer(2)])
            -I[2, 1, 1]
            >>> I.immaculate_function([Integer(0), Integer(2), Integer(0), Integer(2)])
            I[1, 1, 1, 1] + I[1, 2, 1]
            >>> I.immaculate_function([Integer(2), Integer(0), Integer(2), Integer(0), Integer(2)])
            I[2, 1, 1, 1, 1] + I[2, 1, 2, 1]

      to_symmetric_function()

        Morphism to the algebra of symmetric functions.

        This is constructed by extending the computation on the basis or by coercion to the complete basis.

        OUTPUT:

        - The module morphism from the basis `self` to the symmetric functions which corresponds to taking a commutative image.

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: R = N.ribbon()
            sage: x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            sage: R.to_symmetric_function(x)
            2*s[] + 2*s[1] + 3*s[1, 1]
            sage: nM = N.Monomial()
            sage: nM.to_symmetric_function(nM[3,1])
            h[1, 1, 1, 1] - 7/2*h[2, 1, 1] + h[2, 2] + 7/2*h[3, 1] - 2*h[4]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> R = N.ribbon()
            >>> x = R.an_element(); x
            2*R[] + 2*R[1] + 3*R[1, 1]
            >>> R.to_symmetric_function(x)
            2*s[] + 2*s[1] + 3*s[1, 1]
            >>> nM = N.Monomial()
            >>> nM.to_symmetric_function(nM[Integer(3),Integer(1)])
            h[1, 1, 1, 1] - 7/2*h[2, 1, 1] + h[2, 2] + 7/2*h[3, 1] - 2*h[4]

      to_symmetric_function_on_basis(I)

        The image of the basis element indexed by `I` under the map to the symmetric functions.

        This default implementation does a change of basis and computes the image in the complete basis.

        INPUT:

        - `I` – a composition

        OUTPUT:

        - The image of the non-commutative basis element of `self` indexed by the composition `I` under the map from non-commutative symmetric functions to the symmetric functions. This will be a symmetric function.

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: I = N.Immaculate()
            sage: I.to_symmetric_function(I[1,3])
            -h[2, 2] + h[3, 1]
            sage: I.to_symmetric_function(I[1,2])
            0
            sage: Phi = N.Phi()
            sage: Phi.to_symmetric_function_on_basis([3,1,2])==Phi.to_symmetric_function(Phi[3,1,2])
            True
            sage: Phi.to_symmetric_function_on_basis([])
            h[]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> I = N.Immaculate()
            >>> I.to_symmetric_function(I[Integer(1),Integer(3)])
            -h[2, 2] + h[3, 1]
            >>> I.to_symmetric_function(I[Integer(1),Integer(2)])
            0
            >>> Phi = N.Phi()
            >>> Phi.to_symmetric_function_on_basis([Integer(3),Integer(1),Integer(2)])==Phi.to_symmetric_function(Phi[Integer(3),Integer(1),Integer(2)])
            True
            >>> Phi.to_symmetric_function_on_basis([])
            h[]

    super_categories()

      Return the super categories of the category of bases of the non-commutative symmetric functions.

      OUTPUT: list

  class Complete(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the Complete basis.

    The Complete basis is defined in Definition 3.4 of [NCSF1], where it is denoted by \((S^I)_I\). It is a multiplicative basis, and is connected to the elementary generators \(\Lambda_i\) of the ring of non-commutative symmetric functions by the following relation: Define a non-commutative symmetric function \(S_n\) for every nonnegative integer \(n\) by the power series identity

    \[\sum_{k \geq 0} t^k S_k = \left( \sum_{k \geq 0} (-t)^k \Lambda_k \right)^{-1},\]

    with \(\Lambda_0\) denoting \(1\). For every composition \((i_1, i_2, \ldots, i_k)\), we have \(S^{(i_1, i_2, \ldots, i_k)} = S_{i_1} S_{i_2} \cdots S_{i_k}\).

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: S = NCSF.Complete(); S
        Non-Commutative Symmetric Functions over the Rational Field in the Complete basis
        sage: S.an_element()
        2*S[] + 2*S[1] + 3*S[1, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> S = NCSF.Complete(); S
        Non-Commutative Symmetric Functions over the Rational Field in the Complete basis
        >>> S.an_element()
        2*S[] + 2*S[1] + 3*S[1, 1]

    The following are aliases for this basis:

    Sage

        sage: NCSF.complete()
        Non-Commutative Symmetric Functions over the Rational Field in the Complete basis
        sage: NCSF.S()
        Non-Commutative Symmetric Functions over the Rational Field in the Complete basis

    [Python]

        >>> from sage.all import *
        >>> NCSF.complete()
        Non-Commutative Symmetric Functions over the Rational Field in the Complete basis
        >>> NCSF.S()
        Non-Commutative Symmetric Functions over the Rational Field in the Complete basis

    class Element

      Bases: `IndexedFreeModuleElement`

      An element in the Complete basis.

      psi_involution()

        Return the image of the noncommutative symmetric function `self` under the involution \(\psi\).

        The involution \(\psi\) is defined as the linear map \(NCSF \to NCSF\) which, for every composition \(I\), sends the complete noncommutative symmetric function \(S^I\) to the elementary noncommutative symmetric function \(\Lambda^I\). It can be shown that every composition \(I\) satisfies

        \[\psi(R_I) = R_{I^c}, \quad \psi(S^I) = \Lambda^I, \quad \psi(\Lambda^I) = S^I, \quad \psi(\Phi^I) = (-1)^{|I| - \ell(I)} \Phi^I\]

        where \(I^c\) denotes the complement of the composition \(I\), and \(\ell(I)\) denotes the length of \(I\), and where standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(\Phi\) for the basis of the power sums of the second kind, and \(R\) for the ribbon basis). The map \(\psi\) is an involution and a graded Hopf algebra automorphism of \(NCSF\). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(\psi(f)) = \omega(\pi(f))\) for every \(f \in NCSF\), where the \(\omega\) on the right hand side denotes the omega automorphism of \(Sym\).

        The involution \(\psi\) of \(NCSF\) is adjoint to the involution \(\psi\) of \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The involution \(\psi\) has been denoted by \(\psi\) in [LMvW13], section 3.6.

        See also

        `psi involution of NCSF`, `psi involution of QSym`, `star involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: S = NSym.S()
            sage: L = NSym.L()
            sage: S[3,1].psi_involution()
            S[1, 1, 1, 1] - S[1, 2, 1] - S[2, 1, 1] + S[3, 1]
            sage: L(S[3,1].psi_involution())
            L[3, 1]
            sage: S[[]].psi_involution()
            S[]
            sage: S[1,1].psi_involution()
            S[1, 1]
            sage: (S[2,1] - 2*S[2]).psi_involution()
            -2*S[1, 1] + S[1, 1, 1] + 2*S[2] - S[2, 1]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> S = NSym.S()
            >>> L = NSym.L()
            >>> S[Integer(3),Integer(1)].psi_involution()
            S[1, 1, 1, 1] - S[1, 2, 1] - S[2, 1, 1] + S[3, 1]
            >>> L(S[Integer(3),Integer(1)].psi_involution())
            L[3, 1]
            >>> S[[]].psi_involution()
            S[]
            >>> S[Integer(1),Integer(1)].psi_involution()
            S[1, 1]
            >>> (S[Integer(2),Integer(1)] - Integer(2)*S[Integer(2)]).psi_involution()
            -2*S[1, 1] + S[1, 1, 1] + 2*S[2] - S[2, 1]

        The implementation at hand is tailored to the complete basis. It is equivalent to the generic implementation via the ribbon basis:

        Sage

            sage: R = NSym.R()
            sage: all( R(S[I].psi_involution()) == R(S[I]).psi_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> R = NSym.R()
            >>> all( R(S[I].psi_involution()) == R(S[I]).psi_involution()
            ...      for I in Compositions(Integer(4)) )
            True

    dual()

      Return the dual basis to the complete basis of non-commutative symmetric functions. This is the Monomial basis of quasi-symmetric functions.

      OUTPUT: the Monomial basis of quasi-symmetric functions

      EXAMPLES:

      Sage

          sage: S = NonCommutativeSymmetricFunctions(QQ).S()
          sage: S.dual()
          Quasisymmetric functions over the Rational Field in the Monomial basis

      Python

          >>> from sage.all import *
          >>> S = NonCommutativeSymmetricFunctions(QQ).S()
          >>> S.dual()
          Quasisymmetric functions over the Rational Field in the Monomial basis

    internal_product_on_basis(I, J)

      The internal product of two non-commutative symmetric complete functions.

      See `internal_product()` for a thorough documentation of this operation.

      INPUT:

      - `I`, `J` – compositions

      OUTPUT:

      - The internal product of the complete non-commutative symmetric function basis elements indexed by `I` and `J`, expressed in the complete basis.

      EXAMPLES:

      Sage

          sage: N = NonCommutativeSymmetricFunctions(QQ)
          sage: S = N.complete()
          sage: S.internal_product_on_basis([2,2],[1,2,1])
          2*S[1, 1, 1, 1] + S[1, 1, 2] + S[2, 1, 1]
          sage: S.internal_product_on_basis([2,2],[1,2])
          0

      Python

          >>> from sage.all import *
          >>> N = NonCommutativeSymmetricFunctions(QQ)
          >>> S = N.complete()
          >>> S.internal_product_on_basis([Integer(2),Integer(2)],[Integer(1),Integer(2),Integer(1)])
          2*S[1, 1, 1, 1] + S[1, 1, 2] + S[2, 1, 1]
          >>> S.internal_product_on_basis([Integer(2),Integer(2)],[Integer(1),Integer(2)])
          0

    to_symmetric_function()

      Morphism to the algebra of symmetric functions.

      This is constructed by extending the computation on the complete basis.

      OUTPUT:

      - The module morphism from the basis `self` to the symmetric functions which corresponds to taking a commutative image.

      EXAMPLES:

      Sage

          sage: N = NonCommutativeSymmetricFunctions(QQ)
          sage: S = N.complete()
          sage: S.to_symmetric_function(S[3,1,2])
          h[3, 2, 1]
          sage: S.to_symmetric_function(S[[]])
          h[]

      Python

          >>> from sage.all import *
          >>> N = NonCommutativeSymmetricFunctions(QQ)
          >>> S = N.complete()
          >>> S.to_symmetric_function(S[Integer(3),Integer(1),Integer(2)])
          h[3, 2, 1]
          >>> S.to_symmetric_function(S[[]])
          h[]

    to_symmetric_function_on_basis(I)

      The commutative image of a complete element.

      The commutative image of a basis element is obtained by sorting the indexing composition of the basis element and the output is in the complete basis of the symmetric functions.

      INPUT:

      - `I` – a composition

      OUTPUT:

      - The commutative image of the complete basis element indexed by `I`. The result is the complete symmetric function indexed by the partition obtained by sorting `I`.

      EXAMPLES:

      Sage

          sage: S = NonCommutativeSymmetricFunctions(QQ).complete()
          sage: S.to_symmetric_function_on_basis([2,1,3])
          h[3, 2, 1]
          sage: S.to_symmetric_function_on_basis([])
          h[]

      Python

          >>> from sage.all import *
          >>> S = NonCommutativeSymmetricFunctions(QQ).complete()
          >>> S.to_symmetric_function_on_basis([Integer(2),Integer(1),Integer(3)])
          h[3, 2, 1]
          >>> S.to_symmetric_function_on_basis([])
          h[]

  class Elementary(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the Elementary basis.

    The Elementary basis is defined in Definition 3.4 of [NCSF1], where it is denoted by \((\Lambda^I)_I\). It is a multiplicative basis, and is obtained from the elementary generators \(\Lambda_i\) of the ring of non-commutative symmetric functions through the formula \(\Lambda^{(i_1, i_2, \ldots, i_k)} = \Lambda_{i_1} \Lambda_{i_2} \cdots \Lambda_{i_k}\) for every composition \((i_1, i_2, \ldots, i_k)\).

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: L = NCSF.Elementary(); L
        Non-Commutative Symmetric Functions over the Rational Field in the Elementary basis
        sage: L.an_element()
        2*L[] + 2*L[1] + 3*L[1, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> L = NCSF.Elementary(); L
        Non-Commutative Symmetric Functions over the Rational Field in the Elementary basis
        >>> L.an_element()
        2*L[] + 2*L[1] + 3*L[1, 1]

    The following are aliases for this basis:

    Sage

        sage: NCSF.elementary()
        Non-Commutative Symmetric Functions over the Rational Field in the Elementary basis
        sage: NCSF.L()
        Non-Commutative Symmetric Functions over the Rational Field in the Elementary basis

    [Python]

        >>> from sage.all import *
        >>> NCSF.elementary()
        Non-Commutative Symmetric Functions over the Rational Field in the Elementary basis
        >>> NCSF.L()
        Non-Commutative Symmetric Functions over the Rational Field in the Elementary basis

    class Element

      Bases: `IndexedFreeModuleElement`

      psi_involution()

        Return the image of the noncommutative symmetric function `self` under the involution \(\psi\).

        The involution \(\psi\) is defined as the linear map \(NCSF \to NCSF\) which, for every composition \(I\), sends the complete noncommutative symmetric function \(S^I\) to the elementary noncommutative symmetric function \(\Lambda^I\). It can be shown that every composition \(I\) satisfies

        \[\psi(R_I) = R_{I^c}, \quad \psi(S^I) = \Lambda^I, \quad \psi(\Lambda^I) = S^I, \quad \psi(\Phi^I) = (-1)^{|I| - \ell(I)} \Phi^I\]

        where \(I^c\) denotes the complement of the composition \(I\), and \(\ell(I)\) denotes the length of \(I\), and where standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(\Phi\) for the basis of the power sums of the second kind, and \(R\) for the ribbon basis). The map \(\psi\) is an involution and a graded Hopf algebra automorphism of \(NCSF\). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(\psi(f)) = \omega(\pi(f))\) for every \(f \in NCSF\), where the \(\omega\) on the right hand side denotes the omega automorphism of \(Sym\).

        The involution \(\psi\) of \(NCSF\) is adjoint to the involution \(\psi\) of \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The involution \(\psi\) has been denoted by \(\psi\) in [LMvW13], section 3.6.

        See also

        `psi involution of NCSF`, `psi involution of QSym`, `star involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: S = NSym.S()
            sage: L = NSym.L()
            sage: L[3,1].psi_involution()
            L[1, 1, 1, 1] - L[1, 2, 1] - L[2, 1, 1] + L[3, 1]
            sage: S(L[3,1].psi_involution())
            S[3, 1]
            sage: L[[]].psi_involution()
            L[]
            sage: L[1,1].psi_involution()
            L[1, 1]
            sage: (L[2,1] - 2*L[2]).psi_involution()
            -2*L[1, 1] + L[1, 1, 1] + 2*L[2] - L[2, 1]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> S = NSym.S()
            >>> L = NSym.L()
            >>> L[Integer(3),Integer(1)].psi_involution()
            L[1, 1, 1, 1] - L[1, 2, 1] - L[2, 1, 1] + L[3, 1]
            >>> S(L[Integer(3),Integer(1)].psi_involution())
            S[3, 1]
            >>> L[[]].psi_involution()
            L[]
            >>> L[Integer(1),Integer(1)].psi_involution()
            L[1, 1]
            >>> (L[Integer(2),Integer(1)] - Integer(2)*L[Integer(2)]).psi_involution()
            -2*L[1, 1] + L[1, 1, 1] + 2*L[2] - L[2, 1]

        The implementation at hand is tailored to the elementary basis. It is equivalent to the generic implementation via the ribbon basis:

        Sage

            sage: R = NSym.R()
            sage: all( R(L[I].psi_involution()) == R(L[I]).psi_involution()
            ....:      for I in Compositions(3) )
            True
            sage: all( R(L[I].psi_involution()) == R(L[I]).psi_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> R = NSym.R()
            >>> all( R(L[I].psi_involution()) == R(L[I]).psi_involution()
            ...      for I in Compositions(Integer(3)) )
            True
            >>> all( R(L[I].psi_involution()) == R(L[I]).psi_involution()
            ...      for I in Compositions(Integer(4)) )
            True

      star_involution()

        Return the image of the noncommutative symmetric function `self` under the star involution.

        The star involution is defined as the algebra antihomomorphism \(NCSF \to NCSF\) which, for every positive integer \(n\), sends the \(n\)-th complete non-commutative symmetric function \(S_n\) to \(S_n\). Denoting by \(f^{\ast}\) the image of an element \(f \in NCSF\) under this star involution, it can be shown that every composition \(I\) satisfies

        \[(S^I)^{\ast} = S^{I^r}, \quad (\Lambda^I)^{\ast} = \Lambda^{I^r}, \quad R_I^{\ast} = R_{I^r}, \quad (\Phi^I)^{\ast} = \Phi^{I^r},\]

        where \(I^r\) denotes the reversed composition of \(I\), and standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(R\) for the ribbon basis, and \(\Phi\) for that of the power-sums of the second kind). The star involution is an involution and a coalgebra automorphism of \(NCSF\). It is an automorphism of the graded vector space \(NCSF\). Under the canonical isomorphism between the \(n\)-th graded component of \(NCSF\) and the descent algebra of the symmetric group \(S_n\) (see `to_descent_algebra()`), the star involution (restricted to the \(n\)-th graded component) corresponds to the automorphism of the descent algebra given by \(x \mapsto \omega_n x \omega_n\), where \(\omega_n\) is the permutation \((n, n-1, \ldots, 1) \in S_n\) (written here in one-line notation). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(f^{\ast}) = \pi(f)\) for every \(f \in NCSF\).

        The star involution on \(NCSF\) is adjoint to the star involution on \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The star involution has been denoted by \(\rho\) in [LMvW13], section 3.6. See [NCSF2], section 2.3 for the properties of this map.

        See also

        `star involution of NCSF`, `psi involution of NCSF`, `star involution of QSym`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: L = NSym.L()
            sage: L[3,3,2,3].star_involution()
            L[3, 2, 3, 3]
            sage: L[6,3,3].star_involution()
            L[3, 3, 6]
            sage: (L[1,9,1] - L[8,2] + 2*L[6,4] - 3*L[3] + 4*L[[]]).star_involution()
            4*L[] + L[1, 9, 1] - L[2, 8] - 3*L[3] + 2*L[4, 6]
            sage: (L[3,3] - 2*L[2]).star_involution()
            -2*L[2] + L[3, 3]
            sage: L([4,1]).star_involution()
            L[1, 4]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> L = NSym.L()
            >>> L[Integer(3),Integer(3),Integer(2),Integer(3)].star_involution()
            L[3, 2, 3, 3]
            >>> L[Integer(6),Integer(3),Integer(3)].star_involution()
            L[3, 3, 6]
            >>> (L[Integer(1),Integer(9),Integer(1)] - L[Integer(8),Integer(2)] + Integer(2)*L[Integer(6),Integer(4)] - Integer(3)*L[Integer(3)] + Integer(4)*L[[]]).star_involution()
            4*L[] + L[1, 9, 1] - L[2, 8] - 3*L[3] + 2*L[4, 6]
            >>> (L[Integer(3),Integer(3)] - Integer(2)*L[Integer(2)]).star_involution()
            -2*L[2] + L[3, 3]
            >>> L([Integer(4),Integer(1)]).star_involution()
            L[1, 4]

        The implementation at hand is tailored to the elementary basis. It is equivalent to the generic implementation via the complete basis:

        Sage

            sage: S = NSym.S()
            sage: all( S(L[I].star_involution()) == S(L[I]).star_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> S = NSym.S()
            >>> all( S(L[I].star_involution()) == S(L[I]).star_involution()
            ...      for I in Compositions(Integer(4)) )
            True

      verschiebung(n)

        Return the image of the noncommutative symmetric function `self` under the \(n\)-th Verschiebung operator.

        The \(n\)-th Verschiebung operator \(\mathbf{V}_n\) is defined to be the map from the \(\mathbf{k}\)-algebra of noncommutative symmetric functions to itself that sends the complete function \(S^I\) indexed by a composition \(I = (i_1, i_2, \ldots , i_k)\) to \(S^{(i_1/n, i_2/n, \ldots , i_k/n)}\) if all of the numbers \(i_1, i_2, \ldots, i_k\) are divisible by \(n\), and to \(0\) otherwise. This operator \(\mathbf{V}_n\) is a Hopf algebra endomorphism. For every positive integer \(r\) with \(n \mid r\), it satisfies

        \[\mathbf{V}_n(S_r) = S_{r/n}, \quad \mathbf{V}_n(\Lambda_r) = (-1)^{r - r/n} \Lambda_{r/n}, \quad \mathbf{V}_n(\Psi_r) = n \Psi_{r/n}, \quad \mathbf{V}_n(\Phi_r) = n \Phi_{r/n}\]

        (where \(S_r\) denotes the \(r\)-th complete non-commutative symmetric function, \(\Lambda_r\) denotes the \(r\)-th elementary non-commutative symmetric function, \(\Psi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the first kind, and \(\Phi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the second kind). For every positive integer \(r\) with \(n \nmid r\), it satisfes

        \[\mathbf{V}_n(S_r) = \mathbf{V}_n(\Lambda_r) = \mathbf{V}_n(\Psi_r) = \mathbf{V}_n(\Phi_r) = 0.\]

        The \(n\)-th Verschiebung operator is also called the \(n\)-th Verschiebung endomorphism.

        It is a lift of the \(n\)-th Verschiebung operator on the ring of symmetric functions (`verschiebung()`) to the ring of noncommutative symmetric functions.

        The action of the \(n\)-th Verschiebung operator can also be described on the ribbon Schur functions. Namely, every composition \(I\) of size \(n \ell\) satisfies

        \[\mathbf{V}_n ( R_I ) = (-1)^{\ell(I) - \ell(J)} \cdot R_{J / n},\]

        where \(J\) denotes the meet of the compositions \(I\) and \((\underbrace{n, n, \ldots, n}_{|I|/n \mbox{ times}})\), where \(\ell(I)\) is the length of \(I\), and where \(J / n\) denotes the composition obtained by dividing every entry of \(J\) by \(n\). For a composition \(I\) of size not divisible by \(n\), we have \(\mathbf{V}_n ( R_I ) = 0\).

        See also

        `verschiebung method of NCSF`, `adams_operator method of QSym`, `verschiebung method of Sym`

        INPUT:

        - `n` – positive integer

        OUTPUT:

        The result of applying the \(n\)-th Verschiebung operator (on the ring of noncommutative symmetric functions) to `self`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: L = NSym.L()
            sage: L([4,2]).verschiebung(2)
            -L[2, 1]
            sage: L([2,4]).verschiebung(2)
            -L[1, 2]
            sage: L([6]).verschiebung(2)
            -L[3]
            sage: L([2,1]).verschiebung(3)
            0
            sage: L([3]).verschiebung(2)
            0
            sage: L([]).verschiebung(2)
            L[]
            sage: L([5, 1]).verschiebung(3)
            0
            sage: L([5, 1]).verschiebung(6)
            0
            sage: L([5, 1]).verschiebung(2)
            0
            sage: L([1, 2, 3, 1]).verschiebung(7)
            0
            sage: L([7]).verschiebung(7)
            L[1]
            sage: L([1, 2, 3, 1]).verschiebung(5)
            0
            sage: (L[1] - L[2] + 2*L[3]).verschiebung(1)
            L[1] - L[2] + 2*L[3]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> L = NSym.L()
            >>> L([Integer(4),Integer(2)]).verschiebung(Integer(2))
            -L[2, 1]
            >>> L([Integer(2),Integer(4)]).verschiebung(Integer(2))
            -L[1, 2]
            >>> L([Integer(6)]).verschiebung(Integer(2))
            -L[3]
            >>> L([Integer(2),Integer(1)]).verschiebung(Integer(3))
            0
            >>> L([Integer(3)]).verschiebung(Integer(2))
            0
            >>> L([]).verschiebung(Integer(2))
            L[]
            >>> L([Integer(5), Integer(1)]).verschiebung(Integer(3))
            0
            >>> L([Integer(5), Integer(1)]).verschiebung(Integer(6))
            0
            >>> L([Integer(5), Integer(1)]).verschiebung(Integer(2))
            0
            >>> L([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(7))
            0
            >>> L([Integer(7)]).verschiebung(Integer(7))
            L[1]
            >>> L([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(5))
            0
            >>> (L[Integer(1)] - L[Integer(2)] + Integer(2)*L[Integer(3)]).verschiebung(Integer(1))
            L[1] - L[2] + 2*L[3]

  I

    alias of `Immaculate`

  class Immaculate(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The immaculate basis of the non-commutative symmetric functions.

    The immaculate basis first appears in Berg, Bergeron, Saliola, Serrano and Zabrocki’s [BBSSZ2012]. It can be described as the family \((\mathfrak{S}_{\alpha})\), where \(\alpha\) runs over all compositions, and \(\mathfrak{S}_{\alpha}\) denotes the immaculate function corresponding to \(\alpha\) (see `immaculate_function()`).

    If \(\alpha\) is a composition \((\alpha_1, \alpha_2, \ldots, \alpha_m)\), then

    \[\mathfrak{S}_{\alpha} = \sum_{\sigma \in S_m} (-1)^{\sigma} S_{\alpha_1 + \sigma(1) - 1} S_{\alpha_2 + \sigma(2) - 2} \cdots S_{\alpha_m + \sigma(m) - m}.\]

    Warning

    This basis contains only the immaculate functions indexed by compositions (i.e., finite sequences of positive integers). To obtain the remaining immaculate functions (sensu lato), use the `immaculate_function()` method. Calling the immaculate basis with a list which is not a composition will currently return garbage!

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: I = NCSF.I()
        sage: I([1,3,2])*I([1])
        I[1, 3, 2, 1] + I[1, 3, 3] + I[1, 4, 2] + I[2, 3, 2]
        sage: I([1])*I([1,3,2])
        I[1, 1, 3, 2] - I[2, 2, 1, 2] - I[2, 2, 2, 1] - I[2, 2, 3] - I[3, 2, 2]
        sage: I([1,3])*I([1,1])
        I[1, 3, 1, 1] + I[1, 4, 1] + I[2, 3, 1] + I[2, 4]
        sage: I([3,1])*I([2,1])
        I[3, 1, 2, 1] + I[3, 2, 1, 1] + I[3, 2, 2] + I[3, 3, 1] + I[4, 1, 1, 1] + I[4, 1, 2] + 2*I[4, 2, 1] + I[4, 3] + I[5, 1, 1] + I[5, 2]
        sage: R = NCSF.ribbon()
        sage: I(R[1,3,1])
        I[1, 3, 1] + I[2, 2, 1] + I[2, 3] + I[3, 1, 1] + I[3, 2]
        sage: R(I(R([2,1,3])))
        R[2, 1, 3]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> I = NCSF.I()
        >>> I([Integer(1),Integer(3),Integer(2)])*I([Integer(1)])
        I[1, 3, 2, 1] + I[1, 3, 3] + I[1, 4, 2] + I[2, 3, 2]
        >>> I([Integer(1)])*I([Integer(1),Integer(3),Integer(2)])
        I[1, 1, 3, 2] - I[2, 2, 1, 2] - I[2, 2, 2, 1] - I[2, 2, 3] - I[3, 2, 2]
        >>> I([Integer(1),Integer(3)])*I([Integer(1),Integer(1)])
        I[1, 3, 1, 1] + I[1, 4, 1] + I[2, 3, 1] + I[2, 4]
        >>> I([Integer(3),Integer(1)])*I([Integer(2),Integer(1)])
        I[3, 1, 2, 1] + I[3, 2, 1, 1] + I[3, 2, 2] + I[3, 3, 1] + I[4, 1, 1, 1] + I[4, 1, 2] + 2*I[4, 2, 1] + I[4, 3] + I[5, 1, 1] + I[5, 2]
        >>> R = NCSF.ribbon()
        >>> I(R[Integer(1),Integer(3),Integer(1)])
        I[1, 3, 1] + I[2, 2, 1] + I[2, 3] + I[3, 1, 1] + I[3, 2]
        >>> R(I(R([Integer(2),Integer(1),Integer(3)])))
        R[2, 1, 3]

    class Element

      Bases: `IndexedFreeModuleElement`

      An element in the Immaculate basis.

      bernstein_creation_operator(n)

        Return the image of `self` under the \(n\)-th Bernstein creation operator.

        Let \(n\) be an integer. The \(n\)-th Bernstein creation operator \(\mathbb{B}_n\) is defined as the endomorphism of the space \(NSym\) of noncommutative symmetric functions given by

        \[\mathbb{B}_n I_{(\alpha_1, \alpha_2, \ldots, \alpha_m)} = I_{(n, \alpha_1, \alpha_2, \ldots, \alpha_m)},\]

        where \(I_{(\alpha_1, \alpha_2, \ldots, \alpha_m)}\) is the immaculate function associated to the \(m\)-tuple \((\alpha_1, \alpha_2, \ldots, \alpha_m) \in \ZZ^m\).

        This has been introduced in [BBSSZ2012], section 3.1, in analogy to the Bernstein creation operators on the symmetric functions.

        For more information on the \(n\)-th Bernstein creation operator, see `bernstein_creation_operator()`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: I = NSym.I()
            sage: b = I[1,3,2,1]
            sage: b.bernstein_creation_operator(3)
            I[3, 1, 3, 2, 1]
            sage: b.bernstein_creation_operator(5)
            I[5, 1, 3, 2, 1]
            sage: elt = b + 3*I[4,1,2]
            sage: elt.bernstein_creation_operator(1)
            I[1, 1, 3, 2, 1] + 3*I[1, 4, 1, 2]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> I = NSym.I()
            >>> b = I[Integer(1),Integer(3),Integer(2),Integer(1)]
            >>> b.bernstein_creation_operator(Integer(3))
            I[3, 1, 3, 2, 1]
            >>> b.bernstein_creation_operator(Integer(5))
            I[5, 1, 3, 2, 1]
            >>> elt = b + Integer(3)*I[Integer(4),Integer(1),Integer(2)]
            >>> elt.bernstein_creation_operator(Integer(1))
            I[1, 1, 3, 2, 1] + 3*I[1, 4, 1, 2]

        We check that this agrees with the definition on the Complete basis:

        Sage

            sage: S = NSym.S()
            sage: S(elt).bernstein_creation_operator(1) == S(elt.bernstein_creation_operator(1))
            True

        [Python]

            >>> from sage.all import *
            >>> S = NSym.S()
            >>> S(elt).bernstein_creation_operator(Integer(1)) == S(elt.bernstein_creation_operator(Integer(1)))
            True

        Check on nonpositive values of \(n\):

        Sage

            sage: I[2,2,2].bernstein_creation_operator(-1)
            I[1, 1, 1, 2] + I[1, 1, 2, 1] + I[1, 2, 1, 1] - I[1, 2, 2]
            sage: I[2,3,2].bernstein_creation_operator(0)
            -I[1, 1, 3, 2] - I[1, 2, 2, 2] - I[1, 2, 3, 1] + I[2, 3, 2]

        Python

            >>> from sage.all import *
            >>> I[Integer(2),Integer(2),Integer(2)].bernstein_creation_operator(-Integer(1))
            I[1, 1, 1, 2] + I[1, 1, 2, 1] + I[1, 2, 1, 1] - I[1, 2, 2]
            >>> I[Integer(2),Integer(3),Integer(2)].bernstein_creation_operator(Integer(0))
            -I[1, 1, 3, 2] - I[1, 2, 2, 2] - I[1, 2, 3, 1] + I[2, 3, 2]

    dual()

      Return the dual basis to the Immaculate basis of NCSF.

      The basis returned is the dualImmaculate basis of QSym.

      OUTPUT: the dualImmaculate basis of the quasi-symmetric functions

      EXAMPLES:

      Sage

          sage: I = NonCommutativeSymmetricFunctions(QQ).Immaculate()
          sage: I.dual()
          Quasisymmetric functions over the Rational Field in the dualImmaculate
          basis

      Python

          >>> from sage.all import *
          >>> I = NonCommutativeSymmetricFunctions(QQ).Immaculate()
          >>> I.dual()
          Quasisymmetric functions over the Rational Field in the dualImmaculate
          basis

  L

    alias of `Elementary`

  class Monomial(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The monomial basis defined in Tevlin’s paper [Tev2007].

    The monomial basis is well-defined only when the base ring is a \(\QQ\)-algebra. It is the basis denoted by \((M^I)_I\) in [Tev2007].

  class MultiplicativeBases(parent_with_realization)

    Bases: `Category_realization_of_parent`

    Category of multiplicative bases of non-commutative symmetric functions.

    EXAMPLES:

    Sage

        sage: N = NonCommutativeSymmetricFunctions(QQ)
        sage: N.MultiplicativeBases()
        Category of multiplicative bases of Non-Commutative Symmetric Functions over the Rational Field

    Python

        >>> from sage.all import *
        >>> N = NonCommutativeSymmetricFunctions(QQ)
        >>> N.MultiplicativeBases()
        Category of multiplicative bases of Non-Commutative Symmetric Functions over the Rational Field

    The complete basis is a multiplicative basis, but the ribbon basis is not:

    Sage

        sage: N.Complete() in N.MultiplicativeBases()
        True
        sage: N.Ribbon() in N.MultiplicativeBases()
        False

    [Python]

        >>> from sage.all import *
        >>> N.Complete() in N.MultiplicativeBases()
        True
        >>> N.Ribbon() in N.MultiplicativeBases()
        False

    class ParentMethods

      Bases: `object`

      algebra_generators()

        Return the algebra generators of a given multiplicative basis of non-commutative symmetric functions.

        OUTPUT: the family of generators of the multiplicative basis `self`

        EXAMPLES:

        Sage

            sage: Psi = NonCommutativeSymmetricFunctions(QQ).Psi()
            sage: f = Psi.algebra_generators()
            sage: f
            Lazy family (<lambda>(i))_{i in Positive integers}
            sage: f[1], f[2], f[3]
            (Psi[1], Psi[2], Psi[3])

        Python

            >>> from sage.all import *
            >>> Psi = NonCommutativeSymmetricFunctions(QQ).Psi()
            >>> f = Psi.algebra_generators()
            >>> f
            Lazy family (<lambda>(i))_{i in Positive integers}
            >>> f[Integer(1)], f[Integer(2)], f[Integer(3)]
            (Psi[1], Psi[2], Psi[3])

      algebra_morphism(on_generators, **keywords)

        Given a map defined on the generators of the multiplicative basis `self`, return the algebra morphism that extends this map to the whole algebra of non-commutative symmetric functions.

        INPUT:

        - `on_generators` – a function defined on the index set of the generators (that is, on the positive integers)

        - `anti` – boolean (default: `False`)

        - `category` – a category (default: `None`)

        OUTPUT:

        - The algebra morphism of `self` which is defined by `on_generators` in the basis `self`. When `anti` is set to `True`, an algebra anti-morphism is computed instead of an algebra morphism.

        EXAMPLES:

        Sage

            sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
            sage: Psi = NCSF.Psi()
            sage: double = lambda i: Psi[i,i]
            sage: f = Psi.algebra_morphism(double, codomain = Psi)
            sage: f
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
            sage: f(2*Psi[[]] + 3 * Psi[1,3,2] + Psi[2,4] )
            2*Psi[] + 3*Psi[1, 1, 3, 3, 2, 2] + Psi[2, 2, 4, 4]
            sage: f.category()
            Category of endsets of unital magmas and right modules over Rational Field and left modules over Rational Field

        Python

            >>> from sage.all import *
            >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
            >>> Psi = NCSF.Psi()
            >>> double = lambda i: Psi[i,i]
            >>> f = Psi.algebra_morphism(double, codomain = Psi)
            >>> f
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
            >>> f(Integer(2)*Psi[[]] + Integer(3) * Psi[Integer(1),Integer(3),Integer(2)] + Psi[Integer(2),Integer(4)] )
            2*Psi[] + 3*Psi[1, 1, 3, 3, 2, 2] + Psi[2, 2, 4, 4]
            >>> f.category()
            Category of endsets of unital magmas and right modules over Rational Field and left modules over Rational Field

        When extra properties about the morphism are known, one can specify the category of which it is a morphism:

        Sage

            sage: negate = lambda i: -Psi[i]
            sage: f = Psi.algebra_morphism(negate, codomain = Psi, category = GradedHopfAlgebrasWithBasis(QQ))
            sage: f
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
            sage: f(2*Psi[[]] + 3 * Psi[1,3,2] + Psi[2,4] )
            2*Psi[] - 3*Psi[1, 3, 2] + Psi[2, 4]
            sage: f.category()
            Category of endsets of Hopf algebras over Rational Field and graded modules over Rational Field

        [Python]

            >>> from sage.all import *
            >>> negate = lambda i: -Psi[i]
            >>> f = Psi.algebra_morphism(negate, codomain = Psi, category = GradedHopfAlgebrasWithBasis(QQ))
            >>> f
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
            >>> f(Integer(2)*Psi[[]] + Integer(3) * Psi[Integer(1),Integer(3),Integer(2)] + Psi[Integer(2),Integer(4)] )
            2*Psi[] - 3*Psi[1, 3, 2] + Psi[2, 4]
            >>> f.category()
            Category of endsets of Hopf algebras over Rational Field and graded modules over Rational Field

        If `anti` is true, this returns an anti-algebra morphism:

        Sage

            sage: f = Psi.algebra_morphism(double, codomain = Psi, anti=True)
            sage: f
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
            sage: f(2*Psi[[]] + 3 * Psi[1,3,2] + Psi[2,4] )
            2*Psi[] + 3*Psi[2, 2, 3, 3, 1, 1] + Psi[4, 4, 2, 2]
            sage: f.category()
            Category of endsets of modules with basis over Rational Field

        Python

            >>> from sage.all import *
            >>> f = Psi.algebra_morphism(double, codomain = Psi, anti=True)
            >>> f
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
            >>> f(Integer(2)*Psi[[]] + Integer(3) * Psi[Integer(1),Integer(3),Integer(2)] + Psi[Integer(2),Integer(4)] )
            2*Psi[] + 3*Psi[2, 2, 3, 3, 1, 1] + Psi[4, 4, 2, 2]
            >>> f.category()
            Category of endsets of modules with basis over Rational Field

      antipode()

        Return the antipode morphism on the basis `self`.

        The antipode of \(NSym\) is closely related to the omega involution; see `omega_involution()` for the latter.

        OUTPUT:

        - The antipode module map from non-commutative symmetric functions on basis `self`.

        EXAMPLES:

        Sage

            sage: S = NonCommutativeSymmetricFunctions(QQ).S()
            sage: S.antipode
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Complete basis

        Python

            >>> from sage.all import *
            >>> S = NonCommutativeSymmetricFunctions(QQ).S()
            >>> S.antipode
            Generic endomorphism of Non-Commutative Symmetric Functions over the Rational Field in the Complete basis

      coproduct()

        Return the coproduct morphism in the basis `self`.

        OUTPUT:

        - The coproduct module map from non-commutative symmetric functions on basis `self`.

        EXAMPLES:

        Sage

            sage: S = NonCommutativeSymmetricFunctions(QQ).S()
            sage: S.coproduct
            Generic morphism:
              From: Non-Commutative Symmetric Functions over the Rational Field in the Complete basis
              To:   Non-Commutative Symmetric Functions over the Rational Field in the Complete basis # Non-Commutative Symmetric Functions over the Rational Field in the Complete basis

        Python

            >>> from sage.all import *
            >>> S = NonCommutativeSymmetricFunctions(QQ).S()
            >>> S.coproduct
            Generic morphism:
              From: Non-Commutative Symmetric Functions over the Rational Field in the Complete basis
              To:   Non-Commutative Symmetric Functions over the Rational Field in the Complete basis # Non-Commutative Symmetric Functions over the Rational Field in the Complete basis

      product_on_basis(composition1, composition2)

        Return the product of two basis elements from the multiplicative basis. Multiplication is just concatenation on compositions.

        INPUT:

        - `composition1`, `composition2` – integer compositions

        OUTPUT:

        - The product of the two non-commutative symmetric functions indexed by `composition1` and `composition2` in the multiplicative basis `self`. This will be again a non-commutative symmetric function.

        EXAMPLES:

        Sage

            sage: Psi = NonCommutativeSymmetricFunctions(QQ).Psi()
            sage: Psi[3,1,2] * Psi[4,2] == Psi[3,1,2,4,2]
            True
            sage: S = NonCommutativeSymmetricFunctions(QQ).S()
            sage: S.product_on_basis(Composition([2,1]), Composition([1,2]))
            S[2, 1, 1, 2]

        Python

            >>> from sage.all import *
            >>> Psi = NonCommutativeSymmetricFunctions(QQ).Psi()
            >>> Psi[Integer(3),Integer(1),Integer(2)] * Psi[Integer(4),Integer(2)] == Psi[Integer(3),Integer(1),Integer(2),Integer(4),Integer(2)]
            True
            >>> S = NonCommutativeSymmetricFunctions(QQ).S()
            >>> S.product_on_basis(Composition([Integer(2),Integer(1)]), Composition([Integer(1),Integer(2)]))
            S[2, 1, 1, 2]

      to_symmetric_function()

        Morphism to the algebra of symmetric functions.

        This is constructed by extending the algebra morphism by the image of the generators.

        OUTPUT:

        - The module morphism from the basis `self` to the symmetric functions which corresponds to taking a commutative image.

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: S = N.complete()
            sage: S.to_symmetric_function(S[1,3])
            h[3, 1]
            sage: Phi = N.Phi()
            sage: Phi.to_symmetric_function(Phi[1,3])
            h[1, 1, 1, 1] - 3*h[2, 1, 1] + 3*h[3, 1]
            sage: Psi = N.Psi()
            sage: Psi.to_symmetric_function(Psi[1,3])
            h[1, 1, 1, 1] - 3*h[2, 1, 1] + 3*h[3, 1]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> S = N.complete()
            >>> S.to_symmetric_function(S[Integer(1),Integer(3)])
            h[3, 1]
            >>> Phi = N.Phi()
            >>> Phi.to_symmetric_function(Phi[Integer(1),Integer(3)])
            h[1, 1, 1, 1] - 3*h[2, 1, 1] + 3*h[3, 1]
            >>> Psi = N.Psi()
            >>> Psi.to_symmetric_function(Psi[Integer(1),Integer(3)])
            h[1, 1, 1, 1] - 3*h[2, 1, 1] + 3*h[3, 1]

      to_symmetric_function_on_generators(i)

        Morphism of the generators to symmetric functions.

        This is constructed by coercion to the complete basis and applying the morphism.

        OUTPUT:

        - The module morphism from the basis `self` to the symmetric functions which corresponds to taking a commutative image.

        EXAMPLES:

        Sage

            sage: N = NonCommutativeSymmetricFunctions(QQ)
            sage: Phi = N.Phi()
            sage: Phi.to_symmetric_function_on_generators(3)
            h[1, 1, 1] - 3*h[2, 1] + 3*h[3]
            sage: Phi.to_symmetric_function_on_generators(0)
            h[]
            sage: Psi = N.Psi()
            sage: Psi.to_symmetric_function_on_generators(3)
            h[1, 1, 1] - 3*h[2, 1] + 3*h[3]
            sage: L = N.elementary()
            sage: L.to_symmetric_function_on_generators(3)
            h[1, 1, 1] - 2*h[2, 1] + h[3]

        Python

            >>> from sage.all import *
            >>> N = NonCommutativeSymmetricFunctions(QQ)
            >>> Phi = N.Phi()
            >>> Phi.to_symmetric_function_on_generators(Integer(3))
            h[1, 1, 1] - 3*h[2, 1] + 3*h[3]
            >>> Phi.to_symmetric_function_on_generators(Integer(0))
            h[]
            >>> Psi = N.Psi()
            >>> Psi.to_symmetric_function_on_generators(Integer(3))
            h[1, 1, 1] - 3*h[2, 1] + 3*h[3]
            >>> L = N.elementary()
            >>> L.to_symmetric_function_on_generators(Integer(3))
            h[1, 1, 1] - 2*h[2, 1] + h[3]

    super_categories()

      Return the super categories of the category of multiplicative bases of the non-commutative symmetric functions.

      OUTPUT: list

  class MultiplicativeBasesOnGroupLikeElements(parent_with_realization)

    Bases: `Category_realization_of_parent`

    Category of multiplicative bases on grouplike elements of non-commutative symmetric functions.

    Here, a “multiplicative basis on grouplike elements” means a multiplicative basis whose generators \((f_1, f_2, f_3, \ldots )\) satisfy

    \[\Delta(f_i) = \sum_{j=0}^{i} f_j \otimes f_{i-j}\]

    with \(f_0 = 1\). (In other words, the generators are to form a divided power sequence in the sense of a coalgebra.) This does not mean that the generators are grouplike, but means that the element \(1 + f_1 + f_2 + f_3 + \cdots\) in the completion of the ring of non-commutative symmetric functions with respect to the grading is grouplike.

    EXAMPLES:

    Sage

        sage: N = NonCommutativeSymmetricFunctions(QQ)
        sage: N.MultiplicativeBasesOnGroupLikeElements()
        Category of multiplicative bases on group like elements of Non-Commutative Symmetric Functions over the Rational Field

    Python

        >>> from sage.all import *
        >>> N = NonCommutativeSymmetricFunctions(QQ)
        >>> N.MultiplicativeBasesOnGroupLikeElements()
        Category of multiplicative bases on group like elements of Non-Commutative Symmetric Functions over the Rational Field

    The complete basis is a multiplicative basis, but the ribbon basis is not:

    Sage

        sage: N.Complete() in N.MultiplicativeBasesOnGroupLikeElements()
        True
        sage: N.Ribbon() in N.MultiplicativeBasesOnGroupLikeElements()
        False

    [Python]

        >>> from sage.all import *
        >>> N.Complete() in N.MultiplicativeBasesOnGroupLikeElements()
        True
        >>> N.Ribbon() in N.MultiplicativeBasesOnGroupLikeElements()
        False

    class ParentMethods

      Bases: `object`

      antipode_on_basis(composition)

        Return the application of the antipode to a basis element.

        INPUT:

        - `composition` – a composition

        OUTPUT:

        - The image of the basis element indexed by `composition` under the antipode map.

        EXAMPLES:

        Sage

            sage: S = NonCommutativeSymmetricFunctions(QQ).complete()
            sage: S.antipode_on_basis(Composition([2,1]))
            -S[1, 1, 1] + S[1, 2]
            sage: S[1].antipode() # indirect doctest
            -S[1]
            sage: S[2].antipode() # indirect doctest
            S[1, 1] - S[2]
            sage: S[3].antipode() # indirect doctest
            -S[1, 1, 1] + S[1, 2] + S[2, 1] - S[3]
            sage: S[2,3].coproduct().apply_multilinear_morphism(lambda be,ga: S(be)*S(ga).antipode())
            0
            sage: S[2,3].coproduct().apply_multilinear_morphism(lambda be,ga: S(be).antipode()*S(ga))
            0

        Python

            >>> from sage.all import *
            >>> S = NonCommutativeSymmetricFunctions(QQ).complete()
            >>> S.antipode_on_basis(Composition([Integer(2),Integer(1)]))
            -S[1, 1, 1] + S[1, 2]
            >>> S[Integer(1)].antipode() # indirect doctest
            -S[1]
            >>> S[Integer(2)].antipode() # indirect doctest
            S[1, 1] - S[2]
            >>> S[Integer(3)].antipode() # indirect doctest
            -S[1, 1, 1] + S[1, 2] + S[2, 1] - S[3]
            >>> S[Integer(2),Integer(3)].coproduct().apply_multilinear_morphism(lambda be,ga: S(be)*S(ga).antipode())
            0
            >>> S[Integer(2),Integer(3)].coproduct().apply_multilinear_morphism(lambda be,ga: S(be).antipode()*S(ga))
            0

      coproduct_on_generators(i)

        Return the image of the \(i\)-th generator of the algebra under the coproduct.

        INPUT:

        - `i` – positive integer

        OUTPUT: the result of applying the coproduct to the \(i\)-th generator of `self`

        EXAMPLES:

        Sage

            sage: S = NonCommutativeSymmetricFunctions(QQ).complete()
            sage: S.coproduct_on_generators(3)
            S[] # S[3] + S[1] # S[2] + S[2] # S[1] + S[3] # S[]

        Python

            >>> from sage.all import *
            >>> S = NonCommutativeSymmetricFunctions(QQ).complete()
            >>> S.coproduct_on_generators(Integer(3))
            S[] # S[3] + S[1] # S[2] + S[2] # S[1] + S[3] # S[]

    super_categories()

      Return the super categories of the category of multiplicative bases of group-like elements of the non-commutative symmetric functions.

      OUTPUT: list

  class MultiplicativeBasesOnPrimitiveElements(parent_with_realization)

    Bases: `Category_realization_of_parent`

    Category of multiplicative bases of the non-commutative symmetric functions whose generators are primitive elements.

    An element \(x\) of a bialgebra is primitive if \(\Delta(x) = x \otimes 1 + 1 \otimes x\), where \(\Delta\) is the coproduct of the bialgebra.

    Given a multiplicative basis and knowing the coproducts and antipodes of its generators, one can compute the coproduct and the antipode of any element, since they are respectively algebra morphisms and anti-morphisms. See `antipode_on_generators()` and `coproduct_on_generators()`.

    Todo

    this could be generalized to any free algebra.

    EXAMPLES:

    Sage

        sage: N = NonCommutativeSymmetricFunctions(QQ)
        sage: N.MultiplicativeBasesOnPrimitiveElements()
        Category of multiplicative bases on primitive elements of Non-Commutative Symmetric Functions over the Rational Field

    Python

        >>> from sage.all import *
        >>> N = NonCommutativeSymmetricFunctions(QQ)
        >>> N.MultiplicativeBasesOnPrimitiveElements()
        Category of multiplicative bases on primitive elements of Non-Commutative Symmetric Functions over the Rational Field

    The Phi and Psi bases are multiplicative bases whose generators are primitive elements, but the complete and ribbon bases are not:

    Sage

        sage: N.Phi() in N.MultiplicativeBasesOnPrimitiveElements()
        True
        sage: N.Psi() in N.MultiplicativeBasesOnPrimitiveElements()
        True
        sage: N.Complete() in N.MultiplicativeBasesOnPrimitiveElements()
        False
        sage: N.Ribbon() in N.MultiplicativeBasesOnPrimitiveElements()
        False

    [Python]

        >>> from sage.all import *
        >>> N.Phi() in N.MultiplicativeBasesOnPrimitiveElements()
        True
        >>> N.Psi() in N.MultiplicativeBasesOnPrimitiveElements()
        True
        >>> N.Complete() in N.MultiplicativeBasesOnPrimitiveElements()
        False
        >>> N.Ribbon() in N.MultiplicativeBasesOnPrimitiveElements()
        False

    class ParentMethods

      Bases: `object`

      antipode_on_generators(i)

        Return the image of a generator of a primitive basis of the non-commutative symmetric functions under the antipode map.

        INPUT:

        - `i` – positive integer

        OUTPUT:

        The image of the \(i\)-th generator of the multiplicative basis `self` under the antipode of the algebra of non-commutative symmetric functions.

        EXAMPLES:

        Sage

            sage: Psi=NonCommutativeSymmetricFunctions(QQ).Psi()
            sage: Psi.antipode_on_generators(2)
            -Psi[2]

        Python

            >>> from sage.all import *
            >>> Psi=NonCommutativeSymmetricFunctions(QQ).Psi()
            >>> Psi.antipode_on_generators(Integer(2))
            -Psi[2]

      coproduct_on_generators(i)

        Return the image of the \(i\)-th generator of the multiplicative basis `self` under the coproduct.

        INPUT:

        - `i` – positive integer

        OUTPUT: the result of applying the coproduct to the \(i\)-th generator of `self`

        EXAMPLES:

        Sage

            sage: Psi = NonCommutativeSymmetricFunctions(QQ).Psi()
            sage: Psi.coproduct_on_generators(3)
            Psi[] # Psi[3] + Psi[3] # Psi[]

        Python

            >>> from sage.all import *
            >>> Psi = NonCommutativeSymmetricFunctions(QQ).Psi()
            >>> Psi.coproduct_on_generators(Integer(3))
            Psi[] # Psi[3] + Psi[3] # Psi[]

    super_categories()

      Return the super categories of the category of multiplicative bases of primitive elements of the non-commutative symmetric functions.

      OUTPUT: list

  class Phi(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the Phi basis.

    The Phi basis is defined in Definition 3.4 of [NCSF1], where it is denoted by \((\Phi^I)_I\). It is a multiplicative basis, and is connected to the elementary generators \(\Lambda_i\) of the ring of non-commutative symmetric functions by the following relation: Define a non-commutative symmetric function \(\Phi_n\) for every positive integer \(n\) by the power series identity

    \[\sum_{k\geq 1} t^k \frac{1}{k} \Phi_k = -\log \left( \sum_{k \geq 0} (-t)^k \Lambda_k \right),\]

    with \(\Lambda_0\) denoting \(1\). For every composition \((i_1, i_2, \ldots, i_k)\), we have \(\Phi^{(i_1, i_2, \ldots, i_k)} = \Phi_{i_1} \Phi_{i_2} \cdots \Phi_{i_k}\).

    The \(\Phi\)-basis is well-defined only when the base ring is a \(\QQ\)-algebra. The elements of the \(\Phi\)-basis are known as the “power-sum non-commutative symmetric functions of the second kind”.

    The generators \(\Phi_n\) are related to the (first) Eulerian idempotents in the descent algebras of the symmetric groups (see [NCSF1], 5.4 for details).

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: Phi = NCSF.Phi(); Phi
        Non-Commutative Symmetric Functions over the Rational Field in the Phi basis
        sage: Phi.an_element()
        2*Phi[] + 2*Phi[1] + 3*Phi[1, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> Phi = NCSF.Phi(); Phi
        Non-Commutative Symmetric Functions over the Rational Field in the Phi basis
        >>> Phi.an_element()
        2*Phi[] + 2*Phi[1] + 3*Phi[1, 1]

    class Element

      Bases: `IndexedFreeModuleElement`

      psi_involution()

        Return the image of the noncommutative symmetric function `self` under the involution \(\psi\).

        The involution \(\psi\) is defined as the linear map \(NCSF \to NCSF\) which, for every composition \(I\), sends the complete noncommutative symmetric function \(S^I\) to the elementary noncommutative symmetric function \(\Lambda^I\). It can be shown that every composition \(I\) satisfies

        \[\psi(R_I) = R_{I^c}, \quad \psi(S^I) = \Lambda^I, \quad \psi(\Lambda^I) = S^I, \quad \psi(\Phi^I) = (-1)^{|I| - \ell(I)} \Phi^I\]

        where \(I^c\) denotes the complement of the composition \(I\), and \(\ell(I)\) denotes the length of \(I\), and where standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(\Phi\) for the basis of the power sums of the second kind, and \(R\) for the ribbon basis). The map \(\psi\) is an involution and a graded Hopf algebra automorphism of \(NCSF\). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(\psi(f)) = \omega(\pi(f))\) for every \(f \in NCSF\), where the \(\omega\) on the right hand side denotes the omega automorphism of \(Sym\).

        The involution \(\psi\) of \(NCSF\) is adjoint to the involution \(\psi\) of \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The involution \(\psi\) has been denoted by \(\psi\) in [LMvW13], section 3.6.

        See also

        `psi involution of NCSF`, `psi involution of QSym`, `star involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: Phi = NSym.Phi()
            sage: Phi[3,2].psi_involution()
            -Phi[3, 2]
            sage: Phi[2,2].psi_involution()
            Phi[2, 2]
            sage: Phi[[]].psi_involution()
            Phi[]
            sage: (Phi[2,1] - 2*Phi[2]).psi_involution()
            2*Phi[2] - Phi[2, 1]
            sage: Phi(0).psi_involution()
            0

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> Phi = NSym.Phi()
            >>> Phi[Integer(3),Integer(2)].psi_involution()
            -Phi[3, 2]
            >>> Phi[Integer(2),Integer(2)].psi_involution()
            Phi[2, 2]
            >>> Phi[[]].psi_involution()
            Phi[]
            >>> (Phi[Integer(2),Integer(1)] - Integer(2)*Phi[Integer(2)]).psi_involution()
            2*Phi[2] - Phi[2, 1]
            >>> Phi(Integer(0)).psi_involution()
            0

        The implementation at hand is tailored to the Phi basis. It is equivalent to the generic implementation via the ribbon basis:

        Sage

            sage: R = NSym.R()
            sage: all( R(Phi[I].psi_involution()) == R(Phi[I]).psi_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> R = NSym.R()
            >>> all( R(Phi[I].psi_involution()) == R(Phi[I]).psi_involution()
            ...      for I in Compositions(Integer(4)) )
            True

      star_involution()

        Return the image of the noncommutative symmetric function `self` under the star involution.

        The star involution is defined as the algebra antihomomorphism \(NCSF \to NCSF\) which, for every positive integer \(n\), sends the \(n\)-th complete non-commutative symmetric function \(S_n\) to \(S_n\). Denoting by \(f^{\ast}\) the image of an element \(f \in NCSF\) under this star involution, it can be shown that every composition \(I\) satisfies

        \[(S^I)^{\ast} = S^{I^r}, \quad (\Lambda^I)^{\ast} = \Lambda^{I^r}, \quad R_I^{\ast} = R_{I^r}, \quad (\Phi^I)^{\ast} = \Phi^{I^r},\]

        where \(I^r\) denotes the reversed composition of \(I\), and standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(R\) for the ribbon basis, and \(\Phi\) for that of the power-sums of the second kind). The star involution is an involution and a coalgebra automorphism of \(NCSF\). It is an automorphism of the graded vector space \(NCSF\). Under the canonical isomorphism between the \(n\)-th graded component of \(NCSF\) and the descent algebra of the symmetric group \(S_n\) (see `to_descent_algebra()`), the star involution (restricted to the \(n\)-th graded component) corresponds to the automorphism of the descent algebra given by \(x \mapsto \omega_n x \omega_n\), where \(\omega_n\) is the permutation \((n, n-1, \ldots, 1) \in S_n\) (written here in one-line notation). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(f^{\ast}) = \pi(f)\) for every \(f \in NCSF\).

        The star involution on \(NCSF\) is adjoint to the star involution on \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The star involution has been denoted by \(\rho\) in [LMvW13], section 3.6. See [NCSF2], section 2.3 for the properties of this map.

        See also

        `star involution of NCSF`, `psi involution of NCSF`, `star involution of QSym`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(QQ)
            sage: Phi = NSym.Phi()
            sage: Phi[3,1,1,4].star_involution()
            Phi[4, 1, 1, 3]
            sage: Phi[4,2,1].star_involution()
            Phi[1, 2, 4]
            sage: (Phi[1,4] - Phi[2,3] + 2*Phi[5,4] - 3*Phi[3] + 4*Phi[[]]).star_involution()
            4*Phi[] - 3*Phi[3] - Phi[3, 2] + Phi[4, 1] + 2*Phi[4, 5]
            sage: (Phi[3,3] + 3*Phi[1]).star_involution()
            3*Phi[1] + Phi[3, 3]
            sage: Phi([2,1]).star_involution()
            Phi[1, 2]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(QQ)
            >>> Phi = NSym.Phi()
            >>> Phi[Integer(3),Integer(1),Integer(1),Integer(4)].star_involution()
            Phi[4, 1, 1, 3]
            >>> Phi[Integer(4),Integer(2),Integer(1)].star_involution()
            Phi[1, 2, 4]
            >>> (Phi[Integer(1),Integer(4)] - Phi[Integer(2),Integer(3)] + Integer(2)*Phi[Integer(5),Integer(4)] - Integer(3)*Phi[Integer(3)] + Integer(4)*Phi[[]]).star_involution()
            4*Phi[] - 3*Phi[3] - Phi[3, 2] + Phi[4, 1] + 2*Phi[4, 5]
            >>> (Phi[Integer(3),Integer(3)] + Integer(3)*Phi[Integer(1)]).star_involution()
            3*Phi[1] + Phi[3, 3]
            >>> Phi([Integer(2),Integer(1)]).star_involution()
            Phi[1, 2]

        The implementation at hand is tailored to the Phi basis. It is equivalent to the generic implementation via the complete basis:

        Sage

            sage: S = NSym.S()
            sage: all( S(Phi[I].star_involution()) == S(Phi[I]).star_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> S = NSym.S()
            >>> all( S(Phi[I].star_involution()) == S(Phi[I]).star_involution()
            ...      for I in Compositions(Integer(4)) )
            True

      verschiebung(n)

        Return the image of the noncommutative symmetric function `self` under the \(n\)-th Verschiebung operator.

        The \(n\)-th Verschiebung operator \(\mathbf{V}_n\) is defined to be the map from the \(\mathbf{k}\)-algebra of noncommutative symmetric functions to itself that sends the complete function \(S^I\) indexed by a composition \(I = (i_1, i_2, \ldots , i_k)\) to \(S^{(i_1/n, i_2/n, \ldots , i_k/n)}\) if all of the numbers \(i_1, i_2, \ldots, i_k\) are divisible by \(n\), and to \(0\) otherwise. This operator \(\mathbf{V}_n\) is a Hopf algebra endomorphism. For every positive integer \(r\) with \(n \mid r\), it satisfies

        \[\mathbf{V}_n(S_r) = S_{r/n}, \quad \mathbf{V}_n(\Lambda_r) = (-1)^{r - r/n} \Lambda_{r/n}, \quad \mathbf{V}_n(\Psi_r) = n \Psi_{r/n}, \quad \mathbf{V}_n(\Phi_r) = n \Phi_{r/n}\]

        (where \(S_r\) denotes the \(r\)-th complete non-commutative symmetric function, \(\Lambda_r\) denotes the \(r\)-th elementary non-commutative symmetric function, \(\Psi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the first kind, and \(\Phi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the second kind). For every positive integer \(r\) with \(n \nmid r\), it satisfes

        \[\mathbf{V}_n(S_r) = \mathbf{V}_n(\Lambda_r) = \mathbf{V}_n(\Psi_r) = \mathbf{V}_n(\Phi_r) = 0.\]

        The \(n\)-th Verschiebung operator is also called the \(n\)-th Verschiebung endomorphism.

        It is a lift of the \(n\)-th Verschiebung operator on the ring of symmetric functions (`verschiebung()`) to the ring of noncommutative symmetric functions.

        The action of the \(n\)-th Verschiebung operator can also be described on the ribbon Schur functions. Namely, every composition \(I\) of size \(n \ell\) satisfies

        \[\mathbf{V}_n ( R_I ) = (-1)^{\ell(I) - \ell(J)} \cdot R_{J / n},\]

        where \(J\) denotes the meet of the compositions \(I\) and \((\underbrace{n, n, \ldots, n}_{|I|/n \mbox{ times}})\), where \(\ell(I)\) is the length of \(I\), and where \(J / n\) denotes the composition obtained by dividing every entry of \(J\) by \(n\). For a composition \(I\) of size not divisible by \(n\), we have \(\mathbf{V}_n ( R_I ) = 0\).

        See also

        `verschiebung method of NCSF`, `adams_operator method of QSym`, `verschiebung method of Sym`

        INPUT:

        - `n` – positive integer

        OUTPUT:

        The result of applying the \(n\)-th Verschiebung operator (on the ring of noncommutative symmetric functions) to `self`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: Phi = NSym.Phi()
            sage: Phi([4,2]).verschiebung(2)
            4*Phi[2, 1]
            sage: Phi([2,4]).verschiebung(2)
            4*Phi[1, 2]
            sage: Phi([6]).verschiebung(2)
            2*Phi[3]
            sage: Phi([2,1]).verschiebung(3)
            0
            sage: Phi([3]).verschiebung(2)
            0
            sage: Phi([]).verschiebung(2)
            Phi[]
            sage: Phi([5, 1]).verschiebung(3)
            0
            sage: Phi([5, 1]).verschiebung(6)
            0
            sage: Phi([5, 1]).verschiebung(2)
            0
            sage: Phi([1, 2, 3, 1]).verschiebung(7)
            0
            sage: Phi([7]).verschiebung(7)
            7*Phi[1]
            sage: Phi([1, 2, 3, 1]).verschiebung(5)
            0
            sage: (Phi[1] - Phi[2] + 2*Phi[3]).verschiebung(1)
            Phi[1] - Phi[2] + 2*Phi[3]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> Phi = NSym.Phi()
            >>> Phi([Integer(4),Integer(2)]).verschiebung(Integer(2))
            4*Phi[2, 1]
            >>> Phi([Integer(2),Integer(4)]).verschiebung(Integer(2))
            4*Phi[1, 2]
            >>> Phi([Integer(6)]).verschiebung(Integer(2))
            2*Phi[3]
            >>> Phi([Integer(2),Integer(1)]).verschiebung(Integer(3))
            0
            >>> Phi([Integer(3)]).verschiebung(Integer(2))
            0
            >>> Phi([]).verschiebung(Integer(2))
            Phi[]
            >>> Phi([Integer(5), Integer(1)]).verschiebung(Integer(3))
            0
            >>> Phi([Integer(5), Integer(1)]).verschiebung(Integer(6))
            0
            >>> Phi([Integer(5), Integer(1)]).verschiebung(Integer(2))
            0
            >>> Phi([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(7))
            0
            >>> Phi([Integer(7)]).verschiebung(Integer(7))
            7*Phi[1]
            >>> Phi([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(5))
            0
            >>> (Phi[Integer(1)] - Phi[Integer(2)] + Integer(2)*Phi[Integer(3)]).verschiebung(Integer(1))
            Phi[1] - Phi[2] + 2*Phi[3]

  class Psi(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the Psi basis.

    The Psi basis is defined in Definition 3.4 of [NCSF1], where it is denoted by \((\Psi^I)_I\). It is a multiplicative basis, and is connected to the elementary generators \(\Lambda_i\) of the ring of non-commutative symmetric functions by the following relation: Define a non-commutative symmetric function \(\Psi_n\) for every positive integer \(n\) by the power series identity

    \[\frac{d}{dt} \sigma(t) = \sigma(t) \cdot \left( \sum_{k \geq 1} t^{k-1} \Psi_k \right),\]

    where

    \[\sigma(t) = \left( \sum_{k \geq 0} (-t)^k \Lambda_k \right)^{-1}\]

    and where \(\Lambda_0\) denotes \(1\). For every composition \((i_1, i_2, \ldots, i_k)\), we have \(\Psi^{(i_1, i_2, \ldots, i_k)} = \Psi_{i_1} \Psi_{i_2} \cdots \Psi_{i_k}\).

    The \(\Psi\)-basis is a basis only when the base ring is a \(\QQ\)-algebra (although the \(\Psi^I\) can be defined over any base ring). The elements of the \(\Psi\)-basis are known as the “power-sum non-commutative symmetric functions of the first kind”. The generators \(\Psi_n\) correspond to the Dynkin (quasi-)idempotents in the descent algebras of the symmetric groups (see [NCSF1], 5.2 for details).

    Another (equivalent) definition of \(\Psi_n\) is

    \[\Psi_n = \sum_{i=0}^{n-1} (-1)^i R_{1^i, n-i},\]

    where \(R\) denotes the ribbon basis of \(NCSF\), and where \(1^i\) stands for \(i\) repetitions of the integer \(1\).

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: Psi = NCSF.Psi(); Psi
        Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
        sage: Psi.an_element()
        2*Psi[] + 2*Psi[1] + 3*Psi[1, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> Psi = NCSF.Psi(); Psi
        Non-Commutative Symmetric Functions over the Rational Field in the Psi basis
        >>> Psi.an_element()
        2*Psi[] + 2*Psi[1] + 3*Psi[1, 1]

    Checking the equivalent definition of \(\Psi_n\):

    Sage

        sage: def test_psi(n):
        ....:     NCSF = NonCommutativeSymmetricFunctions(ZZ)
        ....:     R = NCSF.R()
        ....:     Psi = NCSF.Psi()
        ....:     a = R.sum([(-1) ** i * R[[1]*i + [n-i]]
        ....:                for i in range(n)])
        ....:     return a == R(Psi[n])
        sage: test_psi(2)
        True
        sage: test_psi(3)
        True
        sage: test_psi(4)
        True

    [Python]

        >>> from sage.all import *
        >>> def test_psi(n):
        ...     NCSF = NonCommutativeSymmetricFunctions(ZZ)
        ...     R = NCSF.R()
        ...     Psi = NCSF.Psi()
        ...     a = R.sum([(-Integer(1)) ** i * R[[Integer(1)]*i + [n-i]]
        ...                for i in range(n)])
        ...     return a == R(Psi[n])
        >>> test_psi(Integer(2))
        True
        >>> test_psi(Integer(3))
        True
        >>> test_psi(Integer(4))
        True

    class Element

      Bases: `IndexedFreeModuleElement`

      verschiebung(n)

        Return the image of the noncommutative symmetric function `self` under the \(n\)-th Verschiebung operator.

        The \(n\)-th Verschiebung operator \(\mathbf{V}_n\) is defined to be the map from the \(\mathbf{k}\)-algebra of noncommutative symmetric functions to itself that sends the complete function \(S^I\) indexed by a composition \(I = (i_1, i_2, \ldots , i_k)\) to \(S^{(i_1/n, i_2/n, \ldots , i_k/n)}\) if all of the numbers \(i_1, i_2, \ldots, i_k\) are divisible by \(n\), and to \(0\) otherwise. This operator \(\mathbf{V}_n\) is a Hopf algebra endomorphism. For every positive integer \(r\) with \(n \mid r\), it satisfies

        \[\mathbf{V}_n(S_r) = S_{r/n}, \quad \mathbf{V}_n(\Lambda_r) = (-1)^{r - r/n} \Lambda_{r/n}, \quad \mathbf{V}_n(\Psi_r) = n \Psi_{r/n}, \quad \mathbf{V}_n(\Phi_r) = n \Phi_{r/n}\]

        (where \(S_r\) denotes the \(r\)-th complete non-commutative symmetric function, \(\Lambda_r\) denotes the \(r\)-th elementary non-commutative symmetric function, \(\Psi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the first kind, and \(\Phi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the second kind). For every positive integer \(r\) with \(n \nmid r\), it satisfes

        \[\mathbf{V}_n(S_r) = \mathbf{V}_n(\Lambda_r) = \mathbf{V}_n(\Psi_r) = \mathbf{V}_n(\Phi_r) = 0.\]

        The \(n\)-th Verschiebung operator is also called the \(n\)-th Verschiebung endomorphism.

        It is a lift of the \(n\)-th Verschiebung operator on the ring of symmetric functions (`verschiebung()`) to the ring of noncommutative symmetric functions.

        The action of the \(n\)-th Verschiebung operator can also be described on the ribbon Schur functions. Namely, every composition \(I\) of size \(n \ell\) satisfies

        \[\mathbf{V}_n ( R_I ) = (-1)^{\ell(I) - \ell(J)} \cdot R_{J / n},\]

        where \(J\) denotes the meet of the compositions \(I\) and \((\underbrace{n, n, \ldots, n}_{|I|/n \mbox{ times}})\), where \(\ell(I)\) is the length of \(I\), and where \(J / n\) denotes the composition obtained by dividing every entry of \(J\) by \(n\). For a composition \(I\) of size not divisible by \(n\), we have \(\mathbf{V}_n ( R_I ) = 0\).

        See also

        `verschiebung method of NCSF`, `adams_operator method of QSym`, `verschiebung method of Sym`

        INPUT:

        - `n` – positive integer

        OUTPUT:

        The result of applying the \(n\)-th Verschiebung operator (on the ring of noncommutative symmetric functions) to `self`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: Psi = NSym.Psi()
            sage: Psi([4,2]).verschiebung(2)
            4*Psi[2, 1]
            sage: Psi([2,4]).verschiebung(2)
            4*Psi[1, 2]
            sage: Psi([6]).verschiebung(2)
            2*Psi[3]
            sage: Psi([2,1]).verschiebung(3)
            0
            sage: Psi([3]).verschiebung(2)
            0
            sage: Psi([]).verschiebung(2)
            Psi[]
            sage: Psi([5, 1]).verschiebung(3)
            0
            sage: Psi([5, 1]).verschiebung(6)
            0
            sage: Psi([5, 1]).verschiebung(2)
            0
            sage: Psi([1, 2, 3, 1]).verschiebung(7)
            0
            sage: Psi([7]).verschiebung(7)
            7*Psi[1]
            sage: Psi([1, 2, 3, 1]).verschiebung(5)
            0
            sage: (Psi[1] - Psi[2] + 2*Psi[3]).verschiebung(1)
            Psi[1] - Psi[2] + 2*Psi[3]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> Psi = NSym.Psi()
            >>> Psi([Integer(4),Integer(2)]).verschiebung(Integer(2))
            4*Psi[2, 1]
            >>> Psi([Integer(2),Integer(4)]).verschiebung(Integer(2))
            4*Psi[1, 2]
            >>> Psi([Integer(6)]).verschiebung(Integer(2))
            2*Psi[3]
            >>> Psi([Integer(2),Integer(1)]).verschiebung(Integer(3))
            0
            >>> Psi([Integer(3)]).verschiebung(Integer(2))
            0
            >>> Psi([]).verschiebung(Integer(2))
            Psi[]
            >>> Psi([Integer(5), Integer(1)]).verschiebung(Integer(3))
            0
            >>> Psi([Integer(5), Integer(1)]).verschiebung(Integer(6))
            0
            >>> Psi([Integer(5), Integer(1)]).verschiebung(Integer(2))
            0
            >>> Psi([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(7))
            0
            >>> Psi([Integer(7)]).verschiebung(Integer(7))
            7*Psi[1]
            >>> Psi([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(5))
            0
            >>> (Psi[Integer(1)] - Psi[Integer(2)] + Integer(2)*Psi[Integer(3)]).verschiebung(Integer(1))
            Psi[1] - Psi[2] + 2*Psi[3]

    internal_product_on_basis_by_bracketing(I, J)

      The internal product of two elements of the Psi basis.

      See `internal_product()` for a thorough documentation of this operation.

      This is an implementation using [NCSF2] Lemma 3.10. It is fast when the length of \(I\) is small, but can get very slow otherwise. Therefore it is not being used by default for internally multiplying Psi functions.

      INPUT:

      - `I`, `J` – compositions

      OUTPUT:

      - The internal product of the elements of the Psi basis of \(NSym\) indexed by `I` and `J`, expressed in the Psi basis.

      AUTHORS:

      - Travis Scrimshaw, 29 Mar 2014

      EXAMPLES:

      Sage

          sage: N = NonCommutativeSymmetricFunctions(QQ)
          sage: Psi = N.Psi()
          sage: Psi.internal_product_on_basis_by_bracketing([2,2],[1,2,1])
          0
          sage: Psi.internal_product_on_basis_by_bracketing([1,2,1],[2,1,1])
          4*Psi[1, 2, 1]
          sage: Psi.internal_product_on_basis_by_bracketing([2,1,1],[1,2,1])
          4*Psi[2, 1, 1]
          sage: Psi.internal_product_on_basis_by_bracketing([1,2,1], [1,1,1,1])
          0
          sage: Psi.internal_product_on_basis_by_bracketing([3,1], [1,2,1])
          -Psi[1, 2, 1] + Psi[2, 1, 1]
          sage: Psi.internal_product_on_basis_by_bracketing([1,2,1], [3,1])
          0
          sage: Psi.internal_product_on_basis_by_bracketing([2,2],[1,2])
          0
          sage: Psi.internal_product_on_basis_by_bracketing([4], [1,2,1])
          -Psi[1, 1, 2] + 2*Psi[1, 2, 1] - Psi[2, 1, 1]

      Python

          >>> from sage.all import *
          >>> N = NonCommutativeSymmetricFunctions(QQ)
          >>> Psi = N.Psi()
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(2),Integer(2)],[Integer(1),Integer(2),Integer(1)])
          0
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(1),Integer(2),Integer(1)],[Integer(2),Integer(1),Integer(1)])
          4*Psi[1, 2, 1]
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(2),Integer(1),Integer(1)],[Integer(1),Integer(2),Integer(1)])
          4*Psi[2, 1, 1]
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(1),Integer(2),Integer(1)], [Integer(1),Integer(1),Integer(1),Integer(1)])
          0
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(3),Integer(1)], [Integer(1),Integer(2),Integer(1)])
          -Psi[1, 2, 1] + Psi[2, 1, 1]
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(1),Integer(2),Integer(1)], [Integer(3),Integer(1)])
          0
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(2),Integer(2)],[Integer(1),Integer(2)])
          0
          >>> Psi.internal_product_on_basis_by_bracketing([Integer(4)], [Integer(1),Integer(2),Integer(1)])
          -Psi[1, 1, 2] + 2*Psi[1, 2, 1] - Psi[2, 1, 1]

  R

    alias of `Ribbon`

  class Ribbon(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the Ribbon basis.

    The Ribbon basis is defined in Definition 3.12 of [NCSF1], where it is denoted by \((R_I)_I\). It is connected to the complete basis of the ring of non-commutative symmetric functions by the following relation: For every composition \(I\), we have

    \[R_I = \sum_J (-1)^{\ell(I) - \ell(J)} S^J,\]

    where the sum is over all compositions \(J\) which are coarser than \(I\) and \(\ell(I)\) denotes the length of \(I\). (See the proof of Proposition 4.13 in [NCSF1].)

    The elements of the Ribbon basis are commonly referred to as the ribbon Schur functions.

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: R = NCSF.Ribbon(); R
        Non-Commutative Symmetric Functions over the Rational Field in the Ribbon basis
        sage: R.an_element()
        2*R[] + 2*R[1] + 3*R[1, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> R = NCSF.Ribbon(); R
        Non-Commutative Symmetric Functions over the Rational Field in the Ribbon basis
        >>> R.an_element()
        2*R[] + 2*R[1] + 3*R[1, 1]

    The following are aliases for this basis:

    Sage

        sage: NCSF.ribbon()
        Non-Commutative Symmetric Functions over the Rational Field in the Ribbon basis
        sage: NCSF.R()
        Non-Commutative Symmetric Functions over the Rational Field in the Ribbon basis

    [Python]

        >>> from sage.all import *
        >>> NCSF.ribbon()
        Non-Commutative Symmetric Functions over the Rational Field in the Ribbon basis
        >>> NCSF.R()
        Non-Commutative Symmetric Functions over the Rational Field in the Ribbon basis

    class Element

      Bases: `IndexedFreeModuleElement`

      star_involution()

        Return the image of the noncommutative symmetric function `self` under the star involution.

        The star involution is defined as the algebra antihomomorphism \(NCSF \to NCSF\) which, for every positive integer \(n\), sends the \(n\)-th complete non-commutative symmetric function \(S_n\) to \(S_n\). Denoting by \(f^{\ast}\) the image of an element \(f \in NCSF\) under this star involution, it can be shown that every composition \(I\) satisfies

        \[(S^I)^{\ast} = S^{I^r}, \quad (\Lambda^I)^{\ast} = \Lambda^{I^r}, \quad R_I^{\ast} = R_{I^r}, \quad (\Phi^I)^{\ast} = \Phi^{I^r},\]

        where \(I^r\) denotes the reversed composition of \(I\), and standard notations for classical bases of \(NCSF\) are being used (\(S\) for the complete basis, \(\Lambda\) for the elementary basis, \(R\) for the ribbon basis, and \(\Phi\) for that of the power-sums of the second kind). The star involution is an involution and a coalgebra automorphism of \(NCSF\). It is an automorphism of the graded vector space \(NCSF\). Under the canonical isomorphism between the \(n\)-th graded component of \(NCSF\) and the descent algebra of the symmetric group \(S_n\) (see `to_descent_algebra()`), the star involution (restricted to the \(n\)-th graded component) corresponds to the automorphism of the descent algebra given by \(x \mapsto \omega_n x \omega_n\), where \(\omega_n\) is the permutation \((n, n-1, \ldots, 1) \in S_n\) (written here in one-line notation). If \(\pi\) denotes the projection from \(NCSF\) to the ring of symmetric functions (`to_symmetric_function()`), then \(\pi(f^{\ast}) = \pi(f)\) for every \(f \in NCSF\).

        The star involution on \(NCSF\) is adjoint to the star involution on \(QSym\) by the standard adjunction between \(NCSF\) and \(QSym\).

        The star involution has been denoted by \(\rho\) in [LMvW13], section 3.6. See [NCSF2], section 2.3 for the properties of this map.

        See also

        `star involution of NCSF`, `star involution of QSym`, `psi involution of NCSF`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: R = NSym.R()
            sage: R[3,1,4,2].star_involution()
            R[2, 4, 1, 3]
            sage: R[4,1,2].star_involution()
            R[2, 1, 4]
            sage: (R[1] - R[2] + 2*R[5,4] - 3*R[3] + 4*R[[]]).star_involution()
            4*R[] + R[1] - R[2] - 3*R[3] + 2*R[4, 5]
            sage: (R[3,3] - 21*R[1]).star_involution()
            -21*R[1] + R[3, 3]
            sage: R([14,1]).star_involution()
            R[1, 14]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> R = NSym.R()
            >>> R[Integer(3),Integer(1),Integer(4),Integer(2)].star_involution()
            R[2, 4, 1, 3]
            >>> R[Integer(4),Integer(1),Integer(2)].star_involution()
            R[2, 1, 4]
            >>> (R[Integer(1)] - R[Integer(2)] + Integer(2)*R[Integer(5),Integer(4)] - Integer(3)*R[Integer(3)] + Integer(4)*R[[]]).star_involution()
            4*R[] + R[1] - R[2] - 3*R[3] + 2*R[4, 5]
            >>> (R[Integer(3),Integer(3)] - Integer(21)*R[Integer(1)]).star_involution()
            -21*R[1] + R[3, 3]
            >>> R([Integer(14),Integer(1)]).star_involution()
            R[1, 14]

        The implementation at hand is tailored to the ribbon basis. It is equivalent to the generic implementation via the complete basis:

        Sage

            sage: S = NSym.S()
            sage: all( S(R[I].star_involution()) == S(R[I]).star_involution()
            ....:      for I in Compositions(4) )
            True

        [Python]

            >>> from sage.all import *
            >>> S = NSym.S()
            >>> all( S(R[I].star_involution()) == S(R[I]).star_involution()
            ...      for I in Compositions(Integer(4)) )
            True

      verschiebung(n)

        Return the image of the noncommutative symmetric function `self` under the \(n\)-th Verschiebung operator.

        The \(n\)-th Verschiebung operator \(\mathbf{V}_n\) is defined to be the map from the \(\mathbf{k}\)-algebra of noncommutative symmetric functions to itself that sends the complete function \(S^I\) indexed by a composition \(I = (i_1, i_2, \ldots , i_k)\) to \(S^{(i_1/n, i_2/n, \ldots , i_k/n)}\) if all of the numbers \(i_1, i_2, \ldots, i_k\) are divisible by \(n\), and to \(0\) otherwise. This operator \(\mathbf{V}_n\) is a Hopf algebra endomorphism. For every positive integer \(r\) with \(n \mid r\), it satisfies

        \[\mathbf{V}_n(S_r) = S_{r/n}, \quad \mathbf{V}_n(\Lambda_r) = (-1)^{r - r/n} \Lambda_{r/n}, \quad \mathbf{V}_n(\Psi_r) = n \Psi_{r/n}, \quad \mathbf{V}_n(\Phi_r) = n \Phi_{r/n}\]

        (where \(S_r\) denotes the \(r\)-th complete non-commutative symmetric function, \(\Lambda_r\) denotes the \(r\)-th elementary non-commutative symmetric function, \(\Psi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the first kind, and \(\Phi_r\) denotes the \(r\)-th power-sum non-commutative symmetric function of the second kind). For every positive integer \(r\) with \(n \nmid r\), it satisfes

        \[\mathbf{V}_n(S_r) = \mathbf{V}_n(\Lambda_r) = \mathbf{V}_n(\Psi_r) = \mathbf{V}_n(\Phi_r) = 0.\]

        The \(n\)-th Verschiebung operator is also called the \(n\)-th Verschiebung endomorphism.

        It is a lift of the \(n\)-th Verschiebung operator on the ring of symmetric functions (`verschiebung()`) to the ring of noncommutative symmetric functions.

        The action of the \(n\)-th Verschiebung operator can also be described on the ribbon Schur functions. Namely, every composition \(I\) of size \(n \ell\) satisfies

        \[\mathbf{V}_n ( R_I ) = (-1)^{\ell(I) - \ell(J)} \cdot R_{J / n},\]

        where \(J\) denotes the meet of the compositions \(I\) and \((\underbrace{n, n, \ldots, n}_{|I|/n \mbox{ times}})\), where \(\ell(I)\) is the length of \(I\), and where \(J / n\) denotes the composition obtained by dividing every entry of \(J\) by \(n\). For a composition \(I\) of size not divisible by \(n\), we have \(\mathbf{V}_n ( R_I ) = 0\).

        See also

        `verschiebung method of NCSF`, `adams_operator method of QSym`, `verschiebung method of Sym`

        INPUT:

        - `n` – positive integer

        OUTPUT:

        The result of applying the \(n\)-th Verschiebung operator (on the ring of noncommutative symmetric functions) to `self`.

        EXAMPLES:

        Sage

            sage: NSym = NonCommutativeSymmetricFunctions(ZZ)
            sage: R = NSym.R()
            sage: R([4,2]).verschiebung(2)
            R[2, 1]
            sage: R([2,1]).verschiebung(3)
            -R[1]
            sage: R([3]).verschiebung(2)
            0
            sage: R([]).verschiebung(2)
            R[]
            sage: R([5, 1]).verschiebung(3)
            -R[2]
            sage: R([5, 1]).verschiebung(6)
            -R[1]
            sage: R([5, 1]).verschiebung(2)
            -R[3]
            sage: R([1, 2, 3, 1]).verschiebung(7)
            -R[1]
            sage: R([1, 2, 3, 1]).verschiebung(5)
            0
            sage: (R[1] - R[2] + 2*R[3]).verschiebung(1)
            R[1] - R[2] + 2*R[3]

        Python

            >>> from sage.all import *
            >>> NSym = NonCommutativeSymmetricFunctions(ZZ)
            >>> R = NSym.R()
            >>> R([Integer(4),Integer(2)]).verschiebung(Integer(2))
            R[2, 1]
            >>> R([Integer(2),Integer(1)]).verschiebung(Integer(3))
            -R[1]
            >>> R([Integer(3)]).verschiebung(Integer(2))
            0
            >>> R([]).verschiebung(Integer(2))
            R[]
            >>> R([Integer(5), Integer(1)]).verschiebung(Integer(3))
            -R[2]
            >>> R([Integer(5), Integer(1)]).verschiebung(Integer(6))
            -R[1]
            >>> R([Integer(5), Integer(1)]).verschiebung(Integer(2))
            -R[3]
            >>> R([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(7))
            -R[1]
            >>> R([Integer(1), Integer(2), Integer(3), Integer(1)]).verschiebung(Integer(5))
            0
            >>> (R[Integer(1)] - R[Integer(2)] + Integer(2)*R[Integer(3)]).verschiebung(Integer(1))
            R[1] - R[2] + 2*R[3]

    antipode_on_basis(composition)

      Return the application of the antipode to a basis element of the ribbon basis `self`.

      INPUT:

      - `composition` – a composition

      OUTPUT:

      - The image of the basis element indexed by `composition` under the antipode map.

      EXAMPLES:

      Sage

          sage: R = NonCommutativeSymmetricFunctions(QQ).ribbon()
          sage: R.antipode_on_basis(Composition([2,1]))
          -R[2, 1]
          sage: R[3,1].antipode() # indirect doctest
          R[2, 1, 1]
          sage: R[[]].antipode() # indirect doctest
          R[]

      Python

          >>> from sage.all import *
          >>> R = NonCommutativeSymmetricFunctions(QQ).ribbon()
          >>> R.antipode_on_basis(Composition([Integer(2),Integer(1)]))
          -R[2, 1]
          >>> R[Integer(3),Integer(1)].antipode() # indirect doctest
          R[2, 1, 1]
          >>> R[[]].antipode() # indirect doctest
          R[]

      We check that the implementation of the antipode at hand does not contradict the generic one:

      Sage

          sage: S = NonCommutativeSymmetricFunctions(QQ).S()
          sage: all( S(R[I].antipode()) == S(R[I]).antipode()
          ....:      for I in Compositions(4) )
          True

      [Python]

          >>> from sage.all import *
          >>> S = NonCommutativeSymmetricFunctions(QQ).S()
          >>> all( S(R[I].antipode()) == S(R[I]).antipode()
          ...      for I in Compositions(Integer(4)) )
          True

    dual()

      Return the dual basis to the ribbon basis of the non-commutative symmetric functions. This is the Fundamental basis of the quasi-symmetric functions.

      OUTPUT: the fundamental basis of the quasi-symmetric functions

      EXAMPLES:

      Sage

          sage: R = NonCommutativeSymmetricFunctions(QQ).ribbon()
          sage: R.dual()
          Quasisymmetric functions over the Rational Field in the Fundamental basis

      Python

          >>> from sage.all import *
          >>> R = NonCommutativeSymmetricFunctions(QQ).ribbon()
          >>> R.dual()
          Quasisymmetric functions over the Rational Field in the Fundamental basis

    product_on_basis(I, J)

      Return the product of two ribbon basis elements of the non-commutative symmetric functions.

      INPUT:

      - `I`, `J` – compositions

      OUTPUT: the product of the ribbon functions indexed by `I` and `J`

      EXAMPLES:

      Sage

          sage: R = NonCommutativeSymmetricFunctions(QQ).ribbon()
          sage: R[1,2,1] * R[3,1]
          R[1, 2, 1, 3, 1] + R[1, 2, 4, 1]
          sage: ( R[1,2] + R[3] ) * ( R[3,1] + R[1,2,1] )
          R[1, 2, 1, 2, 1] + R[1, 2, 3, 1] + R[1, 3, 2, 1] + R[1, 5, 1] + R[3, 1, 2, 1] + R[3, 3, 1] + R[4, 2, 1] + R[6, 1]

      Python

          >>> from sage.all import *
          >>> R = NonCommutativeSymmetricFunctions(QQ).ribbon()
          >>> R[Integer(1),Integer(2),Integer(1)] * R[Integer(3),Integer(1)]
          R[1, 2, 1, 3, 1] + R[1, 2, 4, 1]
          >>> ( R[Integer(1),Integer(2)] + R[Integer(3)] ) * ( R[Integer(3),Integer(1)] + R[Integer(1),Integer(2),Integer(1)] )
          R[1, 2, 1, 2, 1] + R[1, 2, 3, 1] + R[1, 3, 2, 1] + R[1, 5, 1] + R[3, 1, 2, 1] + R[3, 3, 1] + R[4, 2, 1] + R[6, 1]

    to_symmetric_function_on_basis(I)

      Return the commutative image of a ribbon basis element of the non-commutative symmetric functions.

      INPUT:

      - `I` – a composition

      OUTPUT:

      - The commutative image of the ribbon basis element indexed by `I`. This will be expressed as a symmetric function in the Schur basis.

      EXAMPLES:

      Sage

          sage: R = NonCommutativeSymmetricFunctions(QQ).R()
          sage: R.to_symmetric_function_on_basis(Composition([3,1,1]))
          s[3, 1, 1]
          sage: R.to_symmetric_function_on_basis(Composition([4,2,1]))
          s[4, 2, 1] + s[5, 1, 1] + s[5, 2]
          sage: R.to_symmetric_function_on_basis(Composition([]))
          s[]

      Python

          >>> from sage.all import *
          >>> R = NonCommutativeSymmetricFunctions(QQ).R()
          >>> R.to_symmetric_function_on_basis(Composition([Integer(3),Integer(1),Integer(1)]))
          s[3, 1, 1]
          >>> R.to_symmetric_function_on_basis(Composition([Integer(4),Integer(2),Integer(1)]))
          s[4, 2, 1] + s[5, 1, 1] + s[5, 2]
          >>> R.to_symmetric_function_on_basis(Composition([]))
          s[]

  S

    alias of `Complete`

  ZL

    alias of `Zassenhaus_left`

  ZR

    alias of `Zassenhaus_right`

  class Zassenhaus_left(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the left Zassenhaus basis.

    This basis is the left-version of the basis defined in Section 2.5.1 of [HLNT09]. It is multiplicative, with \(Z_n\) defined as the element of \(NCSF_n\) satisfying the equation

    \[\sigma_1 = \cdots exp(Z_n) \cdots exp(Z_2) exp(Z_1),\]

    where

    \[\sigma_1 = \sum_{n \geq 0} S_n .\]

    It can be recursively computed by the formula

    \[S_n = \sum_{\lambda \vdash n} \frac{1}{m_1(\lambda)! m_2(\lambda)! m_3(\lambda)! \cdots} Z_{\lambda_1} Z_{\lambda_2} Z_{\lambda_3} \cdots\]

    for all \(n \geq 0\).

  class Zassenhaus_right(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The Hopf algebra of non-commutative symmetric functions in the right Zassenhaus basis.

    This basis is defined in Section 2.5.1 of [HLNT09]. It is multiplicative, with \(Z_n\) defined as the element of \(NCSF_n\) satisfying the equation

    \[\sigma_1 = exp(Z_1) exp(Z_2) exp(Z_3) \cdots exp(Z_n) \cdots\]

    where

    \[\sigma_1 = \sum_{n \geq 0} S_n .\]

    It can be recursively computed by the formula

    \[S_n = \sum_{\lambda \vdash n} \frac{1}{m_1(\lambda)! m_2(\lambda)! m_3(\lambda)! \cdots} \cdots Z_{\lambda_3} Z_{\lambda_2} Z_{\lambda_1}\]

    for all \(n \geq 0\).

    Note that there is a variant (called the “noncommutative power sum symmetric functions of the third kind”) in Definition 5.26 of [NCSF2] that satisfies:

    \[\sigma_1 = exp(Z_1) exp(Z_2/2) exp(Z_3/3) \cdots exp(Z_n/n) \cdots.\]
  a_realization()

    Give a realization of the algebra of non-commutative symmetric functions. This particular realization is the complete basis of non-commutative symmetric functions.

    OUTPUT:

    - The realization of the non-commutative symmetric functions in the complete basis.

    EXAMPLES:

    Sage

        sage: NonCommutativeSymmetricFunctions(ZZ).a_realization()
        Non-Commutative Symmetric Functions over the Integer Ring in the Complete basis

    Python

        >>> from sage.all import *
        >>> NonCommutativeSymmetricFunctions(ZZ).a_realization()
        Non-Commutative Symmetric Functions over the Integer Ring in the Complete basis

  complete

    alias of `Complete`

  dQS

    alias of `dualQuasisymmetric_Schur`

  dYQS

    alias of `dualYoungQuasisymmetric_Schur`

  dual()

    Return the dual to the non-commutative symmetric functions.

    OUTPUT:

    - The dual of the non-commutative symmetric functions over a ring. This is the algebra of quasi-symmetric functions over the ring.

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: NCSF.dual()
        Quasisymmetric functions over the Rational Field

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> NCSF.dual()
        Quasisymmetric functions over the Rational Field

  class dualQuasisymmetric_Schur(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The basis of NCSF dual to the Quasisymmetric-Schur basis of QSym.

    The `Quasisymmetric_Schur` functions are defined in [QSCHUR] (see also Definition 5.1.1 of [LMvW13]). The dual basis in the algebra of non-commutative symmetric functions is defined by the following formula:

    \[R_\alpha = \sum_{T} dQS_{shape(T)},\]

    where the sum is over all standard composition tableaux with descent composition equal to \(\alpha\). The `Quasisymmetric_Schur` basis \(QS_\alpha\) has the property that

    \[s_\lambda = \sum_{sort(\alpha) = \lambda} QS_\alpha.\]

    As a consequence the commutative image of a dual Quasisymmetric-Schur element in the algebra of symmetric functions (the map defined in the method `to_symmetric_function()`) is equal to the Schur function indexed by the decreasing sort of the indexing composition.

    See also

    `CompositionTableaux`, `CompositionTableau`.

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: dQS = NCSF.dQS()
        sage: dQS([1,3,2])*dQS([1])
        dQS[1, 2, 4] + dQS[1, 3, 2, 1] + dQS[1, 3, 3] + dQS[3, 2, 2]
        sage: dQS([1])*dQS([1,3,2])
        dQS[1, 1, 3, 2] + dQS[1, 3, 3] + dQS[1, 4, 2] + dQS[2, 3, 2]
        sage: dQS([1,3])*dQS([1,1])
        dQS[1, 3, 1, 1] + dQS[1, 4, 1] + dQS[3, 2, 1] + dQS[4, 2]
        sage: dQS([3,1])*dQS([2,1])
        dQS[1, 1, 4, 1] + dQS[1, 4, 2] + dQS[1, 5, 1] + dQS[2, 4, 1] + dQS[3, 1,
        2, 1] + dQS[3, 2, 2] + dQS[3, 3, 1] + dQS[4, 3] + dQS[5, 2]
        sage: dQS([1,1]).coproduct()
        dQS[] # dQS[1, 1] + dQS[1] # dQS[1] + dQS[1, 1] # dQS[]
        sage: dQS([3,3]).coproduct().monomial_coefficients()[(Composition([1,2]),Composition([1,2]))]
        -1
        sage: S = NCSF.complete()
        sage: dQS(S[1,3,1])
        dQS[1, 3, 1] + dQS[1, 4] + dQS[3, 2] + dQS[4, 1] + dQS[5]
        sage: S(dQS[1,3,1])
        S[1, 3, 1] - S[3, 2] - S[4, 1] + S[5]
        sage: s = SymmetricFunctions(QQ).s()
        sage: s(S(dQS([2,1,3])).to_symmetric_function())
        s[3, 2, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> dQS = NCSF.dQS()
        >>> dQS([Integer(1),Integer(3),Integer(2)])*dQS([Integer(1)])
        dQS[1, 2, 4] + dQS[1, 3, 2, 1] + dQS[1, 3, 3] + dQS[3, 2, 2]
        >>> dQS([Integer(1)])*dQS([Integer(1),Integer(3),Integer(2)])
        dQS[1, 1, 3, 2] + dQS[1, 3, 3] + dQS[1, 4, 2] + dQS[2, 3, 2]
        >>> dQS([Integer(1),Integer(3)])*dQS([Integer(1),Integer(1)])
        dQS[1, 3, 1, 1] + dQS[1, 4, 1] + dQS[3, 2, 1] + dQS[4, 2]
        >>> dQS([Integer(3),Integer(1)])*dQS([Integer(2),Integer(1)])
        dQS[1, 1, 4, 1] + dQS[1, 4, 2] + dQS[1, 5, 1] + dQS[2, 4, 1] + dQS[3, 1,
        2, 1] + dQS[3, 2, 2] + dQS[3, 3, 1] + dQS[4, 3] + dQS[5, 2]
        >>> dQS([Integer(1),Integer(1)]).coproduct()
        dQS[] # dQS[1, 1] + dQS[1] # dQS[1] + dQS[1, 1] # dQS[]
        >>> dQS([Integer(3),Integer(3)]).coproduct().monomial_coefficients()[(Composition([Integer(1),Integer(2)]),Composition([Integer(1),Integer(2)]))]
        -1
        >>> S = NCSF.complete()
        >>> dQS(S[Integer(1),Integer(3),Integer(1)])
        dQS[1, 3, 1] + dQS[1, 4] + dQS[3, 2] + dQS[4, 1] + dQS[5]
        >>> S(dQS[Integer(1),Integer(3),Integer(1)])
        S[1, 3, 1] - S[3, 2] - S[4, 1] + S[5]
        >>> s = SymmetricFunctions(QQ).s()
        >>> s(S(dQS([Integer(2),Integer(1),Integer(3)])).to_symmetric_function())
        s[3, 2, 1]

    dual()

      The dual basis to the dual Quasisymmetric-Schur basis of NCSF.

      The basis returned is the `Quasisymmetric_Schur` basis of QSym.

      OUTPUT: the Quasisymmetric-Schur basis of the quasi-symmetric functions

      EXAMPLES:

      Sage

          sage: dQS=NonCommutativeSymmetricFunctions(QQ).dualQuasisymmetric_Schur()
          sage: dQS.dual()
          Quasisymmetric functions over the Rational Field in the Quasisymmetric
          Schur basis
          sage: dQS.duality_pairing_matrix(dQS.dual(),3)
          [1 0 0 0]
          [0 1 0 0]
          [0 0 1 0]
          [0 0 0 1]

      Python

          >>> from sage.all import *
          >>> dQS=NonCommutativeSymmetricFunctions(QQ).dualQuasisymmetric_Schur()
          >>> dQS.dual()
          Quasisymmetric functions over the Rational Field in the Quasisymmetric
          Schur basis
          >>> dQS.duality_pairing_matrix(dQS.dual(),Integer(3))
          [1 0 0 0]
          [0 1 0 0]
          [0 0 1 0]
          [0 0 0 1]

    to_symmetric_function_on_basis(I)

      The commutative image of a dual quasi-symmetric Schur element.

      The commutative image of a basis element is obtained by sorting the indexing composition of the basis element.

      INPUT:

      - `I` – a composition

      OUTPUT:

      - The commutative image of the dual quasi-Schur basis element indexed by `I`. The result is the Schur symmetric function indexed by the partition obtained by sorting `I`.

      EXAMPLES:

      Sage

          sage: dQS=NonCommutativeSymmetricFunctions(QQ).dQS()
          sage: dQS.to_symmetric_function_on_basis([2,1,3])
          s[3, 2, 1]
          sage: dQS.to_symmetric_function_on_basis([])
          s[]

      Python

          >>> from sage.all import *
          >>> dQS=NonCommutativeSymmetricFunctions(QQ).dQS()
          >>> dQS.to_symmetric_function_on_basis([Integer(2),Integer(1),Integer(3)])
          s[3, 2, 1]
          >>> dQS.to_symmetric_function_on_basis([])
          s[]

  class dualYoungQuasisymmetric_Schur(NCSF)

    Bases: `CombinatorialFreeModule`, `BindableClass`

    The basis of NCSF dual to the Young Quasisymmetric-Schur basis of QSym.

    The `YoungQuasisymmetric_Schur` functions are given in Definition 5.2.1 of [LMvW13]. The dual basis in the algebra of non-commutative symmetric functions are related by an involution reversing the indexing composition of the complete expansion of a quasi-Schur basis element. This basis has many of the same properties as the Quasisymmetric Schur basis and is related to that basis by an algebraic transformation.

    EXAMPLES:

    Sage

        sage: NCSF = NonCommutativeSymmetricFunctions(QQ)
        sage: dYQS = NCSF.dYQS()
        sage: dYQS([1,3,2])*dYQS([1])
        dYQS[1, 3, 2, 1] + dYQS[1, 3, 3] + dYQS[1, 4, 2] + dYQS[2, 3, 2]
        sage: dYQS([1])*dYQS([1,3,2])
        dYQS[1, 1, 3, 2] + dYQS[2, 3, 2] + dYQS[3, 3, 1] + dYQS[4, 1, 2]
        sage: dYQS([1,3])*dYQS([1,1])
        dYQS[1, 3, 1, 1] + dYQS[1, 4, 1] + dYQS[2, 3, 1] + dYQS[2, 4]
        sage: dYQS([3,1])*dYQS([2,1])
        dYQS[3, 1, 2, 1] + dYQS[3, 2, 2] + dYQS[3, 3, 1] + dYQS[4, 1, 1, 1]
         + dYQS[4, 1, 2] + dYQS[4, 2, 1] + dYQS[4, 3] + dYQS[5, 1, 1]
         + dYQS[5, 2]
        sage: dYQS([1,1]).coproduct()
        dYQS[] # dYQS[1, 1] + dYQS[1] # dYQS[1] + dYQS[1, 1] # dYQS[]
        sage: dYQS([3,3]).coproduct().monomial_coefficients()[(Composition([1,2]),Composition([2,1]))]
        1
        sage: S = NCSF.complete()
        sage: dYQS(S[1,3,1])
        dYQS[1, 3, 1] + dYQS[1, 4] + dYQS[2, 3] + dYQS[4, 1] + dYQS[5]
        sage: S(dYQS[1,3,1])
        S[1, 3, 1] - S[1, 4] - S[2, 3] + S[5]
        sage: s = SymmetricFunctions(QQ).s()
        sage: s(S(dYQS([2,1,3])).to_symmetric_function())
        s[3, 2, 1]

    Python

        >>> from sage.all import *
        >>> NCSF = NonCommutativeSymmetricFunctions(QQ)
        >>> dYQS = NCSF.dYQS()
        >>> dYQS([Integer(1),Integer(3),Integer(2)])*dYQS([Integer(1)])
        dYQS[1, 3, 2, 1] + dYQS[1, 3, 3] + dYQS[1, 4, 2] + dYQS[2, 3, 2]
        >>> dYQS([Integer(1)])*dYQS([Integer(1),Integer(3),Integer(2)])
        dYQS[1, 1, 3, 2] + dYQS[2, 3, 2] + dYQS[3, 3, 1] + dYQS[4, 1, 2]
        >>> dYQS([Integer(1),Integer(3)])*dYQS([Integer(1),Integer(1)])
        dYQS[1, 3, 1, 1] + dYQS[1, 4, 1] + dYQS[2, 3, 1] + dYQS[2, 4]
        >>> dYQS([Integer(3),Integer(1)])*dYQS([Integer(2),Integer(1)])
        dYQS[3, 1, 2, 1] + dYQS[3, 2, 2] + dYQS[3, 3, 1] + dYQS[4, 1, 1, 1]
         + dYQS[4, 1, 2] + dYQS[4, 2, 1] + dYQS[4, 3] + dYQS[5, 1, 1]
         + dYQS[5, 2]
        >>> dYQS([Integer(1),Integer(1)]).coproduct()
        dYQS[] # dYQS[1, 1] + dYQS[1] # dYQS[1] + dYQS[1, 1] # dYQS[]
        >>> dYQS([Integer(3),Integer(3)]).coproduct().monomial_coefficients()[(Composition([Integer(1),Integer(2)]),Composition([Integer(2),Integer(1)]))]
        1
        >>> S = NCSF.complete()
        >>> dYQS(S[Integer(1),Integer(3),Integer(1)])
        dYQS[1, 3, 1] + dYQS[1, 4] + dYQS[2, 3] + dYQS[4, 1] + dYQS[5]
        >>> S(dYQS[Integer(1),Integer(3),Integer(1)])
        S[1, 3, 1] - S[1, 4] - S[2, 3] + S[5]
        >>> s = SymmetricFunctions(QQ).s()
        >>> s(S(dYQS([Integer(2),Integer(1),Integer(3)])).to_symmetric_function())
        s[3, 2, 1]

    dual()

      The dual basis to the dual Quasisymmetric-Schur basis of NCSF.

      The basis returned is the `Quasisymmetric_Schur` basis of QSym.

      OUTPUT: the Young Quasisymmetric-Schur basis of quasi-symmetric functions

      EXAMPLES:

      Sage

          sage: dYQS=NonCommutativeSymmetricFunctions(QQ).dualYoungQuasisymmetric_Schur()
          sage: dYQS.dual()
          Quasisymmetric functions over the Rational Field in the Young
          Quasisymmetric Schur basis
          sage: dYQS.duality_pairing_matrix(dYQS.dual(),3)
          [1 0 0 0]
          [0 1 0 0]
          [0 0 1 0]
          [0 0 0 1]

      Python

          >>> from sage.all import *
          >>> dYQS=NonCommutativeSymmetricFunctions(QQ).dualYoungQuasisymmetric_Schur()
          >>> dYQS.dual()
          Quasisymmetric functions over the Rational Field in the Young
          Quasisymmetric Schur basis
          >>> dYQS.duality_pairing_matrix(dYQS.dual(),Integer(3))
          [1 0 0 0]
          [0 1 0 0]
          [0 0 1 0]
          [0 0 0 1]

    to_symmetric_function_on_basis(I)

      The commutative image of a dual Young quasi-symmetric Schur element.

      The commutative image of a basis element is obtained by sorting the indexing composition of the basis element.

      INPUT:

      - `I` – a composition

      OUTPUT:

      - The commutative image of the dual Young quasi-Schur basis element indexed by `I`. The result is the Schur symmetric function indexed by the partition obtained by sorting `I`.

      EXAMPLES:

      Sage

          sage: dYQS=NonCommutativeSymmetricFunctions(QQ).dYQS()
          sage: dYQS.to_symmetric_function_on_basis([2,1,3])
          s[3, 2, 1]
          sage: dYQS.to_symmetric_function_on_basis([])
          s[]

      Python

          >>> from sage.all import *
          >>> dYQS=NonCommutativeSymmetricFunctions(QQ).dYQS()
          >>> dYQS.to_symmetric_function_on_basis([Integer(2),Integer(1),Integer(3)])
          s[3, 2, 1]
          >>> dYQS.to_symmetric_function_on_basis([])
          s[]

  elementary

    alias of `Elementary`

  monomial

    alias of `Monomial`

  nM

    alias of `Monomial`

  ribbon

    alias of `Ribbon`