Trac #34370: Add examples to Schubert polynomials documentation

Add examples to the documentation for Schubert polynomials.

URL: https://trac.sagemath.org/34370
Reported by: tkarn
Ticket author(s): Trevor K. Karn
Reviewer(s): Travis Scrimshaw

src/sage/combinat/schubert_polynomial.py

@@ -1,5 +1,63 @@
 r"""
 Schubert Polynomials
+
+
+See :wikipedia:`Schubert_polynomial` and 
+`SymmetricFunctions.com <https://www.symmetricfunctions.com/schubert.htm#schubert>`_.
+Schubert polynomials are representatives of cohomology classes in flag varieties.
+In `n` variables, they are indexed by permutations `w \in S_n`. They also form
+a basis for the coinvariant ring of the `S_n` action on
+`\ZZ[x_1, x_2, \ldots, x_n]`.
+
+EXAMPLES::
+
+    sage: X = SchubertPolynomialRing(ZZ)
+    sage: w = [1,2,5,4,3];  # a list representing an element of `S_5`
+    sage: X(w)
+    X[1, 2, 5, 4, 3]
+
+This can be expanded in terms of polynomial variables::
+
+    sage: X(w).expand()
+    x0^2*x1 + x0*x1^2 + x0^2*x2 + 2*x0*x1*x2 + x1^2*x2
+     + x0*x2^2 + x1*x2^2 + x0^2*x3 + x0*x1*x3 + x1^2*x3
+     + x0*x2*x3 + x1*x2*x3 + x2^2*x3
+
+We can also convert back from polynomial variables. For example,
+the longest permutation is a single term. In `S_5`, this is the
+element (in one line notation) `w_0 = 54321`::
+
+    sage: w0 = [5,4,3,2,1]
+    sage: R.<x0, x1, x2, x3, x4> = PolynomialRing(ZZ)
+    sage: Sw0 = X(x0^4*x1^3*x2^2*x3);  Sw0
+    X[5, 4, 3, 2, 1]
+
+The polynomials also have the property that if the indexing permutation `w` is
+multiplied by a simple transposition `s_i = (i, i+1)` such that the length of
+`w` is more than the length of `ws_i`, then the Schubert
+polynomial of the permutation `ws_i` is computed by applying the divided
+difference operator :meth:`~SchubertPolynomial_class.divided_difference` to
+the polynomial indexed by `w`. For example, applying the divided difference
+operator `\partial_2` to the Schubert polynomial `\mathfrak{S}_{w_0}`::
+
+    sage: Sw0.divided_difference(2)
+    X[5, 3, 4, 2, 1]
+
+We can also check the properties listed in :wikipedia:`Schubert_polynomial`::
+
+    sage: X([1,2,3,4,5])  # the identity in one-line notation
+    X[1]
+    sage: X([1,3,2,4,5]).expand()  # the transposition swapping 2 and 3
+    x0 + x1
+    sage: X([2,4,5,3,1]).expand()
+    x0^2*x1^2*x2*x3 + x0^2*x1*x2^2*x3 + x0*x1^2*x2^2*x3
+
+    sage: w = [4,5,1,2,3]
+    sage: s = SymmetricFunctions(QQ).schur()
+    sage: s[3,3].expand(2)
+    x0^3*x1^3
+    sage: X(w).expand()
+    x0^3*x1^3
 """
 # ****************************************************************************
 #       Copyright (C) 2007 Mike Hansen <mhansen@gmail.com>,