# HG changeset patch
# User Travis Scrimshaw
# Date 1362169656 28800
# Node ID 150d27ffba76327f76023478cee7addf5b690dc8
# Parent b7d846049591f3fb81f8be2f0bd981e7ca85698d
#14111: Review patch for QSym tutorial.
diff git a/sage/combinat/ncsf_qsym/__init__.py b/sage/combinat/ncsf_qsym/__init__.py
 a/sage/combinat/ncsf_qsym/__init__.py
+++ b/sage/combinat/ncsf_qsym/__init__.py
@@ 1,1 +0,0 @@
import tutorial
diff git a/sage/combinat/ncsf_qsym/tutorial.py b/sage/combinat/ncsf_qsym/tutorial.py
old mode 100755
new mode 100644
 a/sage/combinat/ncsf_qsym/tutorial.py
+++ b/sage/combinat/ncsf_qsym/tutorial.py
@@ 1,30 +1,26 @@
1# * coding: utf8 *
+# * coding: utf8 *
r"""
=====================================
Tutorial for Quasisymmetric Functions
=====================================
+Introduction to Quasisymmetric Functions
In this document we briefly explain the quasisymmetric function bases and related functionality in Sage. We assume the reader is familar with the package
:class:`SymmetricFunctions`
+In this document we briefly explain the quasisymmetric function bases and
+related functionality in Sage. We assume the reader is familar with the
+package :class:`SymmetricFunctions`.
Quasisymmetric functions, denoted QSym, form a subring of the power
series ring in countably many variables. QSym contains the symmetric
+Quasisymmetric functions, denoted `QSym`, form a subring of the power
+series ring in countably many variables. `QSym` contains the symmetric
functions. These functions first arose in the theory of
$P$partitions. The initial ideas in this field are attributed to
MacMahon, Knuth, Kreweras, Glâffrwd Thomas, Stanley. In 1984, Gessel
+`P`partitions. The initial ideas in this field are attributed to
+MacMahon, Knuth, Kreweras, Glâffrwd Thomas, Stanley. In 1984, Gessel
formalized the study of quasisymmetric functions and introduced the
basis of fundamental quasisymmetric functions. In 1995, Gelfand,
+basis of fundamental quasisymmetric functions [Ges]_. In 1995, Gelfand,
Krob, Lascoux, Leclerc, Retakh, and Thibon showed that the ring of
quasisymmetric functions is Hopf dual to the noncommutative symmetric
functions. Many results have built on these.
+functions [NCSF]_. Many results have built on these.


One advantage of working in QSym is that many
interesting families of symmetric functions have explicit expansions
in fundamental quasisymmetric functions such as Schur functions
[Ges]_, Macdonald polynomials [HaimanHaglundLoehr], and plethysm of
Schur functions [LoehrWarrington].
+One advantage of working in `QSym` is that many interesting families of
+symmetric functions have explicit expansions in fundamental quasisymmetric
+functions such as Schur functions [Ges]_, Macdonald polynomials
+[HHL05]_, and plethysm of Schur functions [LW12]_.
For more background see :wikipedia:`Quasisymmetric_function`.
@@ 41,12 +37,12 @@ numbers `\QQ`. Other options include th
sage: QSym = QuasiSymmetricFunctions(ZZ); QSym
Quasisymmetric functions over the Integer Ring
All bases of QSym are indexed by compositions e.g. `[3,1,1,4]`. The
convention is to use capitol letters for bases of QSym and lowercase
letters for bases of Sym. Next set up names for the known bases by running
:meth:`QuasiSymmetricFunctions.inject_shorthands`.
As with symmetric functions, you do not need to run this commmand and
you could assign these bases other names. ::
+All bases of `QSym` are indexed by compositions e.g. `[3,1,1,4]`. The
+convention is to use capitol letters for bases of `QSym` and lowercase
+letters for bases of the symmetric functions `Sym`. Next set up names for the
+known bases by running ``inject_shorthands()``. As with symmetric functions,
+you do not need to run this commmand and you could assign these bases other
+names. ::
sage: QSym = QuasiSymmetricFunctions(QQ)
sage: QSym.inject_shorthands()
@@ 54,26 +50,31 @@ you could assign these bases other names
Injecting F as shorthand for Quasisymmetric functions over the Rational Field in the Fundamental basis
Injecting dI as shorthand for Quasisymmetric functions over the Rational Field in the dualImmaculate basis
+Now one can start constructing quasisymmetric functions.
Now one can start constructing quasisymmetric functions. Note, it is best to use variables other than M,F. ::
+.. NOTE::
 sage: x = M[2,1]+M[1,2]
+ It is best to use variables other than ``M`` and ``F``.
+
+::
+
+ sage: x = M[2,1] + M[1,2]
sage: x
M[1, 2] + M[2, 1]
 sage: y=3*M[1,2]+M[3]^2; y
+ sage: y = 3*M[1,2] + M[3]^2; y
3*M[1, 2] + 2*M[3, 3] + M[6]
 sage: F[3,1,3]+7*F[2,1]
+ sage: F[3,1,3] + 7*F[2,1]
7*F[2, 1] + F[3, 1, 3]
 sage: 3*F[2,1,2]+F[3]^2
 F[1, 2, 2, 1] + F[1, 2, 3] + 2*F[1, 3, 2] + F[1, 4, 1] + F[1, 5] + 3*F[2, 1, 2] + 2*F[2, 2, 2] + 2*F[2, 3, 1] + 2*F[2, 4] + F[3, 2, 1] + 3*F[3, 3] + 2*F[4, 2] + F[5, 1] + F[6]
+ sage: 3*F[2,1,2] + F[3]^2
+ F[1, 2, 2, 1] + F[1, 2, 3] + 2*F[1, 3, 2] + F[1, 4, 1] + F[1, 5] + 3*F[2, 1, 2]
+ + 2*F[2, 2, 2] + 2*F[2, 3, 1] + 2*F[2, 4] + F[3, 2, 1] + 3*F[3, 3] + 2*F[4, 2] + F[5, 1] + F[6]
To convert from one basis to another is easy::

 sage: z=M[1,2,1]
+ sage: z = M[1,2,1]
sage: z
M[1, 2, 1]
@@ 83,13 +84,15 @@ To convert from one basis to another is
sage: M(F(z))
M[1, 2, 1]
To expand in variables, one can specify a finite size alphabet $x_1,x_2,\ldots, x_m$. ::
+To expand in variables, one can specify a finite size alphabet `x_1, x_2,
+\ldots, x_m`::
 sage: y=M[1,2,1]
+ sage: y = M[1,2,1]
sage: y.expand(4)
x0*x1^2*x2 + x0*x1^2*x3 + x0*x2^2*x3 + x1*x2^2*x3
The usual methods on free modules are available such as coefficients, degrees, and the support. ::
+The usual methods on free modules are available such as coefficients, degrees,
+and the support::
sage: z=3*M[1,2]+M[3]^2; z
3*M[1, 2] + 2*M[3, 3] + M[6]
@@ 109,11 +112,11 @@ The usual methods on free modules are av
sage: z.monomial_coefficients()
{[3, 3]: 2, [1, 2]: 3, [6]: 1}
As with the symmetric functions package, the quasisymmetric function 1
has several instantiations. However, the most obvious way to write 1
leads to an error::
+As with the symmetric functions package, the quasisymmetric function ``1``
+has several instantiations. However, the most obvious way to write ``1``
+leads to an error (this is due to the semantics of python)::
 sage: M[[]]
+ sage: M[[]]
M[]
sage: M.one()
M[]
@@ 133,7 +136,7 @@ Working with symmetric functions
The quasisymmetric functions are a ring which contains the symmetric
functions as a subring. The Monomial quasisymmetric functions are
related to the monomial symmetric functions by `m_\lambda =
\sum_{sort(c) = \lambda} M_c~`::
+\sum_{sort(c) = \lambda} M_c`::
sage: SymmetricFunctions(QQ).inject_shorthands()
doctest:1075: RuntimeWarning: redefining global value `e`
@@ 145,22 +148,25 @@ related to the monomial symmetric functi
sage: M(s[2,1])
2*M[1, 1, 1] + M[1, 2] + M[2, 1]
There are methods to test if an expression in the quasisymmetric functions is a symmetric
function and, if it is, send it to an expression in the symmetric functions.
::
+There are methods to test if an expression `f` in the quasisymmetric functions
+is a symmetric function::
sage: f = M[1,1,2] + M[1,2,1]
sage: f.is_symmetric()
False
 sage: g = M[3,1] + M[1,3]
 sage: g.is_symmetric()
+ sage: f = M[3,1] + M[1,3]
+ sage: f.is_symmetric()
True
 sage: g.to_symmetric_function()
+
+If `f` is symmetric, there are methods to convert `f` to an expression in the
+symmetric functions::
+
+ sage: f.to_symmetric_function()
m[3, 1]
The expansion of the Schur function in terms of the Fundamental quasisymmetric
functions is due to [Ges]_. There is one term in the expansion for each standard
tableau of shape equal to the partition indexing the Schur function.
+functions is due to [Ges]_. There is one term in the expansion for each
+standard tableau of shape equal to the partition indexing the Schur function.
::
sage: f = F[3,2] + F[2,2,1] + F[2,3] + F[1,3,1] + F[1,2,2]
@@ 171,8 +177,8 @@ tableau of shape equal to the partition
sage: s(f.to_symmetric_function())
s[3, 2]
It is also possible to convert any symmetric function to the quasisymmetric function expansion in any known basis. The converse is not true
::
+It is also possible to convert any symmetric function to the quasisymmetric
+function expansion in any known basis. The converse is not true::
sage: M( m[3,1,1] )
M[1, 1, 3] + M[1, 3, 1] + M[3, 1, 1]
@@ 204,15 +210,14 @@ bases, but it is important that the base
q*t*F[1, 1, 1] + (q+t)*F[1, 2] + (q+t)*F[2, 1] + F[3]
The following will raise an error because the base ring of ``F`` is not
equal to the base ring of ``Ht``
::
+equal to the base ring of ``Ht``::
sage: F(Ht[2,1])
Traceback (most recent call last):
 ...
+ ...
TypeError: do not know how to make x (= McdHt[2, 1]) an element of self (=Quasisymmetric functions over the Rational Field in the Fundamental basis)
QSym is a Hopf algebra
+QSym is a Hopf algebra

The product on this space is commutative and is inherited from the
@@ 230,24 +235,21 @@ product by the realization within the po
F[1, 1, 1, 2]  F[1, 2, 2] + F[2, 1, 1, 1]  F[2, 1, 2]  F[2, 2, 1] + F[5]
There is a coproduct on this ring as well, which in the Monomial basis acts by
cutting the composition into a left half and a right half. The
coproduct is noncocommutative
::
+cutting the composition into a left half and a right half. The coproduct is
+noncocommutative::
sage: M[1,3,1].coproduct()
M[] # M[1, 3, 1] + M[1] # M[3, 1] + M[1, 3] # M[1] + M[1, 3, 1] # M[]
sage: F[1,3,1].coproduct()
F[] # F[1, 3, 1] + F[1] # F[3, 1] + F[1, 1] # F[2, 1] + F[1, 2] # F[1, 1] + F[1, 3] # F[1] + F[1, 3, 1] # F[]
.. rubric:: The duality pairing with noncommutative symmetric functions
+.. rubric:: The Duality Pairing with NonCommutative Symmetric Functions
These two operations endow the quasisymmetric functions `QSym` with the
structure of a Hopf algebra. It is the dual Hopf algebra of the
noncommutative symmetric functions `NCSF`. Under this duality, the
Monomial basis of `QSym` is dual to the Complete basis of `NCSF`, and the
Fundamental basis of `QSym` is dual to the Ribbon basis of `NCSF` (see
[MR]_)
::
+These two operations endow `QSym` with the structure of a Hopf algebra. It is
+the dual Hopf algebra of the noncommutative symmetric functions `NCSF`. Under
+this duality, the Monomial basis of `QSym` is dual to the Complete basis of
+`NCSF`, and the Fundamental basis of `QSym` is dual to the Ribbon basis of
+`NCSF` (see [MR]_)::
sage: S = M.dual(); S
NonCommutative Symmetric Functions over the Rational Field in the Complete basis
@@ 294,9 +296,11 @@ Fundamental basis of `QSym` is dual to t
Let `H` and `G` be elements of `QSym` and `h` an element of `NCSF`. Then if
we represent the duality pairing with the mathematical notation `[ \cdot,
\cdot ]`,
+\cdot ]`, we have:
`[H G, h] = [H \otimes G, \Delta(h)]~.`
+.. MATH::
+
+ [H \cdot G, h] = [H \otimes G, \Delta(h)].
For example, the coefficient of ``M[2,1,4,1]`` in ``M[1,3]*M[2,1,1]`` may be
computed with the duality pairing::
@@ 306,17 +310,17 @@ computed with the duality pairing::
1
And the coefficient of ``S[1,3] # S[2,1,1]`` in ``S[2,1,4,1].coproduct()`` is
equal to this result
::
+equal to this result::
sage: S[2,1,4,1].coproduct()
S[] # S[2, 1, 4, 1] + ... + S[1, 3] # S[2, 1, 1] + ... + S[4, 1] # S[2, 1]
The duality pairing on the tensor space is another way of getting this
coefficient, but currently the method ``duality_pairing`` is not defined on
the tensor squared space. However, we can extend this functionality by
applying a linear morphism to the terms in the coproduct, as follows
::
+coefficient, but currently the method
+:meth:`~sage.combinat.ncsf_qsym.generic_basis_code.BasesOfQSymOrNCSF.ParentMethods.duality_pairing()`
+is not defined on the tensor squared space. However, we can extend this
+functionality by applying a linear morphism to the terms in the coproduct,
+as follows::
sage: X = S[2,1,4,1].coproduct()
sage: def linear_morphism(x, y):
@@ 324,14 +328,15 @@ applying a linear morphism to the terms
sage: X.apply_multilinear_morphism(linear_morphism, codomain=ZZ)
1
Similarly, if `H` is an element of `QSym` and `g` and `h` are elements of `NCSF`,
then
+Similarly, if `H` is an element of `QSym` and `g` and `h` are elements of
+`NCSF`, then
`[ H, g h ] = [ \Delta(H), g \otimes h ]~.`
+.. MATH::
For example, the coefficient of ``R[2,3,1]`` in ``R[2,1]*R[2,1]`` is computed with
the duality pairing by the following command
::
+ [ H, g \cdot h ] = [ \Delta(H), g \otimes h ].
+
+For example, the coefficient of ``R[2,3,1]`` in ``R[2,1]*R[2,1]`` is computed
+with the duality pairing by the following command::
sage: (R[2,1]*R[2,1]).duality_pairing(F[2,3,1])
1
@@ 339,15 +344,13 @@ the duality pairing by the following com
R[2, 1, 2, 1] + R[2, 3, 1]
This coefficient should then be equal to the coefficient of ``F[2,1] # F[2,1]``
in ``F[2,3,1].coproduct()``
::
+in ``F[2,3,1].coproduct()``::
sage: F[2,3,1].coproduct()
F[] # F[2, 3, 1] + ... + F[2, 1] # F[2, 1] + ... + F[2, 3, 1] # F[]
This can also be computed by the duality pairing on the tensor space,
as above
::
+as above::
sage: X = F[2,3,1].coproduct()
sage: def linear_morphism(x, y):
@@ 355,33 +358,34 @@ as above
sage: X.apply_multilinear_morphism(linear_morphism, codomain=ZZ)
1
.. rubric:: The operation adjoint to multiplication by a noncommutative symmetric function
+.. rubric:: The Operation Adjoint to Multiplication by a NonCommutative Symmetric Function
Let `g \in NCSF` and consider the linear endomorphism of `NCSF` defined by
left (respectively, right) multiplication by `g`. Since there is a duality
between `QSym` and `NCSF`, this linear transformation induces an operator
`g^\perp` on `QSym` satisfying
`[ g^\perp(H), h ] = [ H, gh ]~.`
+.. MATH::
+
+ [ g^\perp(H), h ] = [ H, g \cdot h ].
for any noncommutative symmetric function `h`.
This is implemented by the method :meth:`~sage.combinat.ncsf_qsym.generic_basis_code.BasesOfQSymOrNCSF.ElementMethods.skew_by`.
+This is implemented by the method
+:meth:`~sage.combinat.ncsf_qsym.generic_basis_code.BasesOfQSymOrNCSF.ElementMethods.skew_by()`.
Explicitly, if ``H`` is a quasisymmetric function and ``g``
a noncommutative symmetric function, then ``H.skew_by(g)`` and
``H.skew_by(g, side='right')`` are expressions that satisfy
for any noncommutative symmetric function ``h``
+for any noncommutative symmetric function ``h``.
::
H.skew_by(g).duality_pairing(h) == H.duality_pairing(g*h)
H.skew_by(g, side='right').duality_pairing(h) == H.duality_pairing(h*g)
For example, ``M[J].skew_by(S[I])`` is `0` unless the composition ``J``
begins with ``I`` and ``M(J).skew_by(S(I), side='right')`` is `0` unless
the composition ``J`` ends with ``I``

::
+For example, ``M[J].skew_by(S[I])`` is `0` unless the composition `J`
+begins with `I` and ``M(J).skew_by(S(I), side='right')`` is `0` unless
+the composition `J` ends with `I`::
sage: M[3,2,2].skew_by(S[3])
M[2, 2]
@@ 398,8 +402,7 @@ the composition ``J`` ends with ``I``
The antipode sends the Fundamental basis element indexed by the
composition `I` to `1` to the size of `I` times the Fundamental
basis element indexed by the conjugate composition to `I`
::
+basis element indexed by the conjugate composition to `I`::
sage: F[3,2,2].antipode()
F[1, 2, 2, 1, 1]
@@ 416,4 +419,18 @@ We demonstrate here the defining relatio
sage: X.apply_multilinear_morphism(lambda x,y: x.antipode()*y)
0
+REFERENCES:
+
+.. [HHL05] *A combinatorial formula for Macdonald polynomials*.
+ Haiman, Haglund, and Loehr.
+ J. Amer. Math. Soc. 18 (2005), no. 3, 735761.
+
+.. [LW12] *Quasisymmetric expansions of Schurfunction plethysms*.
+ Loehr and Warrington.
+ Proc. Amer. Math. Soc. 140 (2012), no. 4, 11591171.
+
+.. [KT97] *Noncommutative symmetric functions IV: Quantum linear groups and
+ Hecke algebras at* `q = 0`.
+ Krob and Thibon.
+ Journal of Algebraic Combinatorics 6 (1997), 339376.
"""